• 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.)

• 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.

INDEX.md

.md

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

INDEX.md

• 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

---
title: "Section Title"

• my-label

Brief intro summarizing the section.

---
title: API Reference
subtitle: "Reference — Project Docs v1.0"
date: "2026-03-09"
author: "Engineering Team"
confluence_ignore: false
confluence_labels:
  - api
  - reference
confluence_properties:
  - id: status
    fields:
      Owner: "Engineering Team"
      Classification: Internal
      Status: "{status:Green|Published}"
      Version: v1.0
      Reviewed on: 2026-03-05
---

• 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

confluence_properties

**Document Version**: 1.0
**Status**: Draft (Proposal)
**Classification**: Internal
**Last Updated**: March 7, 2026
**Author**: Engineering Team
**Owner**: Platform Team

• 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

• 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

##

• 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.

One-line summary of what this document covers.

1. Section One
2. Section Two

• Status badges — Use

  {status:Color|Text}

  syntax in property fields (e.g.,

  {status:Green|Published}

  )
• 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.

• 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.