Documentation site development

The documentation lives under:

site/
├── mkdocs.yml
├── docs/
└── overrides/

Start the local documentation

yarn dev

This is the normal documentation-development command. It prepares the local vendor first, then starts MkDocs.

For LAN/mobile testing:

yarn dev:lan

Local assets versus GitHub Pages

The documentation has two asset modes.

Local development

yarn dev sets:

TIKZJAX_DOCS_ASSET_MODE=vendor

The site then loads the current local build from:

site/overrides/vendor/tikzjax/

This is the mode to use when validating changes before publishing a TikZJax release.

Published GitHub Pages site

GitHub Pages currently uses the released npm/jsDelivr package version.

This separation is deliberate for now: the Web2js runtime artifacts used by local development are ignored by Git and are not automatically available in a normal GitHub checkout.

The local vendor workflow must therefore not be confused with the current production Pages deployment strategy.

Raw <script type="text/tikz"> inside Markdown containers

TikZJax source inside a real HTML script element is raw TeX text. Markdown must not reinterpret it.

This matters especially inside Content Tabs and admonitions, where indentation is part of the Markdown container syntax.

The documentation enables:

pymdownx.blocks.html

Executable examples nested inside tabs should use the block HTML form:

=== "Rendering"

    /// html | script[type="text/tikz" data-tex-packages="yquant"]

        \begin{tikzpicture}
        \begin{yquant}
            qubit q[2];

            h q[0];
            cnot q[1] | q[0];


            measure q;
        \end{yquant}
        \end{tikzpicture}
    ///

Inside that script, zero, one, two, or more blank lines remain part of the TeX source. They must not escape into Markdown rendering.

The adjacent "HTML" tab may still show the ordinary HTML syntax in a code fence because it is documentation, not an executable block.

Fenced tikzjax blocks and optional packages

A fenced block is convenient:

```tikzjax
\begin{tikzpicture}
    \draw (0,0) circle (1);
\end{tikzpicture}
```

However, the current fenced syntax does not provide per-block HTML attributes such as:

data-tex-packages="physics"

Therefore an example that requires a package such as physics, chemfig, circuitikz, yquant, tikz-feynhand, pgf-spectra, or kinematikz may intentionally fail when shown as a fenced block on this documentation site.

The package is deliberately not loaded globally just to make a demonstration succeed. The package-specific example pages label those demonstrations as Expected failure and explain why the corresponding <script type="text/tikz" data-tex-packages="..."> form is the correct local-loading syntax.

Why packages are not loaded globally for the docs

Keeping optional packages local demonstrates the real recommended configuration and avoids masking integration errors.

It also preserves the performance model: ordinary TikZ diagrams should not load specialized packages that they do not use.

Documentation-only edits are fast

Files under site/docs/ are not part of the TikZJax vendor build-input hash.

After the first synchronization, editing Markdown and restarting yarn dev normally reuses the existing TikZJax build rather than rebuilding Webpack.