format-docs

Format Docs

Prepare markdown documents for clean Confluence publishing via orbit confluence publish. This skill analyzes and transforms markdown files — individually or as a directory tree — to follow the conventions that Confluence expects.

When to Use

• Before running orbit confluence publish for the first time on a docs directory
• When adding new markdown files to an existing published docs tree
• When docs render poorly in Confluence and need structural fixes
• When migrating docs from another system (GitHub wiki, Notion export, etc.)

Process

1. Assess the Scope

Determine whether the user is asking about a single file or a directory.

• Single file: Read it and apply the file-level checks below.
• Directory: List the full tree, then work through both directory-level and file-level checks.

2. Directory-Level Checks

If formatting a directory, verify and fix these structural issues:

INDEX.md files — Every directory that contains markdown files needs an INDEX.md. This file becomes the parent page in Confluence for all sibling .md files.

docs/
  INDEX.md              ← Required: parent page for docs/
  overview.md
  api/
    INDEX.md            ← Required: parent page for api/
    endpoints.md

If an INDEX.md is missing, create one with:

• Frontmatter (title from directory name, today's date)
• A brief intro line
• A properties report directive (see below)
• Child page tables wrapped in confluence ignore blocks

INDEX.md structure — Every INDEX.md must follow this pattern:

---
title: "Section Title"

Key rules for INDEX.md files:

1. Properties report directive — Add a <!-- confluence:properties-report --> directive after the intro content. This generates a dynamic table on Confluence that pulls metadata from all child pages sharing the same label. Use ancestor = currentContent() to scope to child pages, and match the label from confluence_labels.
2. Confluence ignore blocks — Wrap all child page listing content (section headings, tables, links) between <!-- confluence:ignore-start --> and <!-- confluence:ignore-end -->. This content is only visible in markdown viewers (GitHub, local); on Confluence, the properties report replaces it.
3. Label alignment — The label value in the CQL query must match one of the confluence_labels defined in the child pages' frontmatter. Use the same label across all siblings so the report captures them all.
4. Report headings — Include at minimum: Owner,Status,Version,Reviewed on. These must match field names in the children's confluence_properties.

File naming — Rename files that would cause URL issues:

• Use lowercase with hyphens: api-reference.md not API Reference.md
• No spaces, underscores, or special characters in filenames
• No version numbers in filenames — track versions in frontmatter instead

Flat nesting — Confluence page trees work best with one level of topic directories under the root. If the directory has deeply nested subdirectories (3+ levels), suggest flattening.

3. File-Level Checks

For each markdown file, check and fix the following. Read the formatting reference for detailed rules on each item.

Frontmatter

Every file needs YAML frontmatter with all standard fields populated. Frontmatter is the single source of truth for document metadata — any metadata that exists in the frontmatter must NOT be duplicated in the document body.

Always use the full frontmatter template:

When adding or completing frontmatter:

• Derive title from the first # heading if present, otherwise from the filename
• Set date to today's date
• Derive author from inline metadata if present, otherwise from existing sibling files or ask the user
• Derive subtitle from document context (e.g., "ADR — Project v1.0", "Guide — Team Docs")
• Suggest confluence_labels based on the directory name and content
• Always include confluence_properties with at minimum: Owner, Classification, Status, Version, and Reviewed on
• Populate property values from inline metadata found in the document body when available
• Set confluence_ignore: false by default. Only set to true when the user explicitly wants to exclude a file from Confluence publishing (previously published pages will be deleted on next sync)
• Never overwrite existing confluence_page_id or confluence_url

Remove Redundant Inline Metadata

After populating the frontmatter, remove any inline metadata blocks from the document body that duplicate information already captured in the frontmatter or confluence_properties. These blocks typically appear near the top of the document as bold-key/value lines or small tables.

Patterns to detect and remove:

Also detect and remove metadata presented as:

• Key-value lines: Version: 1.0 or Status: Draft
• Small two-column tables with metadata-like headers (e.g., | Field | Value |)
• Blockquote metadata: > **Version**: 1.0

Rules for removal:

• Only remove metadata lines/blocks where the information is already captured in frontmatter fields or confluence_properties fields
• If an inline metadata block contains values not yet in frontmatter, absorb them into frontmatter first, then remove the block
• Preserve any surrounding content — only strip the metadata lines themselves
• If the metadata block is followed by a blank line or horizontal rule, remove the separator too to avoid orphaned whitespace

Heading Hierarchy

The converter skips the first # heading (Confluence uses the page title instead), so the document body should use ## as the top-level section heading.

Fix these issues:

• Multiple # headings — Keep only the first one (it becomes the title). Convert subsequent # to ##.
• Heading gaps — Don't jump from ## to ####. Fill in the hierarchy.
• No # heading — If the file has no # heading but has a title in frontmatter, that's fine. If it has neither, add a # heading derived from the filename.

Document Structure

Well-structured documents follow this pattern:

Apply these structural improvements:

• Add a TOC if the document has 3+ sections (## headings). Wrap the TOC section (heading + list) with <!-- confluence:toc-start --> / <!-- confluence:toc-end --> directives so it gets replaced with the Confluence TOC macro on publish. The markdown TOC remains visible in GitHub/local renderers.
• Add horizontal rules (---) between major sections for visual separation.
• Add a summary blockquote after the title if the document jumps straight into content without context.

Cross-References

If the file is part of a directory being formatted, add a Cross-References section near the bottom linking to related sibling documents:

Use relative paths so links resolve correctly both locally and in Confluence.

Revision History

For documents that will be actively maintained, add a revision history table at the bottom:

Only add this if the document doesn't already have one.

4. Content Formatting

Fix markdown patterns that don't convert well to Confluence:

5. Diagram Formatting

Fenced code blocks with diagram languages (mermaid, plantuml, graphviz, d2, etc.) are rendered as PNG images via Kroki during Confluence publishing (the public https://kroki.io, or a self-hosted instance the profile names). Orbit auto-sanitizes common issues, but source diagrams should follow these rules for best results.

That is the default (--diagrams kroki). Two other strategies exist and change what the rules below are worth:

Under markdown-macro the auto-fixes below are not applied — they work around the Mermaid build Kroki renders with, and the macro's app renders with its own (htmlLabels: true), so <br/> in a label is a line break rather than something to strip. The manual fixes further down still apply: they are about writing valid diagrams, not about Kroki.

Auto-fixed by orbit (no manual action needed, kroki strategy only):

• <br/> tags in participant names, notes, and messages → stripped
• Parenthesized suffixes in participant aliases: Worker (queue) → Worker - queue
• Trailing () on participant names → removed
• Port numbers after colons: API:8000 → API
• Reverse arrows: Client<<--API: msg → API-->>Client: msg

Must be fixed manually when formatting docs:

Diagram type selection:

When encountering ASCII art or text-based diagrams in documents being formatted, convert them to the appropriate diagram language. If the diagram is too complex to convert confidently, leave it as a plain code block with a text language tag.

6. Confluence-Specific Enhancements

These are optional improvements that use Confluence features:

• Status badges — Use {status:Color|Text} syntax in property fields (e.g., {status:Green|Published}). Emoji shortcodes (:green_circle: Green) are also supported.
• Confluence ignore blocks — Wrap sections that should only appear in markdown (not Confluence) with <!-- confluence:ignore-start --> and <!-- confluence:ignore-end -->. In INDEX.md files, all child page tables must be wrapped (see Directory-Level Checks above).
• Properties report — Every INDEX.md must include a properties report directive. See the INDEX.md structure in Directory-Level Checks for the exact pattern.

7. Dry Run

After making changes, suggest the user verify with:

This previews what would be published without making changes.

Rules

• Never delete content — only restructure and add metadata.
• Never overwrite confluence_page_id or confluence_url — these are managed by orbit confluence publish.
• Preserve existing frontmatter fields — add missing ones, don't remove existing ones.
• When in doubt about a title, derive it from the # heading first, then from the filename.
• Keep changes minimal — don't rewrite prose, don't reorganize sections unless the heading hierarchy is broken.
• Show the user a summary of changes before applying them to a large directory.