Developer Docs Sample (Vendor-neutral)

This repository is a vendor-neutral docs-as-code sample for a node-based workflow/automation platform.

It combines anonymized enterprise case-study docs with generic workflow-demo content suitable for developer tools roles.

• Static site: MkDocs Material
• CI: build, link check (lychee), style lint (Vale)
• Content: task-first (Quickstart/How-to/Reference), mermaid diagrams, runnable snippets
• Languages: EN, DE (only for a couple of documents to demonstrate ability to create content in German)

Structure

• docs/workflow/ – generic workflow demo
• docs/case-studies/ – anonymized enterprise case
• docs/contributing/, docs/metrics/ – process & KPI
• .github/workflows/ – CI for docs
• .vale.ini and styles/ – style checks (Vale)
• lychee.toml – lick checks

Install, build, and preview the docs site locally

Prerequisites

• Python 3.10+ and pip
• MkDocs static site generation installed. For more information on how to install MkDocs, please, refer to MkDocs Installation Guide.
• Git
• (optional) a terminal with UTF-8 support

Tip

Use a virtual environment so your global Python stays clean.

Use the following commands to create and activate a virtual environment:

• macOS/Linux

python -m venv .venv
source .venv/bin/activate

• Windows (PowerShell)

  py -m venv .venv
  .venv\Scripts\Activate.ps1

Preview the site locally

To preview the site locally:

1. Install dependencies

   pip install -r requirements.txt

2. Run the local preview server

   python -m mkdocs serve

Important

The site will automatically reload when you change any file.

3. Open the URL printed in the terminal (usually http://127.0.0.1:8000).

Build the docs

Use the following command to build the site:

python -m mkdocs build

!!! tip "Tip" Use the --strict option to fail the build on broken links or configuration issues.

The static site is generated in the ./site directory.

Notes on i18n (EN/DE)

• Pages with a .de.md suffix are shown in German.
• To hide untranslated pages in German, set fallback_to_default: false in mkdocs.yml.

Troubleshooting

• Unrecognised theme name: 'material' → Install the theme inside the virtual environment:

  pip install -r requirements.txt

  Then run python -m mkdocs serve again.

• mkdocs not found → Use python -m mkdocs serve (Windows: py -m mkdocs serve).

• Port in use → Specify the address and port explicitly:

  python -m mkdocs serve -a 127.0.0.1:8001

• Build fails due to i18n config → Ensure plugins.i18n.languages is a list (see mkdocs.yml), not a dict.

Link checking

We use Lychee to continuously check external/internal links.

• Config: lychee.toml
• CI: .github/workflows/links.yml

Installing Lychee locally:

• macOS: brew install lychee
• Linux: cargo install lychee

Local Testing:

make build
make check-links