Validation¶

Validate Confluence pages before pushing to catch errors early.

Overview¶

atlcli can validate your local markdown files to detect issues before pushing to Confluence:

• Broken internal links
• Invalid macro syntax
• Page size limits
• Missing required frontmatter
• Orphaned pages

Validate Command¶

Run validation on a sync directory:

atlcli wiki docs validate ./docs

Output:

Validating 24 files...

ERRORS (2):
  getting-started.md:45 - Broken link: [Setup Guide](./setup.md) - file not found
  api-reference.md:12 - Invalid macro: ::: unknown-macro - unrecognized macro type

WARNINGS (3):
  large-guide.md - Page size 485 KB (limit: 500 KB) - consider splitting
  old-docs/legacy.md - Orphaned: not linked from any page
  config.md:78 - Deprecated macro: ::: note - use ::: info instead

Validation complete: 2 errors, 3 warnings

Options:

Validation Rules¶

Link Validation¶

Checks all internal links resolve to existing files:

[Valid Link](./existing-page.md)     ✓
[Broken Link](./missing-page.md)     ✗ File not found
[Anchor Link](./page.md#section)     ✓ (if section exists)

Configure link checking:

# Skip external link validation
atlcli wiki docs validate ./docs --skip-external

# Check external links too (slower)
atlcli wiki docs validate ./docs --check-external

Macro Validation¶

Validates macro syntax and parameters:

::: info                             ✓ Valid panel
::: info "Title"                     ✓ Valid panel with title
::: unknown                          ✗ Unknown macro type
::: expand                           ✗ Missing required title
::: toc minLevel=abc                 ✗ Invalid parameter value

Size Validation¶

Checks page content size against limits:

Configure limits:

atlcli wiki docs validate ./docs --max-page-size 1MB --max-code-block 200KB

Frontmatter Validation¶

Checks required YAML frontmatter:

---
id: "12345"        # Required for existing pages
title: "Page Title" # Required
space: "TEAM"       # Optional, inherited from config
---

Orphan Detection¶

Finds pages not linked from any other page:

atlcli wiki docs validate ./docs --check-orphans

Auto-Fix¶

Some issues can be automatically fixed:

atlcli wiki docs validate ./docs --fix

Auto-fixable issues:

Strict Mode¶

Fail on any issue (useful in CI):

atlcli wiki docs validate ./docs --strict

Exit codes: - 0 - No errors - 1 - Errors found - 2 - Warnings found (in strict mode)

Ignore Patterns¶

Skip certain files or rules:

# Ignore drafts folder
atlcli wiki docs validate ./docs --ignore "drafts/**"

# Ignore specific rules
atlcli wiki docs validate ./docs --ignore-rules orphan,deprecated-macro

Or configure in .atlcli/config.json:

{
  "validation": {
    "ignore": ["drafts/**", "*.draft.md"],
    "ignoreRules": ["orphan"],
    "maxPageSize": "1MB"
  }
}

JSON Output¶

atlcli wiki docs validate ./docs --json

{
  "schemaVersion": "1",
  "valid": false,
  "files": 24,
  "errors": [
    {
      "file": "getting-started.md",
      "line": 45,
      "rule": "broken-link",
      "message": "Broken link: [Setup Guide](./setup.md) - file not found",
      "severity": "error"
    }
  ],
  "warnings": [
    {
      "file": "large-guide.md",
      "rule": "page-size",
      "message": "Page size 485 KB approaching limit (500 KB)",
      "severity": "warning"
    }
  ],
  "summary": {
    "errors": 2,
    "warnings": 3
  }
}

Pre-Push Hook¶

Validate before pushing:

# In package.json or git hooks
atlcli wiki docs validate ./docs --strict && atlcli wiki docs push ./docs

CI Integration¶

GitHub Actions¶

- name: Validate Confluence docs
  run: |
    atlcli wiki docs validate ./docs --strict --json > validation.json
    if [ $? -ne 0 ]; then
      echo "::error::Documentation validation failed"
      cat validation.json | jq -r '.errors[] | "::error file=\(.file),line=\(.line)::\(.message)"'
      exit 1
    fi

GitLab CI¶

validate-docs:
  script:
    - atlcli wiki docs validate ./docs --strict
  allow_failure: false

Use Cases¶

Pre-Commit Validation¶

# .git/hooks/pre-commit
#!/bin/bash
if git diff --cached --name-only | grep -q "^docs/"; then
  atlcli wiki docs validate ./docs --strict
fi

Find All Issues¶

# Get complete report
atlcli wiki docs validate ./docs --json | jq '.errors + .warnings | sort_by(.file)'

Validate Single File¶

# Check specific file
atlcli wiki docs validate ./docs/api-reference.md