Skip to main content

Creating topics

In Docusaurus, content pages live under docs/. At 3di, we call each of those pages a topic.

This page explains how to create a topic file, where to save it, and which front matter this template expects.

Prerequisites​

  • You need a local version of the project on your PC.
    For more information, see Getting started.
Live preview

For a live preview, start a local server, and check the output in your browser.

Project structure​

Topics always live under the docs/ folder at the repository root.

Focument typeLocation
Product / project docs for readersdocs/<section>/… — create a folder per section (for example docs/user-guide/)
Template how-to pages (this site)docs/template-description/…
Shared reusable snippets (not standalone pages)docs/_includes/ — see Reusing content with includes
Shared content variables (short strings)docs/_variables/ — see Reusing content with variables
Naming convention

Use lowercase folders and kebab-case file names: docs/user-guide/getting-started.mdx. That path becomes the URL and the doc ID used in sidebars.js.

Creating a topic​

  1. Under docs/, create the section folder if it doesn't exist yet (for example docs/user-guide/).
  2. Create a new file with the .mdx extension, for example getting-started.mdx.
  3. At the top of the file, add front matter.
    See Creating front matter.
  4. Below the front matter, add a single top-level heading (#) that matches the topic title, then write the body.
  5. Save the file.
Use .mdx by default

Create new topics as .mdx files, even when you write plain Markdown inside them.

.mdx supports everything this template uses: front matter, admonitions, tabs, tables, HTML blocks, and imports. An .md file may work for very simple pages, but imports and some MDX features can fail or behave differently.

Example topic file​

docs/user-guide/getting-started.mdx
---
title: Getting started
description: Install the product and open the first workspace.
---

# Getting started

Welcome to the user guide. Follow the steps below to get started.

Resulting URL​

The site URL is derived from the path under docs/ (no file extension):

docs/user-guide/getting-started.mdx → /docs/user-guide/getting-started

Creating front matter​

Front matter is the YAML block between --- lines at the very top of the file. Use it to specify the page metadata.

FieldPurpose
titlePage title in the browser tab and search
descriptionShort summary for search and link previews

Example front matter​

docs/user-guide/getting-started.mdx
---
title: Getting started
description: Install the product and open the first workspace.
---

# Getting started

Adding the topic to the sidebar​

To display the topic in the left-hand navigation, you need to add the topic to the sidebar.

For more information, see Sidebar and table of contents.

Previewing the topic locally​

  1. From the repository root, run npm start.
  2. Open the URL shown in the terminal, usually http://localhost:3000/.
  3. Open the topic from the sidebar, or go directly to /docs/… using the path from Resulting URL.
  4. Confirm that the title, description (used later in the search), and body look correct.
  5. Before you push, optionally run npm run build — this template fails the build on broken links (onBrokenLinks: 'throw').

On this page: