Custom Documentation Pages

Custom Documentation Pages let you create additional documentation beyond what the AI generates --- using a block-based editor with drag-and-drop content insertion, rich block types, and a content library sidebar.

Overview

While Archflow's AI Documentation generates comprehensive architecture docs automatically, custom pages give you full control to create supplementary content. Custom pages support:

• Manual and AI creation --- Start from a blank page or let Archie generate structured content
• Nested page hierarchies --- Organize pages in a tree structure with parent/child relationships
• Independent publishing --- Control which custom pages appear in the published documentation
• Rich block types --- Markdown, code, callouts, embedded diagrams, and dividers
• Drag-and-drop content --- Insert architecture elements directly from the Content Library sidebar

Creating a Custom Page

Empty Page

1. Open the Documentation tab in any diagram view
2. Click Add Custom Page in the documentation sidebar
3. Enter a title for the new page
4. Start adding blocks using the block editor

AI-Generated Page

Use Archie to generate a complete custom page based on your architecture:

1. Open Archie and describe the page you want (e.g., "Create a deployment runbook for the payment system")
2. Configure generation parameters:

3. Review the generated blocks and edit as needed before saving

Available templates for AI generation:

Block Types

Custom pages are composed of blocks --- each an independent content section with its own editor.

Markdown Blocks

The primary content block. Features a split editor with:

• Markdown source on the left
• Live rendered preview on the right
• Full markdown syntax including headings, lists, tables, links, and images

Code Blocks

Syntax-highlighted code snippets with a language selector supporting:

• TypeScript, Python, Java, Go, Rust
• SQL, JSON, YAML, Bash
• Plain text

Callout Blocks

Highlighted notices with four variants:

Diagram Blocks

Embed live, interactive diagrams directly in your documentation. Six diagram subtypes:

Divider Blocks

Simple horizontal rules to visually separate content sections.

The Block Editor

Adding Blocks

• Click the + dropdown that appears between existing blocks to insert a new block at that position
• Alternatively, drag a block from the Content Library sidebar to a drop zone
• New blocks are added with a default type that you can change

Editing Blocks

• Click a block to enter edit mode
• Each block has its own Save and Cancel controls
• Change a block's type using the type selector dropdown
• Edit the block title and content independently

Reordering Blocks

• Use the drag handle on the left side of each block to drag and drop
• Use the up/down arrow buttons for precise single-step reordering

Deleting Blocks

• Click the delete button on a block to remove it
• Deletion is immediate --- there is no undo, so be careful

Content Library Sidebar

The Content Library is a collapsible sidebar that provides drag-and-drop access to your architecture elements. Open it from the documentation toolbar.

Available Sections

Using the Content Library

• Drag and drop --- Drag an item from the sidebar onto a drop zone between blocks
• Click to append --- Click an item to add it as a new block at the end of the page
• Search and filter --- Use the search bar to find specific items across all sections

Page Management

Navigation Tree

Custom pages appear in a tree structure in the documentation sidebar. Pages can be:

• Nested under other custom pages to create hierarchies
• Reordered within the tree using drag-and-drop
• Expanded/collapsed to manage large page trees

Page Metadata

Each custom page has:

• Title --- Displayed in the sidebar and page header
• Description --- Optional summary shown in the page header
• Icon --- Optional icon for the sidebar navigation

Publishing Control

• Toggle page visibility independently with the publish switch
• Hidden pages are excluded from the published documentation view
• Child pages inherit their parent's published state unless overridden

Published View

When documentation is published, custom pages render as read-only content:

• All block types render in their final presentation format
• Interactive diagrams are preserved --- users can pan, zoom, and inspect elements
• Code blocks retain syntax highlighting
• Callouts display with their styled variants
• The page tree structure is maintained in published navigation

Best Practices

• Start with AI templates for common documentation types, then customize the generated blocks
• Use callout blocks to highlight important decisions, warnings, and architectural constraints
• Embed live diagrams rather than screenshots --- they stay up to date as your architecture evolves
• Organize with nesting --- Group related pages under parent pages (e.g., "Deployment Guides" → per-environment pages)
• Combine AI and manual content --- Let Archie generate the initial structure, then add your team's specific knowledge

Next Steps