new-doc-page

Prompt file imported from arkitektio/arkitektio.github.io (.github/prompts/new-doc-page.prompt.md). Copyright stays with the author.

New Documentation Page

Create a new documentation page in this Docusaurus project following the established conventions.

Gather inputs

Determine from the user's request:

1. Title — the display title for the page.
2. Section — which docs/ subdirectory it belongs to (e.g. design/services, apps/plugins, introduction/first_steps). If the section doesn't exist yet, create the directory.
3. Page type — one of:
   • Leaf page — a single .mdx file (default).
   • Category index — an index.mdx (or index.md) that introduces a new sub-section.
4. Sidebar position — a number controlling sort order among siblings. If not specified, look at existing siblings and pick the next available number.
5. File extension — .mdx if the page will use React/JSX components (imports, custom components), .md if it's plain Markdown. Default to .mdx.

If any of these are ambiguous, infer reasonable defaults from the target section's existing pages rather than asking.

Conventions to follow

• Frontmatter — every page must start with YAML frontmatter:

---
id: <kebab-case-identifier>
title: "<Title>"
sidebar_label: "<Short Label>"
sidebar_position: <number>
---

• Sidebar — this project uses autogenerated sidebars, so ordering is controlled entirely by sidebar_position in frontmatter. Do NOT edit sidebars.js.
• Category directories — when creating a new sub-section, provide either:
  • An index.mdx with frontmatter (preferred in this project), or
  • A _category_.json with label, position, and optionally a link field.
• Images / assets — place media files (.png, .webm, etc.) next to the .mdx file that references them, not in static/.
• Imports — for ideal images use import Image from "@theme/IdealImage";. Only add imports when the page actually needs them.

Steps

1. Determine the full file path under docs/ based on the section and page type.
2. Check existing siblings in the target directory to pick a sensible sidebar_position.
3. Create the file with proper frontmatter and a starter body containing:
   • A one-line description paragraph (placeholder if none given).
   • An ## Overview heading ready for content.
4. If creating a new category, also ensure the parent directory exists and create the index.mdx for it.
5. Inspect similar existing pages in the target section to understand what the current implementations are like to inform the new page.
6. Summarise what was created and where, so the user knows the next step is to fill in the content.