MkDocs for CEDAR

Setup

You can set up the build environment either with a plain Python virtual environment (pip) or with Conda. The pip approach is the simplest and does not require installing Conda.

Python virtual environment (pip)

Requires Python 3 (any recent version). The pinned dependencies live in requirements.txt.

Create the virtual environment

python3 -m venv .venv

Activate it and install the dependencies

source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Once activated, mkdocs is on your PATH and the commands under MkDocs below work directly. Run deactivate to leave the environment.

If you prefer not to activate it, you can call the tools directly, e.g. .venv/bin/mkdocs serve. The .venv/ directory is git-ignored.

Conda environment

Install Conda

Use the guide at: https://docs.conda.io/

To install Anaconda, you can go directly to: https://www.anaconda.com/products/individual/get-started

Install Anaconda, close all your terminals and start a new one.

Create Conda environment to run MkDocs

conda env create -f ./environment.yml

Activate Conda environment

conda activate cedar-mkdocs

Deactivate Conda environment

conda deactivate

Remove Conda environment

conda env remove --name cedar-mkdocs

MKDocs Material

MkDocs-Material will be installed from conda-forge when creating the environment.

The documentation can be found at: https://squidfunk.github.io/mkdocs-material/

MkDocs

Please read the full documentation at: https://www.mkdocs.org/

Start built-in dev server

mkdocs serve

You can see the content served by this dev server at http://localhost:8000/

Build the documentation

mkdocs build

Build clean documentation

mkdocs build --clean

Markdown extension syntax

https://facelessuser.github.io/pymdown-extensions/extensions/superfences/

https://python-markdown.github.io/extensions/

Regenerating tutorial screenshots

The screenshots in the CEDAR Tutorial and CEDAR Controlled Term Tutorial are generated, not captured by hand, by a Playwright step-driver that walks the live CEDAR Workbench. It lives in runner/ and writes straight into docs/tutorials/img/ and docs/tutorials/term-img/. This is local authoring tooling (Node/Playwright); it never runs during a Read the Docs build. See runner/README.md for setup and usage.

The two screenshots in the CEDAR MCPs Tutorial come from the local browser pages served by cedar-cee-mcp, not from the Workbench. Build the current MCP JAR, use its show_template and show_instance tools with the tutorial's stored Tissue Sample template and filled instance, and keep that MCP process running while the capture runs:

cd runner
npm install
node mcp-capture.mjs <show-template-url> <show-instance-url>

The capture waits for CEE to finish rendering, refuses a page whose status or console reports a problem, and writes the two 2000×1756 PNGs under docs/img/tutorials/. See runner/README.md for the full workflow.

Diagrams

Diagrams are hand-authored inline SVG in the Markdown, not images. That is a different case from the tutorial screenshots above: a screenshot records what CEDAR looks like and goes stale, while a diagram states a relationship and is reviewed like prose.

The site enables no diagram extension, so there is no Mermaid fence to use. No page carries a diagram at present — the CEE appearance page had the one, and it reads better as a table. Conventions for adding one:

• Wrap it in <figure> with a short <figcaption> naming what the figure shows.
• Give the <svg> role="img" and an aria-label carrying the same claim in words, since the drawing is the only place that information appears.
• Draw in currentColor so it follows the theme's foreground, reserving a literal color for the one thing that carries meaning.
• Size it with viewBox plus width: 100%; min-width: …; max-width: …. The minimum keeps labels legible on a phone; .md-typeset figure scrolls horizontally rather than shrinking the drawing past reading size.
• Keep it self-contained: no <script>, <style>, or external references.

mkdocs build does not validate SVG, so preview the page before pushing.

Contributing and Conventions

Working in this repository, especially with an AI coding assistant? See CLAUDE.md (mirrored as AGENTS.md) for the project conventions. Most importantly: documentation screenshots are generated by the runner, not captured by hand, so a new page that needs CEDAR screenshots should extend the runner rather than embed manual images.