Skip to content

Docs & tooling

This site is built with MkDocs + Material. Everything lives under docs/.

Running the docs locally

cd docs
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cd ..
npx nx serve docs

Open http://127.0.0.1:8000/ to preview changes with live reload.

Faster installs

If MkDocs and Material are already installed globally, skip the virtual environment and run pip install mkdocs-material pymdown-extensions.

Structure

  • docs/pages – Markdown sources.
  • docs/mkdocs.yml – site metadata + navigation.
  • docs/site – build output (ignored by git; generated via mkdocs build).
  • docs/demo – the assembled live demo (ignored by git; generated via docs:create-demo).
  • docs/scripts – the demo assembly script that target runs.

Writing guidelines

  • Use Markdown features already enabled: admonition, pymdownx.details, pymdownx.highlight, superfences, inlinehilite, footnotes, and attr_list.
  • Prefer short sections with clear headings (##). Material automatically builds the table of contents.
  • Use !!! note|tip|warning for callouts.

Building / publishing

mkdocs build renders the Markdown and nothing else:

cd docs
mkdocs build

That produces docs/site, but it is not the complete site. Two sets of artifacts are generated outside MkDocs and copied in afterwards — the live demo and the JSON schemas. Skip them and the deployed site's demo links and schema downloads 404.

Assembling the complete site

Run all five steps from the workspace root, in order:

# 1. Build the editor bundle and assemble the demo into docs/demo.
npx nx run docs:create-demo

# 2. Render the Markdown into docs/site.
npx nx build docs

# 3. Copy the demo into the rendered site.
cp -R docs/demo docs/site/demo

# 4. Generate manuscript.schema.json and manuscript-snapshot.schema.json
#    into packages/schema/prosemirror/dist/.
npx nx run @sciflow/schema-prosemirror:generate-schema

# 5. Copy them into the rendered site.
mkdir -p docs/site/schemas
cp packages/schema/prosemirror/dist/*.schema.json docs/site/schemas/

Step 1 must come before step 2 only in the sense that both must finish before step 3 — but step 2 overwrites docs/site wholesale, so the two copy steps (3 and 5) must always run after it. Re-running mkdocs build alone silently drops both.

The result in docs/site is what the deployment pipeline uploads and what a static host should be given. docs/site and docs/demo are both build output and are git-ignored.

Serving locally

npx nx serve docs (or mkdocs serve) also renders Markdown only. To preview the demo or the schema links, run the five steps above and serve docs/site with any static file server instead.

Updating navigation

  1. Edit docs/mkdocs.yml.
  2. Run npx nx serve docs to confirm the new nav renders correctly.
  3. Keep the nav order aligned with the documentation plan (Overview → User Guide → Developer Guide → Reference).

Linting Markdown

Run npx remark docs/pages --quiet if you have remark configured locally. Otherwise rely on MkDocs build warnings for now.