Automation & Tools / Công Cụ Tự Động

This reference provides tools and scripts for automating documentation validation and generation.

Link Checking

Validate all markdown links to prevent broken references:

# Install markdown-link-check
npm install -g markdown-link-check

# Check single file
markdown-link-check docs/en/README.md

# Check all markdown files in docs/
find docs -name "*.md" | xargs markdown-link-check

# With config file
markdown-link-check -c .markdown-link-check.json docs/en/README.md

Config example (.markdown-link-check.json):

{
  "ignorePatterns": [
    { "pattern": "^http://localhost" },
    { "pattern": "^https://api.goodgo.vn" }
  ],
  "timeout": "20s",
  "retryOn429": true,
  "aliveStatusCodes": [200, 206]
}

Markdown Linting

Enforce consistent markdown style:

# Install markdownlint-cli
npm install -g markdownlint-cli

# Lint all docs
markdownlint docs/**/*.md

# Fix auto-fixable issues
markdownlint --fix docs/**/*.md

# With config
markdownlint -c .markdownlint.json docs/**/*.md

Config example (.markdownlint.json):

{
  "default": true,
  "MD013": { "line_length": 120 },
  "MD033": false,
  "MD041": false
}

Documentation Generation

OpenAPI to Markdown:

# Using redoc-cli
npx @redocly/cli build-docs docs/en/api/openapi/service.yaml \
  -o docs/en/api/reference.html

# Using swagger-markdown
npx swagger-markdown -i docs/en/api/openapi/service.yaml \
  -o docs/en/api/REFERENCE.md

C# XML Comments to Markdown:

# Using xmldoc2md (for .NET projects)
dotnet tool install -g xmldoc2md
xmldoc2md src/MyService.API/bin/Debug/net8.0/MyService.API.xml \
  docs/en/api/

CI/CD Integration

# .github/workflows/docs-validation.yml
name: Validate Documentation

on: [pull_request]

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check links
        run: |
          npm install -g markdown-link-check
          find docs -name "*.md" | xargs markdown-link-check
      - name: Lint markdown
        run: |
          npm install -g markdownlint-cli
          markdownlint docs/**/*.md

Documentation Testing

# Check for broken links
find docs -name "*.md" -exec markdown-link-check {} \;

# Lint markdown files
markdownlint docs/**/*.md

Resources

markdown-link-check - Validate markdown links
markdownlint - Markdown linter
Redocly CLI - OpenAPI tools
Back to Documentation Skill

2.6 KiB Raw Blame History