Writing dGC Documentation¶

Where possible, we have tried to bring together all documentation relating to any aspect of the dGC project into this one Zensical site, published at growth.rcpch.ac.uk

Zensical¶

The documentation for the Digital Growth Charts project is created using Zensical, a documentation framework built on MkDocs. It uses the classic variant, which provides a Material-like appearance with additional features.

Adding or editing documentation¶

Mostly this just requires creating Markdown files in the docs/ directory of the documentation repository.

Use other pages within this repo to get ideas on the style and the features available such as emoji, icons, and admonitions (refer to the Zensical documentation for available extensions).

Continuous Integration via GitHub Actions¶

Any changes to the live branch of the documentation repository trigger a GitHub Action. This runs Zensical on a temporary GitHub-hosted runner, builds the site from the Markdown source into a set of static HTML pages, and publishes the site to Azure. Pull requests from branches in this repository that target live receive an Azure preview deployment; GitHub does not provide the required deployment secret to pull requests from forks.

This occurs whether changes are made using online or local, offline editing methods.

Online editing of the Markdown¶

If you are new to Markdown editing, you can use GitHub's interface itself to edit online, by clicking the 'pencil' edit icon in the top right corner of any source code page. There are also external tools like Prose.io and StackEdit which give you a nice interface for editing MarkDown online, and will sync the changes with GitHub for you.

We will need to review your changes before they are merged into the live branch, so please make them on prerelease or another branch and open a Pull Request targeting live.

Once merged, the changes will be automatically deployed to the live site, and you can see them at growth.rcpch.ac.uk.

Using a text editor and editing locally¶

More experienced coders can git clone the repo and make changes offline on their local machine before pushing to the remote to either the rcpch organisation's remote, or their own fork. This allows you to run Zensical locally and preview the site as it will appear when pushed to live.

Setting up a development environment for the dGC documentation site¶

For all platforms we recommend using the docker compose setup, which will run the Zensical site in a Docker container, so you don't need to install Python or Zensical locally. This is the easiest way to get started, and it isolates your local development environment from any conflicting dependencies.

Prerequisites¶

• Docker installed and running on your machine.
• Docker Compose installed (this is included with Docker Desktop on Windows and Mac, but needs to be installed separately on Linux).
• Git installed on your machine, to clone the repository.

Steps to set up the development environment¶

1. Clone the repository:

git clone https://github.com/rcpch/digital-growth-charts-documentation.git

1. Change into the cloned directory:

cd digital-growth-charts-documentation

1. Start the Zensical development server using Docker Compose:

./s/docs

Suspended Plugins¶

Zensical does not yet support the previously used git-committers and mkdocs-with-pdf plugins. Their configuration remains commented out with links to the relevant upstream issues. The repository's supported PDF path is the self-hosted WeasyPrint exporter invoked by ./s/build-pdf, which generates both the complete-site and controlled safety-documentation PDFs.

./s/build-pdf

Adding a new page¶

• Create a new Markdown file in a subfolder in the docs folder. There is now also a template to get you started, in docs/_utilities/page-template.md, which you would copy into your new page file.

Because of the way we have set up the left sidebar navigation, new pages are not automatically added to the navigation.

(This allows us to have pages which are work-in-progress, available on the live site for review, but not in the navigation, hence only those who have the link would easily find it)

See the next section for how to add pages to the navigation.

Adding navigation for the page¶

Add navigation by editing the nav: tree element in mkdocs.yml. Below is an excerpt from the nav: in this project. You can see how the top level Navbar headings Home and About are defined, and how the sidebar headings work. You can nest several levels deep, if needed.

nav:
  - Home: "index.md"
  - About:
      - "about/about.md"
      - "about/overview.md"

By manually specifying the navigation in this way, we have control over the precise appearance of subfolder names (which are otherwise rendered in Title Case, but this doesn't work for acronyms). Also, we can customise the order of listing of sidebar headings, which would otherwise be ordered alphabetically.

Page title in the navigation¶

The page title that will be displayed in the left sidebar navigation is set in the YAML front matter:

---
title: Some Page Title
reviewers: Dr Reviewer
---

Heading on the page¶

The heading that will be displayed on the page is set using the first <h1> heading (i.e. one hashtag #)

# Heading, which can be different to the sidebar title

Reviewers¶

Reviewers are encouraged to add their details to the reviewers: section of the YAML front matter, this enables us to evidence that each page has been reviewed by multiple members of the team.

---
title: Some Page Title
reviewers: Dr Marcus Baw, Dr Simon Chapman, Other Reviewer ...
---

Tags¶

Pages can be categorised with tags in the YAML front matter. Zensical renders these tags at the foot of the page and indexes them into the site search, giving readers an extra layer of discoverability on top of the navigation tree and full-text search.

---
title: Some Page Title
reviewers: Dr Marcus Baw
tags:
  - API
  - Integration
---

To keep tags useful, please reuse the controlled vocabulary already in use across the docs rather than inventing new, one-off tags. The current vocabulary is:

API, API Reference, Integration, SNOMED CT, Growth Charts, Growth References, Centiles, Date and Age Calculations, React, Python, Docker, Flutter, Command Line, Testing, Versioning, Contributing, Getting Started, FAQ, Clinical Safety, Hazards, Medical Device Regulation, DTAC, Data Protection, Privacy, Security, Licensing, Legal, Accessibility, WCAG, Compliance, Quality Management, Investigations, Post-market Surveillance, WHO, Pricing, Research, Support, Team, Press and Awards, Videos, Overview, Deprecated.

Aim for two to four tags per page that describe its subject matter. If a page genuinely needs a new tag, add it here too so the vocabulary stays consistent.

Markdown Linting and Spellchecking¶

We maintain consistent documentation quality through automated linting and spellchecking. All contributors should run these tools locally before submitting changes.

Markdown Linting¶

Run markdown linting to check for style issues, broken links, and formatting problems:

./s/lint

This runs PyMarkdown with the ruleset defined in .pymarkdown.yml.

Spellchecking¶

Run spellchecking to catch typos and ensure UK English spelling conventions (e.g. "colour", "centre" not "center"):

./s/spellcheck

This runs Codespell with a .codespellrc configuration file. The tool uses UK English by default.

Before pushing¶

Before submitting a Pull Request, run the complete local quality suite:

./s/lint
./s/spellcheck
./s/check-docs-nav
./s/linkcheck
./s/build-pdf
./s/audit

If a check reports issues, fix them and re-run the relevant command.

Publishing is automated¶

When you open or update a Pull Request from a branch in this repository that targets live, Azure automatically builds a preview site. The deployment workflow records the preview environment; team members with Azure access can also inspect it through the Static Web App resource. Pull requests from forks and Dependabot still run the read-only quality and workflow-security checks, but cannot receive an Azure preview because GitHub withholds the deployment secret.

Pull-request automation does not replace local validation. Run the documented quality suite before pushing so CI confirms an already-reviewed change rather than discovering routine errors remotely.

Plugins¶

Zensical supports a defined set of Markdown extensions and native modules. The active set is declared in mkdocs.yml; do not enable a general MkDocs plugin unless current Zensical documentation confirms compatibility.