Skip to content

Code, snippets, and directives

Examples should be small enough to understand and complete enough to try.

Highlighted code

A title identifies the file, line numbers support discussion, and a highlight directs attention.

greeting.py
1
2
3
4
def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("reader"))

Inline highlighting works too: greet("reader").

Show Markdown source
```python title="greeting.py" linenums="1" hl_lines="2"
def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("reader"))
```

Inline highlighting works too: `#!python greet("reader")`.

Annotations

Select the numbered marker for an explanation alongside the code.

settings.toml
[build]
target = "site" # (1)!
  1. The target names the output directory for this illustrative configuration.
Show Markdown source
```toml title="settings.toml"
[build]
target = "site" # (1)!
```

1. The target names the output directory for this illustrative configuration.

Reusable fixed text

The following source file is included at build time using the Snippets extension.

release-note.txt
Version 1.2
- Added a review step.
- Clarified the rollback procedure.
Show Markdown source
```text title="release-note.txt"
--8<-- "assets/authoring/release-note.txt"
```

References

Conditional directives

The official directives extension is distributed separately through Zensical Spark. It uses a catalog and a selected variant; it is not enabled in this example site. The following is illustrative source, not a live demo.

@if deployment = cloud

    Open the cloud console.

@else

    Configure the local service.

This guide covers @var{deployment}.

@use shared/security-notice.md

See the directives guide for installation, catalog configuration, conditions, variables, and source reuse.