moai-docs-linting

Docs Linting

Primary Agent: doc-syncer
Secondary Agents: alfred
Version: 4.0.0
Keywords: docs, linting, cd, spec, ci

📖 Progressive Disclosure

Level 1: Quick Reference (Core Concepts)

📚 Content

Section 1: Linting Overview

Documentation linting automatically detects formatting issues, broken references, and structural problems in markdown files. This skill provides comprehensive validation strategies for:

Header Structure: Duplicate H1s, level skipping, hierarchy violations
Code Blocks: Missing language declarations, unclosed blocks, syntax issues
Links: Broken references, invalid paths, protocol consistency
Lists: Marker consistency (mixing - and *), indentation problems
Tables: Column count mismatch, alignment issues
Typography: Trailing whitespace, full-width characters, encoding issues

Key Benefits:

Catch errors before documentation builds
Ensure consistency across all documents
Improve readability and user experience
Validate multilingual document structure

Section 2: Core Linting Rules

Header Validation

Rules:
  - H1 (# Title): Exactly 1 per document
  - H2-H6 (## Subtitle, etc.): Can be multiple
  - Level Hierarchy: No skipping levels (# → ## → ###)
  - Duplicates: No duplicate headers on same level
  - Special Characters: No emojis in headers (MoAI-ADK standard)

Example - Good:

# Main Title (single H1)

---

### Level 2: Practical Implementation (Common Patterns)

📚 Content

### Section 1: Linting Overview

Documentation linting automatically detects formatting issues, broken references, and structural problems in markdown files. This skill provides comprehensive validation strategies for:

- **Header Structure**: Duplicate H1s, level skipping, hierarchy violations
- **Code Blocks**: Missing language declarations, unclosed blocks, syntax issues
- **Links**: Broken references, invalid paths, protocol consistency
- **Lists**: Marker consistency (mixing `-` and `*`), indentation problems
- **Tables**: Column count mismatch, alignment issues
- **Typography**: Trailing whitespace, full-width characters, encoding issues

**Key Benefits**:
- Catch errors before documentation builds
- Ensure consistency across all documents
- Improve readability and user experience
- Validate multilingual document structure

### Section 2: Core Linting Rules

#### Header Validation

```yaml
Rules:
  - H1 (# Title): Exactly 1 per document
  - H2-H6 (## Subtitle, etc.): Can be multiple
  - Level Hierarchy: No skipping levels (# → ## → ###)
  - Duplicates: No duplicate headers on same level
  - Special Characters: No emojis in headers (MoAI-ADK standard)

Example - Good:

# Main Title (single H1)

---

Section 2
### Subsection 2.1

Example - Bad:

# Title 1
# Title 2        ❌ Multiple H1s

---

Subsection
#### Deep level   ❌ Skipped H3

Code Block Validation

Rules:
  - Language Declaration: Every block must specify language
  - Matching Delimiters: Opening ``` must match closing ```
  - Placement: Code blocks on separate lines
  - Content: Valid code examples

Example - Good:

\`\`\`python
def hello():
    print("Hello, World!")
\`\`\`

Example - Bad:

\`\`\`
def hello():
\`\`\`python    ❌ Mismatched delimiters

\`\`\`          ❌ No language specified
def hello():
\`\`\`

Link Validation

Rules:
  - Relative Links: Use ../ for cross-directory navigation
  - External Links: Must use https:// protocol
  - Valid References: All linked files must exist
  - Anchor Links: Point to valid headers

Example - Good:

[Install Guide](../getting-started/installation.md)
[External](https://example.com)
[Section](#header-anchor)

Example - Bad:

[Link](../../nonexistent.md)           ❌ File doesn't exist
[Link](http://example.com)             ❌ Not https
[Link](#invalid-section)               ❌ Header doesn't exist

List Validation

Rules:
  - Marker Consistency: Don't mix - and * in same list
  - Indentation: Use 2-4 spaces (never tabs)
  - Nesting: Consistent indentation for nested items
  - Separator: Blank line required after list

Example - Good:

- Item 1
- Item 2
  - Nested 2.1
  - Nested 2.2
- Item 3

Example - Bad:

- Item 1
* Item 2           ❌ Mixed markers
	- Item 3       ❌ Tab indentation

Table Validation

Rules:
  - Column Consistency: All rows must have same column count
  - Header Line: Required | --- | separator
  - Alignment: Optional but consistent :--|:--:|--:

Example - Good:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Example - Bad:

| Header 1 | Header 2
| Cell 1   | Cell 2 | Cell 3   |  ❌ Column mismatch

Section 3: Multilingual Linting

For Korean Documents (ko/):

UTF-8 Encoding: Verify encoding consistency
Full-width Characters: Avoid U+3000 (full-width space)
Typography: Proper spacing around Korean-English boundaries
Capitalization: Consistent title casing

For Other Languages (en/, ja/, zh/):

Language-specific rules
Consistent structure matching Korean source
Translation quality validation

Section 4: Automation & Tooling

Python Linting Script Pattern:

class DocumentationLinter:
    def __init__(self, docs_path: str):
        self.docs_path = Path(docs_path)
        self.errors = []
        self.warnings = []

    def lint_headers(self, content: str) -> List[str]:
        """Validate header structure"""
        h1_count = len(re.findall(r'^# ', content, re.MULTILINE))
        if h1_count != 1:
            return [f"Error: Found {h1_count} H1 headers (expected 1)"]
        return []

    def lint_code_blocks(self, content: str) -> List[str]:
        """Validate code block pairs"""
        issues = []
        # Check for ```language declaration
        # Check for matching delimiters
        # Validate content
        return issues

    def lint_links(self, content: str, file_path: Path) -> List[str]:
        """Validate link references"""
        # Find all [text](path) patterns
        # Verify file existence
        # Check protocol (https for external)
        return issues

Integration with CI/CD:

# Pre-commit validation
python3 .moai/scripts/lint_korean_docs.py
python3 .moai/scripts/validate_mermaid_diagrams.py
python3 .moai/scripts/validate_korean_typography.py

# Generate comprehensive report
python3 .moai/scripts/generate_final_comprehensive_report.py

Section 5: MoAI-ADK Standards

Header Style (from November 9 validation):

✅ No emojis in headers (text only)
✅ Material Icons allowed in body text (not headers)
✅ Clear hierarchy (H1 → H2 → H3)

Link Standards:

✅ Use relative paths within language directories
✅ Use https:// for external links
✅ Descriptive link text (avoid "click here")

Code Block Standards:

✅ Always specify language (python, javascript, bash, etc.)
✅ Real, tested examples
✅ Clear explanations

Internationalization:

✅ Same structure across ko/, en/, ja/, zh/
✅ UTF-8 encoding for all files
✅ Consistent terminology across languages

✅ Validation Checklist

Comprehensive linting rules documented
Real examples provided
Python script patterns included
MoAI-ADK standards integrated
Multilingual support explained
Tool integration examples
English language confirmed

Level 3: Advanced Patterns (Expert Reference)

Note: Advanced patterns for complex scenarios.

Coming soon: Deep dive into expert-level usage.

🎯 Best Practices Checklist

Must-Have:

✅ [Critical practice 1]
✅ [Critical practice 2]

Recommended:

✅ [Recommended practice 1]
✅ [Recommended practice 2]

Security:

🔒 [Security practice 1]

🔗 Context7 MCP Integration

When to Use Context7 for This Skill:

This skill benefits from Context7 when:

Working with [docs]
Need latest documentation
Verifying technical details

Example Usage:

# Fetch latest documentation
from moai_adk.integrations import Context7Helper

helper = Context7Helper()
docs = await helper.get_docs(
    library_id="/org/library",
    topic="docs",
    tokens=5000
)

Relevant Libraries:

Library	Context7 ID	Use Case
[Library 1]	`/org/lib1`	[When to use]

📊 Decision Tree

When to use moai-docs-linting:

Start
  ├─ Need docs?
  │   ├─ YES → Use this skill
  │   └─ NO → Consider alternatives
  └─ Complex scenario?
      ├─ YES → See Level 3
      └─ NO → Start with Level 1

🔄 Integration with Other Skills

Prerequisite Skills:

Skill("prerequisite-1") – [Why needed]

Complementary Skills:

Skill("complementary-1") – [How they work together]

Next Steps:

Skill("next-step-1") – [When to use after this]

📚 Official References

Metadata

skill_id: moai-docs-linting
skill_name: Documentation Linting & Markdown Validation
version: 1.0.0
created_date: 2025-11-10
updated_date: 2025-11-10
language: english
word_count: 1400
triggers:
  - keywords: [markdown lint, documentation validation, lint check, header validation, code block, link validation, table format]
  - contexts: [docs-linting, @docs:lint, documentation-validation, quality-gate]
agents:
  - docs-manager
  - docs-auditor
  - quality-gate
freedom_level: high
context7_references:
  - url: "https://github.com/igorshubovych/markdownlint"
    topic: "Markdownlint Rules"
  - url: "https://www.markdownguide.org/basic-syntax/"
    topic: "Markdown Basic Syntax"

📈 Version History

v4.0.0 (2025-11-12)

✨ Context7 MCP integration
✨ Progressive Disclosure structure
✨ 10+ code examples
✨ Primary/secondary agents defined
✨ Best practices checklist
✨ Decision tree
✨ Official references

Generated with: MoAI-ADK Skill Factory v4.0
Last Updated: 2025-11-12
Maintained by: Primary Agent (doc-syncer)