# Writedocs

> Documentation sites from a writedocs.json file and a folder of Markdown pages.

## Get started

### Get started

- [Introduction](https://preview.writedocs.io/index.md): What Writedocs is, and what a documentation site built with it includes.
- [Quickstart](https://preview.writedocs.io/docs/quickstart.md): Install Writedocs, create a project and preview it locally.
- [Project structure](https://preview.writedocs.io/docs/project-structure.md): How a Writedocs project is laid out - which files become pages, where the home page is, and where images, snippets and styles go.
- [CLI Reference](https://preview.writedocs.io/docs/cli.md): Every writedocs command and flag.

### Migrate

- [Migrating from Mintlify](https://preview.writedocs.io/docs/migrating-from-mintlify.md): Which Mintlify MDX renders unchanged in writedocs, and what still needs an edit.
- [Migrating from the previous writedocs](https://preview.writedocs.io/docs/migrating-from-writedocs-v1.md): Turn a config.json from the previous writedocs into writedocs.json.

## Configuration

### writedocs.json

- [writedocs.json](https://preview.writedocs.io/docs/configuration/overview.md): The file that describes your site - every top-level field, with links to the details.

### Navigation

- [Navigation basics](https://preview.writedocs.io/docs/configuration/navigation-basics.md): A sidebar of pages, groups and links - the simplest form of writedocs.json's navigation.
- [Tabs, versions, languages and products](https://preview.writedocs.io/docs/configuration/navigation-advanced.md): More than one sidebar - tabs, versions, languages, products and dropdowns, and how they nest.
- [Hidden sections](https://preview.writedocs.io/docs/configuration/hidden-sections.md): Tabs, products, versions, languages or dropdowns that nothing links to - docs for a different audience, reached by their address, with a search of their own.
- [Redirects](https://preview.writedocs.io/docs/configuration/redirects.md): Send old addresses to new ones, and how the site's address and folder addresses lead to a page.

### Look and feel

- [Colors and backgrounds](https://preview.writedocs.io/docs/configuration/colors.md): The brand color, text color, navbar and page background - for light and dark mode.
- [Logo and favicon](https://preview.writedocs.io/docs/configuration/logo-and-favicon.md): The logo in the topbar and footer, with a version for dark mode, and the icon in the browser tab.
- [Fonts](https://preview.writedocs.io/docs/configuration/fonts.md): Use a Google Font, your own font file, or a hosted font - for the whole site, or separately for headings and body text.
- [Code themes](https://preview.writedocs.io/docs/configuration/code-themes.md): The color themes of code blocks in light and dark mode, and highlighting a language as another.
- [Topbar, footer and socials](https://preview.writedocs.io/docs/configuration/topbar-and-socials.md): Links at the top right of every page, columns of links and a logo in the footer, and links to your profiles.
- [Banner and 404 page](https://preview.writedocs.io/docs/configuration/banner-and-404.md): An announcement strip above the topbar, and the page shown for an address that doesn't exist.
- [Custom CSS and scripts](https://preview.writedocs.io/docs/configuration/custom-code.md): Add your own styles and scripts - drop a .css or .js file in the project, or list scripts in writedocs.json.

### Search and AI

- [Search](https://preview.writedocs.io/docs/search.md): Search is built into every site - nothing to set up. What it finds, and how it follows versions, languages and products.
- [Contextual menu](https://preview.writedocs.io/docs/configuration/context-menu.md): The "Copy page" menu and a .md copy of every page — on by default; writedocs.json's contextMenu picks the options or turns it off.
- [llms.txt and llms-full.txt](https://preview.writedocs.io/docs/configuration/llms-txt.md): The always-on, zero-config site index and full-content export AI tools look for.
- [MCP server](https://preview.writedocs.io/docs/configuration/mcp.md): An MCP server at /mcp, so AI tools like Claude and Cursor can search and read your docs.

### SEO and analytics

- [SEO and sitemap](https://preview.writedocs.io/docs/configuration/seo-and-sitemap.md): The site's domain, sitemap.xml, robots.txt, canonical URLs, structured data, and the title and meta tags search engines and social media read - for the whole site, and page by page.
- [Integrations](https://preview.writedocs.io/docs/configuration/integrations.md): Turn on Google Analytics 4, Google Tag Manager, Plausible, Fathom, PostHog, Umami or an Ask AI chat widget with the ID from your account - and a consent banner that asks before analytics load.

## Content

### Pages

- [Markdown basics](https://preview.writedocs.io/docs/content/markdown.md): How to write a page - text, headings, links, lists, tables, images and HTML - and what .md and .mdx files can each do.
- [Frontmatter](https://preview.writedocs.io/docs/content/frontmatter.md): The fields at the top of a page - its title and description, address, layout, how it shows in the sidebar, and its meta tags.
- [Page modes](https://preview.writedocs.io/docs/content/page-modes.md): A page's mode sets its layout - the usual one, wider, without a sidebar, a blank canvas under the topbar, or nothing at all.

### Writing

- [Code blocks](https://preview.writedocs.io/docs/content/code-blocks.md): Syntax highlighting, titles, icons, line and word highlighting, focus, diffs, line numbers, wrapping and collapsible blocks.
- [Diagrams](https://preview.writedocs.io/docs/content/diagrams.md): Draw flowcharts, sequence diagrams and more with a mermaid code block.
- [Math](https://preview.writedocs.io/docs/content/math.md): Write equations in LaTeX between dollar signs - inline or as a block.
- [Variables](https://preview.writedocs.io/docs/content/variables.md): Write a product name, a version or an email address once in writedocs.json, and use it in every page.
- [Snippets](https://preview.writedocs.io/docs/content/snippets.md): Reusable MDX prose and real React components, shared across pages via a snippets/ folder.

## Components

- [Components](https://preview.writedocs.io/docs/content/components.md): Every component you can use in a page - callouts, cards, tabs, steps, code groups and more - with no imports.

### Callouts and text

- [Callout](https://preview.writedocs.io/docs/content/components/callout.md): A highlighted box that sets a note, tip, warning or danger apart from the text around it.
- [Hint](https://preview.writedocs.io/docs/content/components/hint.md): A word with a dotted underline that shows a tooltip - to explain a term without leaving the sentence.
- [Badge](https://preview.writedocs.io/docs/content/components/badge.md): A small inline label for status indicators, version tags, or metadata.
- [Icon](https://preview.writedocs.io/docs/content/components/icon.md): An icon or a small image in the text - and the icons you can use anywhere an icon is accepted.

### Layout

- [Card and CardGroup](https://preview.writedocs.io/docs/content/components/card.md): Cards that link to a page - with an icon, an image or an HTTP method - and a grid that lays out cards or anything else in columns.
- [Tile](https://preview.writedocs.io/docs/content/components/tile.md): A visual preview card - an image on a patterned background, with a title and description.
- [Panel](https://preview.writedocs.io/docs/content/components/panel.md): Content pinned to the right-hand column, in place of the table of contents - in view while the reader scrolls.

### Organizing content

- [Tabs and Tab](https://preview.writedocs.io/docs/content/components/tabs.md): The same place in a page, with a tab per option - per operating system, package manager or plan.
- [Accordion and AccordionGroup](https://preview.writedocs.io/docs/content/components/accordion.md): Sections that open and close - for FAQs, optional details, and long content the reader may skip.
- [Steps and Step](https://preview.writedocs.io/docs/content/components/steps.md): A numbered procedure, with a line connecting its steps.
- [View](https://preview.writedocs.io/docs/content/components/view.md): Versions of the same content - per language or framework - with one switcher for the whole page.
- [Visibility](https://preview.writedocs.io/docs/content/components/visibility.md): Content only for people reading the site, or only for AI tools reading the page's Markdown.

### Code

- [CodeGroup](https://preview.writedocs.io/docs/content/components/code-group.md): Several code blocks in one box, one at a time - with tabs, or a menu.
- [CodeBlock](https://preview.writedocs.io/docs/content/components/code-block.md): A code block built from props - for code that comes from a variable or a component.
- [RequestExample and ResponseExample](https://preview.writedocs.io/docs/content/components/request-response-example.md): A request and its response, pinned in the right-hand column beside the page - the layout of an API reference page.

### Media

- [Image](https://preview.writedocs.io/docs/content/components/image.md): An image with a size, a caption, and a different version for dark mode.
- [Frame](https://preview.writedocs.io/docs/content/components/frame.md): A border, rounded corners and a caption around anything - an image, a video, an embed.
- [Video](https://preview.writedocs.io/docs/content/components/video.md): A video file with playback controls, or a YouTube, Vimeo or Loom video - with a width and a caption.

### Reference

- [Parameter and Expandable](https://preview.writedocs.io/docs/content/components/parameter.md): A field's name, type and description - for API parameters, response fields and configuration options - with nested fields that open and close.
- [Searchbar](https://preview.writedocs.io/docs/content/components/searchbar.md): A box above a table that filters its rows as the reader types.
- [Tree](https://preview.writedocs.io/docs/content/components/tree.md): A file and folder tree with collapsible folders and keyboard navigation.
- [Update](https://preview.writedocs.io/docs/content/components/update.md): Changelog entries with a date or version label, a description, and tag filters.
- [Color](https://preview.writedocs.io/docs/content/components/color.md): Color swatches with their values - click one to copy its value.
- [Prompt](https://preview.writedocs.io/docs/content/components/prompt.md): A ready-made AI prompt readers can copy, or open directly in Cursor.
- [GitHub repository](https://preview.writedocs.io/docs/content/components/github.md): A card for a public GitHub repository, with its description, stars and forks.

## API reference

### OpenAPI

- [API reference](https://preview.writedocs.io/docs/openapi/overview.md): Turn an OpenAPI spec into an API reference - a page per endpoint, with parameters, responses, examples and a Try it playground.
- [More specs, and your own pages](https://preview.writedocs.io/docs/openapi/multi-spec-and-overrides.md): Several OpenAPI specs in one site, API groups inside tabs, and replacing a generated endpoint page with one you write.
- [Try it playground](https://preview.writedocs.io/docs/configuration/api-settings.md): How the API reference's Try it playground sends requests, and writedocs.json's api.proxy setting.

### Example API

#### Pets

- [List all pets](https://preview.writedocs.io/api/pets/get-pets.md): GET /pets
- [Create a pet](https://preview.writedocs.io/api/pets/post-pets.md): POST /pets
- [Get a pet by ID](https://preview.writedocs.io/api/pets/get-pets-petid.md): GET /pets/{petId}