docs: Add new documentation references for automation tools and configuration guidelines.

2026-01-18 23:12:29 +07:00
parent 941ace8c80
commit c55c4b4459
2 changed files with 276 additions and 0 deletions
--- a/.agent/skills/documentation/references/AUTOMATION.md
+++ b/.agent/skills/documentation/references/AUTOMATION.md
@@ -0,0 +1,123 @@
+# 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)
--- a/.agent/skills/documentation/references/CONFIGURATION.md
+++ b/.agent/skills/documentation/references/CONFIGURATION.md
@@ -0,0 +1,153 @@
+# Configuration Documentation / Tài Liệu Cấu Hình
+
+This reference provides templates and guidelines for documenting service configuration.
+
+## Environment Variables Table
+
+```markdown
+## Environment Variables / Biến Môi Trường
+
+### Required Variables / Biến Bắt Buộc
+
+| Variable | Type | Description / Mô Tả | Example |
+|----------|------|---------------------|----------|
+| `DATABASE_URL` | string | PostgreSQL connection string / Chuỗi kết nối PostgreSQL | `postgresql://user:pass@localhost:5432/db` |
+| `REDIS_URL` | string | Redis connection string / Chuỗi kết nối Redis | `redis://localhost:6379` |
+| `JWT_SECRET` | string | Secret key for JWT signing / Khóa bí mật ký JWT | `your-256-bit-secret` |
+| `RABBITMQ_URL` | string | RabbitMQ connection / Kết nối RabbitMQ | `amqp://user:pass@localhost:5672` |
+
+### Optional Variables / Biến Tùy Chọn
+
+| Variable | Type | Description / Mô Tả | Default |
+|----------|------|---------------------|----------|
+| `PORT` | integer | Server port / Cổng server | `5000` |
+| `LOG_LEVEL` | enum | Logging level: `debug`, `info`, `warn`, `error` | `info` |
+| `CORS_ORIGINS` | string | Allowed CORS origins (comma-separated) | `*` |
+| `RATE_LIMIT_MAX` | integer | Max requests per window / Số request tối đa | `100` |
+| `RATE_LIMIT_WINDOW_MS` | integer | Rate limit window in ms / Cửa sổ giới hạn (ms) | `60000` |
+| `CACHE_TTL_SECONDS` | integer | Default cache TTL / TTL cache mặc định | `300` |
+```
+
+## Configuration File Example
+
+```markdown
+## Configuration File: `appsettings.json`
+
+\`\`\`json
+{
+  "Server": {
+    "Port": 5000,
+    "Environment": "Development",
+    "EnableSwagger": true
+  },
+  "Database": {
+    "Host": "localhost",
+    "Port": 5432,
+    "Name": "goodgo_dev",
+    "Username": "postgres",
+    "Password": "password",
+    "MaxPoolSize": 20,
+    "CommandTimeout": 30
+  },
+  "Redis": {
+    "Host": "localhost",
+    "Port": 6379,
+    "Database": 0,
+    "Password": null,
+    "ConnectTimeout": 5000,
+    "SyncTimeout": 5000
+  },
+  "Jwt": {
+    "Secret": "your-secret-key-min-32-chars",
+    "Issuer": "goodgo-platform",
+    "Audience": "goodgo-clients",
+    "ExpirationMinutes": 60,
+    "RefreshTokenExpirationDays": 7
+  },
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft": "Warning",
+      "Microsoft.Hosting.Lifetime": "Information"
+    },
+    "Console": {
+      "FormatterName": "json"
+    }
+  },
+  "RateLimiting": {
+    "PermitLimit": 100,
+    "Window": "00:01:00",
+    "QueueLimit": 10
+  },
+  "Cors": {
+    "AllowedOrigins": [
+      "http://localhost:3000",
+      "https://app.goodgo.vn"
+    ],
+    "AllowCredentials": true,
+    "AllowedHeaders": ["*"],
+    "AllowedMethods": ["GET", "POST", "PUT", "DELETE"]
+  }
+}
+\`\`\`
+
+**Notes:**
+- **EN**: Never commit secrets to version control. Use environment variables or secret management tools.
+- **VI**: Không bao giờ commit secrets vào version control. Dùng biến môi trường hoặc công cụ quản lý secrets.
+```
+
+## Docker Compose Configuration
+
+```markdown
+## Docker Compose Configuration
+
+\`\`\`yaml
+version: '3.8'
+
+services:
+  app:
+    build: .
+    ports:
+      - "5000:5000"
+    environment:
+      - DATABASE_URL=postgresql://postgres:password@db:5432/goodgo
+      - REDIS_URL=redis://redis:6379
+      - JWT_SECRET=${JWT_SECRET}
+      - LOG_LEVEL=info
+    depends_on:
+      - db
+      - redis
+  
+  db:
+    image: postgres:15
+    environment:
+      - POSTGRES_DB=goodgo
+      - POSTGRES_USER=postgres
+      - POSTGRES_PASSWORD=password
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+  
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+
+volumes:
+  postgres_data:
+  redis_data:
+\`\`\`
+
+**Environment File** (`.env`):
+\`\`\`bash
+JWT_SECRET=your-production-secret-key-min-32-characters
+DATABASE_PASSWORD=your-secure-db-password
+\`\`\`
+```
+
+## Resources
+
+- [Back to Documentation Skill](../SKILL.md)