Skip to content

Write topics, build a map, publish to the web

By the end of this tutorial, you'll understand the full authoring workflow: creating Create and manage topics with rich formatting, organizing them in a hierarchical Create and organize a map, and publishing a polished documentation site.

What you'll build

A five-topic user guide with nested sections, formatted content (tables, code blocks, callouts), and a published site with two levels of navigation depth.

Before you begin

Create a project

  1. From the Projects page, click New Project and name it "Acme Docs."

  2. You land in the project dashboard.

Write a welcome topic

  1. Go to Topics and click New Topic.

  2. Title it "Welcome to Acme."

  3. Write an introductory paragraph.

  4. Type / and select Info Callout. Inside the Add callouts, write a note like: "This documentation covers Acme version 3.0."

  5. Below the callout, add a Heading 2 called "What's covered" and a bullet list summarizing the sections readers will find.

Write a setup topic

  1. Create another topic called "Installation and Setup."

  2. Add a Heading 2 for "System Requirements" and insert a Work with tables with columns for Component, Minimum, and Recommended.

  3. Add a Heading 2 for "Install steps" and write numbered steps.

  4. Add a code block (type / then select Code Block). Set the language to bash and write an install command.

  5. Below the code block, add a Warning Callout noting a common pitfall during installation.

Use the Editor slash commands (/) for block-level elements like headings, tables, code blocks, and callouts. Use the formatting toolbar for inline styles like bold, italic, and code.

Write three more topics

Create these topics with any content you like:

  • "Basic Usage" — describe the core workflow with a mix of paragraphs and lists

  • "Configuration Reference" — use a table listing all configuration options, their types, and defaults

  • "Troubleshooting" — add a few Heading 2 sections, each describing a problem and solution

Each topic should cover a single subject. This keeps topics reusable — they can appear in different Create and organize a map and in different positions without breaking context. See Structuring content for reuse for more on this principle.

Set topic statuses

  1. Open each topic and find the Content statuses dropdown in the top bar.

  2. Change "Welcome to Acme" and "Installation and Setup" to Published.

  3. Leave the others as Draft for now.

Status helps you track which content is ready for readers, but it doesn't affect what gets published. All topics in a map are included in the output regardless of status. To exclude content from specific outputs, use Create conditional content blocks.

Build a map with nesting

  1. Go to Maps and create a map called "Acme User Guide."

  2. Add all five topics in order.

  3. Select "Installation and Setup" and click the indent button to nest it under "Welcome to Acme."

  4. Leave "Basic Usage," "Configuration Reference," and "Troubleshooting" at the top level.

Your map now has two levels: "Welcome to Acme" with a child page, and three standalone pages.

Publish and review

  1. Create a new Web Publication target settings called "Acme Help Center."

  2. Click Publish.

  3. Open the published site.

Notice how the sidebar reflects your nesting — "Welcome to Acme" has an expandable section with "Installation and Setup" underneath. Each page shows its headings in the right-side table of contents.

What you learned

  • Topics are atomic — each one covers a single subject

  • The editor supports rich Format content in the editor through Use slash commands and the toolbar

  • Statuses track content readiness but don't affect what gets published (all map topics are included)

  • Maps define navigation hierarchy through indentation

  • Publishing converts your map into a complete site with search, navigation, and a table of contents

Next: Reuse content with components to eliminate duplication across topics.

See also

Was this page helpful?