buchwandler

Jekyll integration

sphinxpress build-site writes Markdown files with Jekyll front matter plus HTML rendered by Sphinx’s JSON builder.

The generated page front matter includes:

  • layout

  • title

  • permalink

  • nav_tool

  • docs_project

  • docs_variant

  • docs_ref

  • docs_commit

Navigation data is written as YAML under the configured site.nav_data_dir path. A site layout can use nav_tool to select the matching navigation file.

When site versioning is enabled, each nav payload also includes:

  • nav_key

  • variant, variant_label, variant_kind

  • source_ref, source_commit, source_url

  • release_tag, release_url

  • versions, a version-switcher list for the logical project

Generated files include a notice so they can be distinguished from hand-written site pages.

Scoped API stylesheet

Every generated Jekyll page wraps the Sphinx body in a stable root container:

<div class="sphinxpress-doc">...Sphinx body HTML...</div>

A small, scoped stylesheet is embedded as a <style data-sphinxpress-style="api"> block immediately above the wrapper. The stylesheet:

  • styles Python API descriptions, field lists, inline literals, and source links

  • uses CSS custom properties so host themes can recolor the panels

  • supports light and dark host themes via prefers-color-scheme: dark

  • hides the [source] link in print media

The stylesheet is fully self-contained: it does not depend on Sphinx theme assets, fonts, or JavaScript, and it does not parse or rewrite the Sphinx signature HTML.

Host layouts should:

  • preserve the <div class="sphinxpress-doc"> wrapper

  • avoid overriding .sphinxpress-doc dt.sig with highly specific rules that would defeat the embedded style

  • rely on the embedded style for API presentation instead of shipping duplicate rules

Liquid protection

Generated pages place the Sphinx HTML inside one sphinxpress-owned raw block after front matter:

---
...
---

<!-- GENERATED by sphinxpress. Do not edit by hand. -->

{% raw %}
<style ...>...</style>
<div class="sphinxpress-doc">...</div>
{% endraw %}

This keeps Jekyll 3 from interpreting literal Liquid examples inside Sphinx HTML. Literal {% endraw %} examples are neutralized before rendering so they cannot terminate the outer raw block.

Version switcher layout

sphinxpress/templates/tool-doc.html is the canonical consumer layout for the generated tool pages. It is shipped with the package (it is installed into sphinxpress/templates/ alongside the other templates) and can be used in two ways:

  • Copy the file into the consuming site’s _layouts/tool-doc.html and let sphinxpress keep generating pages that reference layout: tool-doc.

  • Or render the file directly from the package if the consuming site is willing to point its layout: value at a vendored copy of the file.

The sphinxpress sync-layout command keeps the consumer’s copy in step with the package. It writes the package file to <site.root>/_layouts/<site.layout>.html (path derived from the existing [site].root and [site].layout keys). The default policy is safe: identical files are skipped silently, and a file that has drifted from the package is refused (exit 1) with a unified diff printed for inspection. Re-run with --force to overwrite, or --dry-run to print the diff without writing. CI scripts that want a hard gate on drift can run sphinxpress sync-layout directly and treat exit 1 as a failure.

Minimal front matter

A generated tool page needs at least the following front matter to use the layout (sphinxpress already writes this for every page, so consumer sites do not have to add it manually):

---
layout: tool-doc
title: "sphinxpress"
permalink: /tools/sphinxpress/
nav_tool: sphinpress
---

nav_tool is the only field the layout strictly requires. It selects the matching entry from site.data.tool_nav. The other fields (title, permalink, docs_project, docs_variant, docs_ref, docs_commit) are already documented above and can be passed through unchanged.

What the layout renders

The layout reads nav = site.data.tool_nav[page.nav_tool] and renders:

  • the tool title as a link to the tool’s release-variant index page,

  • a <details class="tool-nav-versions"> block sourced from nav.versions (the entry with current: true is shown as plain text inside the <summary>, every other entry is rendered as a link to its own url),

  • the existing “View on GitHub” link from nav.repo_url (when present),

  • the existing “Latest release” link from nav.release_tag / nav.release_url (when present),

  • the entries <ul> from nav.entries, with the existing label cleanup (entry.nav_title, entry.label, entry.slug == 'index' -> 'Overview', entry.title | remove_first: tool_prefix fallback) and the existing active / aria-current="page" rule keyed on page.url == entry.url.

If nav.versions is missing or empty, the version switcher <details> block is omitted entirely; the rest of the layout still renders normally. This keeps the layout working for working-tree-only sites (the example_site fixture falls back cleanly) and for any future variant source that does not yet populate versions.

The layout does not pull a “Latest release” hint or a “Source” link into the switcher itself; release variants still show release_tag next to the title, and the per-page front matter already carries the source ref and commit.