document wiki writer pages template format

[mrjf]

https://github.com/githubnext/agentics/blob/main/docs/agentic-wiki-writer.md needs to describe the pages.md file and how it's generated automatically, editable, can be supplied at the start, how to include literal text, what the formatting of the sections is, etc.

The format is like the below, but verify the exact behavior of the workflow:

Wiki Definition Format

Define your entire wiki structure in a single markdown file. The parser transforms this into individual wiki pages and sub-page sections with an auto-generated sidebar.

You can provide the PAGES.md file yourself, or one will be built for you the first time you generate documentation, after which you may edit it as you see fit.

Header Hierarchy

Level	Purpose	Output
H1 (#)	Top-level page	Separate .md file, top-level sidebar entry
H2 (##)	Nested page	Separate .md file, indented under parent in sidebar
H3 (###)	Deeply nested page	Separate .md file, further indented in sidebar
H4+ (####)	Section within page	H2+ header in rendered page, not in sidebar nav
H4+ with + (####+)	Sidebar section	H2+ header in page, included in sidebar nav

Query Templates

Use *{ query }* syntax to mark content that should be AI-generated:

# Home

*{ Provide an overview of this project }*

## Architecture

*{ Describe the system architecture and key design decisions }*

Static text is preserved as-is:

# Getting Started

This guide will help you set up the project.

*{ List the installation steps }*

For more help, see the troubleshooting section.

Sidebar Sections

By default, H4+ headers become sections within a page but don't appear in the sidebar. Add + after the hashes to include them:

# API Reference

*{ Overview of the API }*

####+ Authentication
*{ Describe auth flow }*

####+ Rate Limits
*{ Describe rate limiting }*

#### Internal Details
*{ Implementation details - not shown in sidebar }*

This generates:

• Sidebar: API Reference with nested links to #Authentication and #Rate Limits
• Page: All three sections rendered as H2 headers

Complete Example

# Home

Welcome to the project documentation.

*{ Provide a brief overview of the project }*

# Architecture

*{ Describe the high-level architecture }*

## Frontend

*{ Describe the frontend stack }*

### Components

*{ List major React components }*

####+ State Management
*{ Explain how state is managed }*

####+ Routing
*{ Describe the routing setup }*

## Backend

*{ Describe the backend architecture }*

### API

*{ Document the REST API }*

####+ Endpoints
*{ List all endpoints }*

# Getting Started

*{ Write a getting started guide }*

#### Prerequisites
*{ List prerequisites }*

#### Installation
*{ Installation steps }*

Output Files

File	Content
Home.md	H1 title + overview content
Architecture.md	H1 title + architecture content
Frontend.md	H1 title + frontend content + State Management (H2) + Routing (H2) sections
Components.md	H1 title + components content
Backend.md	H1 title + backend content
API.md	H1 title + API content + Endpoints (H2) section
Getting-Started.md	H1 title + guide content + Prerequisites (H2) + Installation (H2) sections
_Sidebar.md	Auto-generated navigation

Generated Sidebar

- [[Home|Home]]
- [[Architecture|Architecture]]
  - [[Frontend|Frontend]]
    - [[State Management|Frontend#State-Management]]
    - [[Routing|Frontend#Routing]]
    - [[Components|Components]]
  - [[Backend|Backend]]
    - [[API|API]]
      - [[Endpoints|API#Endpoints]]
- [[Getting Started|Getting-Started]]

Header Normalization

Sections (H4-H6) are normalized when rendered to individual pages:

Definition	Rendered
####	##
#####	###
######	####

This keeps page structure clean—every page starts with H1 (the title), and sections start at H2.

Slug Generation

Page and section slugs are generated from titles:

• Spaces → hyphens
• Special characters removed
• Multiple hyphens collapsed

Title	Slug
Getting Started	Getting-Started
What's New?	Whats-New
API Reference (v2)	API-Reference-v2