124 lines
2.6 KiB
Markdown
124 lines
2.6 KiB
Markdown
# 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)
|