Skip to main content

New to the editor? Start with the tutorial.

Create a branch, make a change, share a preview, and publish.
Use the editor to write and publish documentation in your browser. The editor uses a docs-as-code workflow with all your changes backed by Git. Your work saves as commits in your repository and the editor manages Git operations for you. The editor loads by default when you open your dashboard. Anyone in your organization can open it, but certain actions depend on your role. Admins and editors can edit and publish. Viewers can browse content and leave comments and suggestions.

​
How the editor works

Changes save automatically, but saving is separate from publishing. As you type, the editor stores your work. Your changes persist across tabs, devices, and network interruptions. For any changes to reach your live site, you must publish them. Publishing writes to Git. When you publish, the editor commits your changes to your repository. If you publish to your deployment branch, this updates your live site immediately. On a feature branch, your edits commit to the branch automatically and open a pull request for review. Nothing on a feature branch reaches your live site until it merges into your deployment branch. Git stays in sync. When someone pushes to your repository, those changes appear automatically. You don’t need to pull or refresh. The editor merges non-conflicting changes and flags anything that needs your attention. Your team edits together. Multiple people can edit the same page at once, with live cursors showing who is working where. Comments and suggestions are visible to everyone.
If the editor ever appears out of sync with your repository, use Reset editor to force a resync.

​
Editor layout

  • Top bar: Click Collapse sidebar to hide your pages, and Ask agent to open the agent beside your page. On a site page, the top bar also has Preview and Publish, plus the branch selector when it’s visible. On a private page, it has Share. Click More options for page actions like Page settings, Comments, Version history, Duplicate, and Move within project.
  • Sidebar: Use the sidebar to select pages to edit, create new pages, manage your site structure, and move around the dashboard. Press Cmd + \ (macOS) or Ctrl + \ (Windows) to hide or show your pages. Press Cmd + K (macOS) or Ctrl + K (Windows) to search the dashboard.
    • Dashboard icons: Switch projects from the menu at the top. Click Home to return to the editor from anywhere in the dashboard or Search to search your pages, settings, and automations. Below those, open Publishes, Analytics, MCP, and Settings. At the bottom, click Get help for documentation, support, and product updates, or click your avatar to open your profile menu.
    • Pages: Navigation contains the pages in your site navigation. Files lists the files in your repository that aren’t in your navigation. If you use private pages, Personal contains your private drafts and Shared with me contains pages teammates shared with you directly.

​
Search the dashboard

Press Cmd + K (macOS) or Ctrl + K (Windows), or click Search in the sidebar, to search the dashboard. In visual mode, deselect any text first, because Cmd + K adds a link to selected text. Search finds:
  • Your pages.
  • Settings pages.
  • docs.json sections, which open in the editor.
  • Analytics and Publishes sections.
  • Automations by name.
Search also runs actions, such as inviting members, creating an automation, opening or closing the agent, showing or hiding the sidebar, switching between light and dark themes, contacting support, and opening the list of keyboard shortcuts. Some actions, like inviting members, appear only if your role allows them. Before you type, search suggests results for the page you’re on. For example, on a settings page it suggests sections of that page, and in the editor it suggests site configuration sections.

​
Visual and source mode

Visual mode renders your page as you type. Press / to open the component menu and insert components. Source mode gives you direct access to the MDX, with line numbers. Use it for precise control over component properties and frontmatter. Type < to access components. Press Cmd + S (macOS) or Ctrl + S (Windows) to format the document. If a single change modifies more than 10,000 characters, the editor asks you to confirm it. Both modes edit the same file and support real-time collaboration. Switch between them with Cmd + Shift + S (macOS) or Ctrl + Shift + S (Windows), or with the Source mode switch in More options. The editor remembers your choice across pages. Source mode is unavailable while suggesting mode is on. For the components you can insert, see Components. For MDX syntax, see Format text and Format code.

​
Git concepts

Understanding some Git concepts helps you get the most from the editor. For definitions of commits, branches, pull requests, merges, conflicts, and diffs, see Git concepts for documentation.