pygments-citry

A Pygments lexer for Citry components. It highlights a component the way an editor would: the Python class, plus the HTML, JavaScript, CSS, and Fluent embedded in its template, js, css, and messages 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. It also highlights message IDs, variables, selectors, and comments in a component's Fluent messages block.

Install

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:

pygmentize -l citry my_component.py

In 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:

```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>
    """

    messages = """
      welcome-title = Welcome
    """
```

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, and messages 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).
• Server-side Python in c-* dynamic attributes and #c-key, including a nested Citry template used as a dynamic attribute value.
• Browser-side JavaScript in $c-props and Alpine attributes such as x-data, x-show, @click, and :class. The server-dynamic forms such as c-$c-props and c-@click remain Python.
• Server handler references in Events attributes such as @c-click="save" and :c-query.debounce.300ms="refresh". An optional parenthesized argument on an @c-* handler is highlighted as an Alpine/JavaScript expression.
• The bare #c-ignore framework marker.
• {{ ... }} interpolation, whose body is a Python expression.
• {# ... #} template comments.
• The JavaScript in js and the CSS in css.
• The Fluent messages, terms, variables, attributes, selectors, and comments in messages.

Standalone Fluent fences also work through the fluent and ftl aliases registered by the package's Fluent lexer dependency.

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

The lexer also keeps useful language coloring for common unfinished forms, including an interpolation or quoted dynamic attribute that is still being typed. It highlights source but does not validate whether a directive is allowed on a particular element or component.

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:

```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 project.