README DOCS - antimetal/system-agent GitHub Wiki

Documentation Maintenance Tools

This wiki uses automated tools to maintain documentation quality and consistency. This README explains how to use these tools locally and what happens in CI/CD.

Quick Start

# Install dependencies
npm install

# Run all checks
npm run check:all

# Fix common issues automatically
npm run fix:all

Available Tools

1. Markdown Linting (markdownlint)

Ensures consistent formatting and style across all markdown files.

# Check formatting
npm run lint:markdown

# Fix formatting issues automatically
npm run lint:markdown:fix

Configuration: .markdownlint.json

2. Link Validation (markdown-link-check)

Validates that all internal and external links work correctly.

# Check all links
npm run check:links

# Check specific file
npm run check:links:single README.md

Configuration: .markdown-link-check.json

3. Style Guide (Vale)

Enforces writing style and terminology consistency using Microsoft and write-good rules.

# Check writing style
npm run check:style

# Install Vale styles (first time only)
vale sync

Configuration: .vale.ini and .vale/styles/

4. Wiki Structure Analysis

Custom tool that analyzes wiki structure and finds issues.

# Analyze wiki structure
npm run analyze:structure
# or directly:
node scripts/analyze-wiki.js

GitHub Actions

The wiki automatically runs quality checks on every commit via .github/workflows/docs.yml:

  • ✅ Markdown Linting - Formatting consistency
  • ✅ Link Validation - Broken link detection
  • ✅ Style Guide - Writing quality
  • ✅ Structure Analysis - Wiki organization

Results are available in the Actions tab of the repository.

Configuration Files

File Purpose Tool
.markdownlint.json Markdown formatting rules markdownlint
.markdown-link-check.json Link checking configuration markdown-link-check
.vale.ini Style guide configuration Vale
.vale/styles/Antimetal/ Custom terminology rules Vale
package.json Node.js dependencies and scripts npm

Common Issues and Fixes

Broken Links

Issue: Links to non-existent files
Fix: Create the missing file or update the link

# Find broken links
npm run check:links

# Analyze which files are missing
npm run analyze:structure

Formatting Issues

Issue: Inconsistent markdown formatting
Fix: Run the auto-formatter

# Fix automatically
npm run lint:markdown:fix

Style Guide Violations

Issue: Writing doesn't follow style guide
Fix: Review Vale suggestions and update content

# Check style issues
npm run check:style

Orphaned Files

Issue: Files not linked from anywhere
Fix: Add links from appropriate pages or remove unused files

# Find orphaned files
npm run analyze:structure

Writing Guidelines

Terminology

  • Use "Kubernetes" not "k8s" or "K8S"
  • Use "gRPC" not "grpc" or "GRPC"
  • Use "System Agent" not "system-agent" or "systemagent"
  • Use "eBPF" not "ebpf" or "EBPF"

Formatting

  • Use ATX headers (# not ===)
  • Use dashes for lists (- not *)
  • Limit lines to 120 characters
  • Use fenced code blocks with language tags

Links

  • Use descriptive link text (not "click here")
  • Internal wiki links should not include .md extension
  • Always test links after adding them

Local Development Workflow

  1. Before Making Changes

    npm run check:all

  2. After Making Changes

    npm run lint:markdown:fix  # Fix formatting
npm run check:links        # Verify links work
npm run analyze:structure  # Check wiki structure

  3. Before Committing

    npm run check:all  # Final verification

Troubleshooting

Vale Not Working

# Install Vale styles
vale sync

# Check Vale configuration
vale --config .vale.ini --help

Link Checker False Positives

Add patterns to ignore in .markdown-link-check.json:

{
  "ignorePatterns": [
    {"pattern": "^http://example.com"}
  ]
}

Markdown Lint Conflicts

Disable specific rules in .markdownlint.json:

{
  "MD013": false  // Disable line length rule
}

Integration with IDEs

VS Code

Install extensions:

  • markdownlint - Real-time markdown linting
  • Vale VSCode - Style guide checking
  • Markdown All in One - Enhanced markdown support

Other Editors

Most editors have plugins for markdownlint and Vale. Check your editor's extension marketplace.

For more information about the System Agent documentation structure, see Home.