Writing

In svedocs, the file tree is also the structure of the site. File names and frontmatter determine routes, sidebar order, page outlines, search results, SEO data, and Ask AI citations.

This section covers how to organize that content and write pages that are easy to read and easy to find.

Where files go

Most projects use two content roots:

Root	Purpose	Route shape
content/docs	Product docs, guides, tutorials, API explanations, integration notes.	/docs/...
content/pages	Landing pages, changelog pages, standalone product pages.	/...

Put guides and reference material in docs when they belong in the sidebar. Use pages for home pages, changelogs, and other standalone content.

File formats

Format	Use it for
.md	Most documentation: prose, tables, code blocks, callouts, math, and images.
.svx	Pages that need Svelte components, interactive examples, or richer local composition.
.mdx	MDX-style authoring when you prefer that extension; svedocs still compiles it through the Svelte-compatible pipeline.

Start with Markdown. Move to SVX only when the page needs interactivity.

Recommended page shape

A useful docs page usually has:

1. A specific title and description.
2. A short opening paragraph that explains who the page is for.
3. A working example near the top.
4. Sections that map to user tasks, not internal implementation details.
5. A troubleshooting or next-steps section when the workflow can fail.

Markdowncontent/docs/deploy.md
1---2title: Deploy3description: Build and deploy the docs site to Cloudflare Pages.4order: 45---67# Deploy89This guide shows the default edge deployment path.1011## Build1213Run the production build first.

Navigation and ordering

The sidebar is generated from the file tree and frontmatter:

• order moves pages and groups above alphabetical sorting.
• navTitle shortens the sidebar label without changing the page title.
• collapsed controls whether a group starts collapsed.
• hidden removes a page from navigation and generated public lists.
• icon passes an icon hint to the default theme.

Directory index pages are important. A file like content/docs/configuration/index.md represents the group landing page for /docs/configuration.

Search and Ask AI quality

Search records are created from pages and headings. Ask AI citations also use these records, so clear headings directly improve retrieval quality.

Prefer:

• Task-focused headings: Configure Algolia, Deploy to Cloudflare Pages.
• Specific descriptions: one sentence that says what the page helps users accomplish.
• Short examples with real file names.
• Stable anchor names for pages that other docs link to.

Avoid:

• Many pages with the same title.
• Generic headings like Usage, Options, or More.
• Long code blocks without explanation.
• Hiding pages that should still be discoverable in search.

Section guide

• Content: frontmatter, Markdown features, code blocks, diffs, links, assets, and section extraction.
• Components: Svelte components, custom layouts, and theme composition.

Documentation workflow

Use this loop while writing:

Shell
1pnpm dev2pnpm check3pnpm build

Run pnpm check regularly. It catches broken links, route conflicts, and missing metadata before they become harder to spot in a large site.