A topic is one authored page in a Markdown content entry. This topic explains the structure and publication metadata of a topic file. Before writing topics, configure Markdown content in the project manifest.

Create topic files under a Markdown content root:

docs/
|-- getting-started/
|   |-- overview.md
|   `-- installation.md
|-- markdown/
|   `-- topics.md
`-- toc.md

With this layout, getting-started/overview.md and markdown/topics.md are topic paths relative to the docs content root.

Use one topic for one task, concept, or reference page. Use stable, lowercase kebab-case filenames:

docs/
`-- markdown/
    |-- content.md
    |-- topics.md
    `-- table-of-contents.md

Use one H1 at the top of each topic:

# Configure logging

Use this topic to configure diagnostic logging.

Start each topic with one H1. DocInsight uses it as the generated page title and does not duplicate it in the topic body.

Use H2 through H6 for sections inside the topic:

# Build output

## Select a target

## Open generated files

Add YAML front matter when the topic needs a stable ID, description, keywords, tags, draft state, document Xref bindings, or custom metadata:

---
id: guide/install
description: Install DocInsight before running the CLI.
keywords: [install, setup]
tags: [getting-started]
draft: true
xref:
  base: mylibrary/MyLibrary.Collections
  aliases:
    list: mylibrary/MyLibrary.Collections/IList{T}
---

# Installation

The opening and closing front matter fences must be --- on their own lines.

DocInsight uses the topic ID in Xrefs from other content entries and Delphi XML documentation. By default, it derives the ID from the topic path without the file extension. Set id when cross-references must remain stable after the file moves. Topic IDs must be unique within the Markdown content entry.

DocInsight reads these front matter keys:

• id: Stable topic ID. It must be unique within the Markdown content entry. If omitted, DocInsight derives the ID from the topic path without the file extension.

• title: Topic title used when the file does not contain an H1.

• description: Topic description used by generated output.

• keywords: String or list of strings.

• tags: String or list of strings.

• draft: Boolean. Use true for unfinished topics. Draft topics are excluded from normal published output.

• xref: Optional document Xref scope with base and aliases. See Configure a document Xref scope.

Unknown keys are preserved as extra metadata for downstream processing. The former name key does not set the topic ID; use id instead.

Set draft: true while a topic is under review:

---
draft: true
---

# New deployment guide

Draft topics are left out of normal published output. If a draft topic has a topic entry in toc.md, DocInsight omits that entry from the generated table of contents. A link from a published topic to a draft topic produces a check diagnostic, so remove the link or finish the draft before publishing.

Drafts are not an access-control mechanism. The source file remains in the project, so do not use drafts for confidential content.

A topic is published only when it is selected by the Markdown content entry, that content entry is included by the selected output target, and the topic is not excluded as a draft. When the content root has toc.md, the TOC provides the main publishing shape. For details, see Organize the table of contents.