Markdown Quality Tools

Markdown Linting

Automatically check for common markdown errors.

``bash npm install -D markdownlint-cli ``

Then lint all docs: ``bash markdownlint docs/**/*.md ``

Configuration (.markdownlintrc.json): ``json { "extends": "default", "no-hard-tabs": false, "line-length": false, "no-multiple-spaces": false, "no-inline-html": false } ``

What it catches:

• Inconsistent heading levels
• Multiple blank lines
• Missing spaces around headings
• Inconsistent list formatting

---

Link Checking

Automatically verify all links are correct.

``bash npm install -D markdown-link-check ``

Then check all links: ``bash find docs -name "*.md" -exec markdown-link-check {} \; ``

What it catches:

• Broken links
• Links to files that don't exist
• Invalid URLs

---

Documentation Site Generation

Build HTML from Markdown

If you want to generate static HTML from your markdown (for hosting or offline reading):

```bash

Using a custom build script

node build-docs.js

Or use a tool like MkDocs

pip install mkdocs mkdocs build ```

Benefits:

• Offline documentation
• Hosting without GitBook subscription
• Full control over styling
• Self-contained HTML files

---

Local Serving

To preview docs locally before publishing:

```bash

Using a simple HTTP server

npx http-server docs/_build/html/

Or use Python

python3 -m http.server 8000 --directory docs/_build/html/ ```

Then visit: http://localhost:8000

---

Version Control & CI/CD

Checking Docs in CI

Add to your CI pipeline (GitHub Actions example):

```yaml name: Documentation Quality

on: [pull_request]

jobs: docs: runs-on: ubuntu-latest steps:

• uses: actions/checkout@v3
• uses: actions/setup-node@v3

with: node-version: '18'

• run: npm install -D markdownlint-cli markdown-link-check
• run: markdownlint docs/**/*.md
• run: find docs -name "*.md" -exec markdown-link-check {} \;

```

Benefits:

• Catch broken links before merging
• Enforce markdown style consistently
• Prevent documentation regressions

---

Version Sync

Keep documentation version in sync with code:

```bash

Extract version from package.json

VERSION=$(jq -r '.version' package.json)

Update CHANGELOG.md with new version

sed -i "s/## \[Unreleased\]/## [$VERSION] - $(date +%Y-%m-%d)/" docs/CHANGELOG.md

Or in Python

import json from datetime import date

with open('package.json') as f: version = json.load(f)['version']

with open('docs/CHANGELOG.md') as f: content = f.read()

today = date.today().isoformat() content = content.replace( '## [Unreleased]', f'## [{version}] - {today}' )

with open('docs/CHANGELOG.md', 'w') as f: f.write(content) ```

---

Search & Discoverability

Enable Full-Text Search

GitBook has built-in search. For self-hosted docs, use:

Option 1: Algolia (Recommended) ``javascript // Add to your site header <script> docsearch({ appId: 'YOUR_APP_ID', apiKey: 'YOUR_API_KEY', indexName: 'docs', container: '#docsearch' }); </script> ``

Option 2: Lunr.js (Self-hosted) ```bash npm install lunr

Index your docs at build time

```

Benefits:

• Users find content faster
• Reduces support questions
• Improves documentation discoverability

---

SEO Optimization

If hosting docs publicly:

``html <!-- In each HTML page header --> <meta name="description" content="How to deploy ARX platform"> <meta name="keywords" content="deployment, ARX, installation, setup"> <meta property="og:title" content="Deployment Guide - ARX"> <meta property="og:description" content="Step-by-step deployment instructions"> ``

GitBook does this automatically.

---

Automation: Keep Docs Fresh

Auto-Generate API Reference

If your API is documented in code, auto-generate the reference:

Python (using docstrings): ```bash

Generate markdown from docstrings

pip install pdoc3 pdoc3 --html --output docs/api-reference my_module ```

JavaScript (using JSDoc): ``bash npm install -D jsdoc-to-markdown jsdoc-to-markdown src/**/*.js > docs/API_REFERENCE.md ``

Benefits:

• API docs always in sync with code
• Less manual work
• Single source of truth

---

Auto-Generate Changelog

Use a commit convention + tool to auto-generate changelog:

``bash npm install -D conventional-changelog-cli conventional-changelog -p angular -i CHANGELOG.md -s ``

Requires conventional commits: `` feat: add authentication fix: resolve policy drift detection bug docs: update API reference ``

Benefits:

• Changelog generated from commits
• Always accurate
• No manual tracking

---

Documentation Metrics

What to Track

```bash

Count documentation pages

find docs -name "*.md" | wc -l

Check average page length (words)

for f in docs/**/*.md; do echo "$f: $(wc -w < $f) words" done

Check code coverage

grep -r "code block" docs/**/*.md | wc -l ```

Set Targets

• Minimum docs: 1 README, 1 Quick Start, 1 API Reference
• Code examples: At least 1 example per major feature
• Page length: Average 1,000-2,000 words
• Freshness: Update CHANGELOG every release
• Links: Every page should link to 2-3 related pages

---

Quick Reference: The Doc Stack

| Document | Audience | Purpose | Length | Update Frequency | |----------|----------|---------|--------|------------------| | README | Everyone | Orientation | 1 page | When basics change | | QUICK_START | New devs | Get working | 1 page | When setup changes | | ARCHITECTURE | Senior engineers | Understand design | 3-5 pages | Rarely | | API_REFERENCE | All engineers | Complete spec | 10-20 pages | With each release | | GUIDES | Specific use cases | How-to instructions | 2-3 pages each | As needed | | EXAMPLES | Learners | Working code | 1-2 pages each | With API changes | | CONTRIBUTING | Contributors | Dev workflow | 2-3 pages | Rarely | | TROUBLESHOOTING | Everyone | Problem-solving | 3-5 pages | As needed | | CHANGELOG | Release managers | Version history | 1 page | With each release |

---

Tool Recommendations

Essential

• markdownlint - Catch formatting errors
• markdown-link-check - Verify links work
• Git hooks - Run checks before commit

Recommended

• Conventional Changelog - Auto-generate changelog
• Algolia - Full-text search
• GitHub Actions - CI/CD for docs

Optional

• Mermaid - Diagrams in markdown
• PlantUML - Architecture diagrams
• Swagger/OpenAPI - API auto-documentation

---

Summary

Good documentation tooling:

• Catches errors early — Linting, link checking
• Keeps docs fresh — Auto-generation from code
• Makes docs discoverable — Search, SEO
• Enforces quality — CI/CD checks
• Saves time — Automation reduces manual work

Start with linting and link checking. Add auto-generation when you have the capacity.