# Markdown topics

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 a topic file

Create topic files under a Markdown content root:

text

    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:

text

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

## Add a topic title

Use one H1 at the top of each topic:

markdown

    # 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:

markdown

    # Build output

    ## Select a target

    ## Open generated files

## Add topic metadata

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

markdown

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

## Keep unfinished topics as drafts

Set `draft: true` while a topic is under review:

markdown

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