Metadata-Version: 2.4
Name: pygments-citry
Version: 0.1.0
Summary: Pygments lexer for Citry components: highlights the HTML, JS, and CSS embedded in a component's template/js/css strings
Author-email: Juro Oravec <juraj.oravec.josefson@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://citry.dev
Project-URL: Repository, https://github.com/citry-dev/citry
Project-URL: Changelog, https://github.com/citry-dev/citry/blob/main/packages/py/pygments_citry/CHANGELOG.md
Project-URL: Issues, https://github.com/citry-dev/citry/issues
Keywords: citry,pygments,lexer,syntax highlighting,components,html
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygments>=2.15
Dynamic: license-file

# pygments-citry

A [Pygments](https://pygments.org/) lexer for [Citry](https://citry.dev)
components. It highlights a component the way an editor would: the Python class,
plus the HTML, JavaScript, and CSS embedded in its `template`, `js`, and `css`
string attributes, each in its own language.

Without it, a Citry component in a ` ```python ` block renders the template,
JS script, and CSS stylesheet as flat string literals. With it, a ` ```citry `
block colours the `<c-*>` tags, the `{{ ... }}` interpolation, the embedded
stylesheet, and the embedded script.

## Install

```bash
pip install pygments-citry
```

The package registers a `citry` lexer as a Pygments plugin, so any tool that
resolves lexers by name picks it up once it is installed.

## Use it

On the command line:

```bash
pygmentize -l citry my_component.py
```

In Python:

```python
from pygments import highlight
from pygments.formatters import HtmlFormatter
from pygments.lexers import get_lexer_by_name

lexer = get_lexer_by_name("citry")
html = highlight(source, lexer, HtmlFormatter())
```

In a Markdown site (mkdocs with `pymdownx.highlight` / `pymdownx.superfences`,
or any python-markdown setup that resolves Pygments lexers by name), tag the
fence with `citry`:

````markdown
```citry
from citry import Component

class Welcome(Component):
    template = """
      <div class="card">
        <h1>{{ title }}</h1>
        <p c-if="count">You have {{ count }} new messages.</p>
      </div>
    """
```
````

No superfences `custom_fences` entry is needed: once the package is installed,
`citry` resolves like any other Pygments lexer.

## What it highlights

A `citry` block is highlighted as Python, and the following Citry constructs
inside the `template` / `js` / `css` attributes are highlighted in their own
language:

- The HTML in `template`, including the `<c-*>` component and control-flow tags
  (the built-ins `c-if`, `c-for`, `c-slot`, `<c-raw>`, and so on) and `c-*`
  dynamic attributes.
- `{{ ... }}` interpolation, whose body is a Python expression.
- `{# ... #}` template comments.
- The JavaScript in `js` and the CSS in `css`.

The `<c-raw>...</c-raw>` element is treated as verbatim text, matching the
engine: `{{ }}` and tags inside it are not interpreted.

## Template-only blocks: `citry-html`

For a fenced block that shows only a template, with no surrounding Python (just
`<c-*>` tags, `{{ ... }}`, and `{# ... #}`), tag it `citry-html`:

````markdown
```citry-html
<c-for each="item in items">
  <li c-if="item.visible">{{ item.label }}</li>
</c-for>
```
````

`citry` expects full component code (Python with embedded strings), so a bare
template belongs in a `citry-html` block instead.

## License

MIT. Part of the [Citry](https://github.com/citry-dev/citry) project.
