# 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:

```bash
# 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`):
```json
{
  "ignorePatterns": [
    { "pattern": "^http://localhost" },
    { "pattern": "^https://api.goodgo.vn" }
  ],
  "timeout": "20s",
  "retryOn429": true,
  "aliveStatusCodes": [200, 206]
}
```

## Markdown Linting

Enforce consistent markdown style:

```bash
# 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`):
```json
{
  "default": true,
  "MD013": { "line_length": 120 },
  "MD033": false,
  "MD041": false
}
```

## Documentation Generation

**OpenAPI to Markdown:**
```bash
# 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:**
```bash
# 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

```yaml
# .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

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

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

## Resources

- [markdown-link-check](https://github.com/tcort/markdown-link-check) - Validate markdown links
- [markdownlint](https://github.com/DavidAnson/markdownlint) - Markdown linter
- [Redocly CLI](https://redocly.com/docs/cli/) - OpenAPI tools
- [Back to Documentation Skill](../SKILL.md)