--- title: Create and edit pages description: Create task-focused MDX pages with frontmatter, code examples, and built-in documentation components. url: https://pr-6-a9c4e9fe1b6c.thally.app/guides/writing-content --- # Create and edit pages Create task-focused MDX pages with frontmatter, code examples, and built-in documentation components. Use this guide to create one complete MDX page and choose the built-in components that make its task easier to follow. For content strategy, start with [Choose the right content type](/guides/content-types). Create or improve a task-focused page in this Thally project about TASK. You are done when a reader can complete the task without guessing, the page is placed where they will look for it, every product claim is supported by the current implementation, and the project passes its documentation checks and production build. Start by reading AGENTS.md if present, docs.json, package.json, src/data/site.ts, and the pages returned by a repository search for the task, feature names, commands, settings, and related user language. Inspect the source code, CLI help, configuration types, and tests behind any behavior you plan to document. Treat code and tests as evidence; do not turn assumptions, roadmap notes, generic Next.js behavior, or another product's conventions into Thally claims. Prefer improving the existing page that owns the task. Create one new MDX file under src/content only when the task needs its own durable URL. Add a new page to the most relevant docs.json group, keep its navTitle short enough for one sidebar line when practical, and link to prerequisites instead of duplicating them. Write directly to the reader in friendly, concrete language. Include the outcome, prerequisites, ordered steps, exact UI labels or tested commands, realistic examples, expected results, and troubleshooting for the two or three most likely failures. Use code fences with the correct language. Use Note, Warning, Steps, Tabs, Cards, or another built-in component only when it makes the task easier to scan. Never add a second H1 inside the body. Run every safe command you document when the environment permits. Then run npx thally check and npm run build. Start a local preview, inspect the page in light and dark mode at desktop and narrow widths, and check links, navigation, code contrast, overflow, and headings. Fix regressions caused by your changes. Report the user outcome, files changed, evidence used for product claims, commands run, visual checks completed, and any facts that still require a product owner. Do not commit, push, deploy, delete content, or modify unrelated framework internals unless I explicitly ask. ## Create a page Add a file under `src/content/`. Its path becomes the URL, so `src/content/guides/invite-a-member.mdx` is available at `/guides/invite-a-member`. ## MDX basics Every page in Thally is an `.mdx` file — Markdown with JSX support. You can use standard Markdown syntax plus React components inline. ```mdx # Heading Regular paragraph with **bold**, *italic*, and `inline code`. - Bullet lists - Work as expected 1. Numbered lists too ``` ## Frontmatter Every page needs a frontmatter block at the top: ```yaml --- title: Page Title description: A short summary for search results and meta tags. --- ``` | Field | Required | Purpose | | --- | --- | --- | | `title` | Yes | Page heading and sidebar label | | `description` | Yes | Meta description and search snippet | The title from frontmatter is automatically rendered as the page heading — you don't need to add an `# H1` in the body. See the [frontmatter reference](/guides/frontmatter-reference) for search, provenance, visibility, API-operation, and page-layout fields. ## Code blocks Fenced code blocks get syntax highlighting automatically: ````mdx ```javascript const greeting = 'Hello from Thally!' console.log(greeting) ``` ```` Use the `bash`, `typescript`, `python`, `json`, or any other language identifier supported by Shiki. ## Callouts and notes Use the `` component to highlight important information: ```mdx Notes support **Markdown** inside them. This is a warning callout. ``` Available types: `info`, `warning`, `danger`, `tip`. ## Links Standard Markdown links work for both internal and external pages: ```mdx Check the [Quickstart](/quickstart) guide or visit [GitHub](https://github.com). ``` ## Tabs Use `` and `` to show platform-specific or variant content without code blocks: ```mdx Install with Homebrew: \`\`\`bash brew install your-cli \`\`\` Install with apt: \`\`\`bash sudo apt install your-cli \`\`\` ``` Each `` supports full MDX content inside — code blocks, lists, callouts, and more. ## Steps Use `` and `` for sequential instructions with numbered circles and connector lines: ```mdx Run the installer: \`\`\`bash npm install your-package \`\`\` Create a config file and add your API key. ``` ## Cards Use `` and `` to create clickable card grids for landing pages or "next steps" sections: ```mdx Get up and running in five minutes. Explore the full API. ``` Available icons: `book-open`, `code-simple`, `grid-round`, `link-simple`, `wrench`, `party-horn`, `telegram`, `envelope`, `x-twitter`, `message`. ## Images and frames Place images in the `public/` folder and reference them with a leading slash: ```mdx ![Screenshot](/images/image1.jpg) ``` Wrap images in a `` for a styled border with an optional caption. Frames are click-to-zoom by default: ```mdx ![Screenshot](/images/image1.jpg) ``` Disable zoom with ``. For asset organization, alt text, downloads, and review guidance, see [Add images and downloadable files](/guides/images-and-files). ## Heading anchor links Every `h2` and `h3` heading is a permalink. Selecting the heading copies the section URL without adding a visible marker beside it, so you can share a specific answer while keeping the page visually clean. ## Tables Standard Markdown tables render with proper styling: ```mdx | Method | Endpoint | Description | | --- | --- | --- | | GET | /pets | List all pets | | POST | /pets | Create a pet | ``` ## File organization All content lives in `src/content/`. You can use subdirectories to organize related pages: ``` src/content/ introduction.mdx → /introduction (or / for the root) quickstart.mdx → /quickstart guides/ getting-started.mdx → /guides/getting-started writing-content.mdx → /guides/writing-content ``` The URL path matches the file path relative to `src/content/`, minus the `.mdx` extension. ## Add the page to navigation In `docs.json`, add the page ID to the intended group's `pages` array. For the example above, use `"guides/invite-a-member"`. See [Organize your navigation](/guides/configuring-navigation). ## Verify the page Open the page in the [local preview](/guides/preview-locally), follow its instructions, test links and interactive components, then run: ```bash npx thally check npm run build ``` ## Next steps - [Reuse content with snippets](/guides/reusable-snippets) - [Choose a page layout](/guides/page-modes) - [Browse the component reference](/components/badge)