Skip to main content

​
Home and Publishing

The editor workspace is split into two tabs: Home and Publishing. Home is your workspace. It shows the content files in your repository, including your private pages, whether or not they appear on your published site. Publishing is your published site. It shows the navigation your visitors see, along with your site settings. Home hides some files by default, including docs.json, files and folders whose names start with a dot, files with no extension, all-caps Markdown files like README.md, and .css, .js, .jsx, .mjs, .cjs, and .pdf files. To see all files, turn on Show all files or press Cmd + Shift + . (macOS) or Ctrl + Shift + . (Windows).

​
Create a page

To add a page to your navigation, click the plus button on the navigation element where you want it. Enter a name for your page. The editor adds the .mdx extension for you.

​
Add media

Type /image or /video to upload a file or pick one already in your repository. You can also drag files from your computer onto the page. To reuse media, drag an image or video from the navigation tree onto a page.
  • Uploads save to your images/ and videos/ folders and commit with your next publish.
  • Supported formats are PNG, JPG, JPEG, GIF, WebP, SVG, MP4, and WebM.
  • To serve different images in light and dark mode, hover an inserted image and use Light/dark variants.
  • Type /embed and paste a YouTube, Loom, or Vimeo URL to generate the iframe. For anything else, toggle Manual embed to write custom HTML.
For formatting images and using the Frame component, see Images and embeds.

​
Organize navigation

Drag elements in the Navigation view to reorder or nest them. The editor writes your changes to docs.json when you publish.
  • Groups: Collapsible sections that cluster related pages. Can nest inside other groups.
  • Tabs: Top-level sections with horizontal navigation. Use these for distinct areas like API reference and guides.
  • Anchors: Persistent items at the top of your sidebar. Useful for external resources. Can be global, appearing on every page.
  • Dropdowns: Expandable menus at the top of your sidebar. A lighter alternative to tabs.
  • Menus: Dropdown items within a tab that link directly to specific pages.
  • Products: A switcher for multiple product documentation sets, each with its own navigation.
  • Versions: A switcher for multiple simultaneous documentation versions.
  • Languages: A switcher for documentation in multiple languages.
Some elements can’t nest inside others. Tabs can’t nest inside groups, for example. The editor prevents invalid combinations.
To change a page’s title, slug, description, or layout, open its settings from the navigation tree. See Pages for more information on specific settings.

​
Delete a page

To delete a page, click More options in the top-right of the page, then click Move to trash. You can also delete a page from its options menu in the navigation tree. For private pages, the menu shows Delete page. Deleting a page removes both the file and its navigation entry. To remove a page from your published navigation without deleting its file, select Remove from publishing in the page’s options menu in the navigation tree. Editors and admins can delete pages.

​
Version history

Version history lets you review and restore earlier saved versions of a page. It isn’t available for docs.json. Viewers can review and compare saved versions of private pages. Editors and admins can restore them. The editor records a new entry whenever content differs from the latest recorded version. Version history is branch-scoped. Only the current branch’s version history is available. To view version history, click More options in the top-right of the page, then click Version history. If you restore a version, it overwrites any unsaved changes you made to the page. When you restore a public page, it is only restored on your current branch. When you restore a private page, it is restored on all branches.

​
Private pages

Private pages are drafts that live in the Personal section of the Home tab. They are private to you, are not committed to your repository, and never appear on your published site. To create a private page or folder, click the plus button on the Personal section header, then select New page or New folder. Dragging a private page or folder into your workspace makes it available to your collaborators immediately, though it is not added to your site navigation.
You can’t move workspace content back to the Personal section. Making a private page public is a one-way change.