documentation-structure

name	documentation-structure
description	Validates documentation structural integrity including heading hierarchy, metadata, file naming, navigation, and cross-references. Use when checking documentation organization or validating toctree structure.

Documentation Structure Audit

Scope

Document structure only: heading hierarchy, section ordering, presence of required sections (introduction, prerequisites, steps, reference), file naming, metadata blocks, navigation, and cross-references.

Inputs

• Documentation file(s) under review.
• Documentation directory structure.
• Diataxis classification output (from the documentation-diataxis skill, when run as part of the orchestrated review).

Actions

1. File Naming:

   Verify files use lowercase with dashes and the correct extension for their syntax (for example, connect-vscode.rst for reST, connect-vscode.md for MyST).

2. Metadata:

   Ensure every page has required metadata near the top when the repository's docs conventions require it: .. meta:: after the anchor label for reST, or the MyST equivalent (front matter or meta directive) for Markdown sources.

3. Directory Placement:

   Confirm the file is located in the directory matching its intended Diataxis category (for example, tutorials in tutorial/, how-to guides in how-to/).

4. Navigation:

   Ensure new pages are added to the toctree.

5. Cross-References:

   • Prefer stable reference roles (:ref: for reST, / for MyST) over page-level links.