Skip to content

Documentation export

  • Status: Active packaging and publication procedure
  • Destination: masojus/motoxdashboard-docs on GitLab

The Markdown in this repository is the source of truth. The separate GitLab repository is a generated, reviewable publication snapshot; do not fix prose there without bringing the same change back here.

Export layout

The export preserves the source paths that make relative links work:

README.md
docs/
    index.md
    decisions/
    ...
mkdocs.yml
.gitlab-ci.yml
assets/
javascripts/
stylesheets/

docs/index.md is the curated site landing page. README.md remains the developer-oriented repository overview and is included under Reference in the site navigation. MkDocs configuration and presentation assets live in docs-site/ in this repository and are copied to the export root.

Create a snapshot

Run from the repository root in WSL, choosing a path that does not already exist:

destination="$(mktemp -d)/motoxdashboard-docs"
./scripts/export-docs.sh "$destination"
find "$destination" -type f -print | sort

The exporter uses an allowlist: Markdown source plus the YAML, CSS, JavaScript, and SVG files required to build the site. It refuses to overwrite an existing path and does not copy source code, build output, credentials, production data, or private media.

Validate before publishing

Build exactly as GitLab Pages will. The CI job creates workspace/ because MkDocs requires every published source to live under one docs_dir:

docker run --rm \
  -v "$destination:/docs" \
  --entrypoint sh \
  squidfunk/mkdocs-material:9.6 \
  -c 'rm -rf workspace public &&
      mkdir -p workspace &&
      cp README.md workspace/README.md &&
      cp -R docs workspace/docs &&
      cp -R stylesheets workspace/stylesheets &&
      cp -R javascripts workspace/javascripts &&
      cp -R assets workspace/assets &&
      mkdocs build --strict --clean --site-dir public'
test -f "$destination/public/docs/index.html"

Alternatively, install mkdocs-material>=9.6,<10 in an isolated Python environment and run mkdocs build --strict. Review the generated navigation, Mermaid diagrams, MathJax formulas, relative links, and both palette modes.

Publish

Commit the complete snapshot to the default branch of the destination repository. GitLab CI builds only the default branch and publishes the public/ artifact through GitLab Pages. The repository may stay private while the Pages access level is changed independently in GitLab.

After pushing:

  1. verify that the pages pipeline succeeds;
  2. open the Pages URL and follow the reading paths from the landing page;
  3. check that the destination commit corresponds to the intended source commit; and
  4. only then change Pages visibility if public access is desired.

The intended Pages URL is https://masojus.gitlab.io/motoxdashboard-docs/ unless a custom domain is configured later.