Writing these docs

The site is written in AsciiDoc and built with Antora. GitHub Actions builds it on every push to main and publishes it to the gh-pages branch, which GitHub Pages serves.

Where things are

Path Holds

Path	Holds
`antora-playbook.yml`	The site: title, URL, UI bundle, search.
`docs/antora.yml`	The component: name, title, attributes, navigation file.
`docs/modules/ROOT/nav.adoc`	The left-hand menu.
`docs/modules/ROOT/pages/`	One `.adoc` file per page.
`docs/modules/ROOT/images/`	Screenshots.
`docs/modules/ROOT/partials/`	Reused fragments; `generated/` is made by `tools/gen_docs.py`.
`docs/results/tutorials.json`	The tutorial replay’s results.
`docs/ui/`	NX-Style’s additions to Antora’s default UI: header, footer, `css/nxstyle.css`.

antora-playbook.yml

The site: title, URL, UI bundle, search.

docs/antora.yml

The component: name, title, attributes, navigation file.

docs/modules/ROOT/nav.adoc

The left-hand menu.

docs/modules/ROOT/pages/

One .adoc file per page.

docs/modules/ROOT/images/

Screenshots.

docs/modules/ROOT/partials/

Reused fragments; generated/ is made by tools/gen_docs.py.

docs/results/tutorials.json

The tutorial replay’s results.

docs/ui/

NX-Style’s additions to Antora’s default UI: header, footer, css/nxstyle.css.

Generated parts

Reference tables are generated from the code so they cannot drift from it:

Partial From

Partial	From
`shortcuts.adoc`	`NXStyle/nxstyle/shortcuts.py` (`TABLE`)
`settings.adoc`	`NXStyle/nxstyle/config.py` (`DEFAULTS` and their comments)
`ribbon-*.adoc`, `applications.adoc`	`NXStyle/nxstyle/resources/ribbons/*.json`
`tutorial-*.adoc`, `tutorial-summary.adoc`, `tutorial-meta.adoc`	`docs/results/tutorials.json`

shortcuts.adoc

NXStyle/nxstyle/shortcuts.py (TABLE)

settings.adoc

NXStyle/nxstyle/config.py (DEFAULTS and their comments)

ribbon-*.adoc, applications.adoc

NXStyle/nxstyle/resources/ribbons/*.json

tutorial-*.adoc, tutorial-summary.adoc, tutorial-meta.adoc

docs/results/tutorials.json

They are not committed. Change the source and run python tools/gen_docs.py; never edit partials/generated/.

Building the site locally

Needs Python 3.8+ and Node.js 18+.

npm ci

npm run docs

npm run docs runs tools/gen_docs.py and then Antora. The site is in build/site/; open build/site/index.html, or serve the folder:

python -m http.server -d build/site 8000

The build stops on any AsciiDoc warning (a broken cross reference, a missing include or image).

Style

One sentence per line in the .adoc sources: diffs stay readable.
NX names in bold, keys with Ctrl+Q, settings and files in monospace.
Sizes in millimetres; a book’s inch value only in parentheses after it.
Screenshots come from the self-test and the tutorial replay, so they show the current UI. Name them after what they show (ui-…, tutorial-X-…).
Say what differs from NX plainly; no promises about what FreeCAD will do later.

Maintaining the overview

The overview’s page-role: home selects the landing-page styles in docs/ui/css/nxstyle.css. Other pages keep Antora’s sidebar and page outline. Keep the overview focused on entry points; put detailed options and limitations in the linked guides.

When a workflow changes, update What’s new, its matching feature guide and What differs from NX together. Use existing tutorial screenshots and descriptive alternative text; do not substitute mockups for working features. Preview the homepage, a guide and the tutorial index at desktop and mobile widths. Check the menu, search results, section links and keyboard focus as well as the build.