Create and edit pages

Create pages, edit content, add media, organize your navigation, restore earlier page versions, and manage private and teamspace pages in the editor.

Workspace and Site

The editor sidebar has two tabs: Workspace and Site.

Workspace contains pages that aren’t part of your Git repository or published site. Workspace pages save automatically and have no publish step.

Recents: Workspace pages you opened recently.
Starred: Workspace pages you starred. To star a page, open its options menu and select Star. Stars are personal to you.
Personal: Your private pages.
Teamspace: Pages shared with everyone in your organization. See Teamspace.
Shared with me: Pages that teammates shared with you directly.

Site contains your repository and the pages your visitors see on your published site.

Navigation: The pages and groups in your site navigation, as defined in docs.json.
Files: Every file in your repository that isn’t in your navigation, including images, videos, OpenAPI specs, and docs.json.

Recents, starred, and shared with me only appear when they have something in them.

Drag a section header to reorder the sections in a tab. Click a section header to collapse or expand it. The editor saves your section order and collapsed state to your account.

Switching tabs reopens the last page you viewed on that tab. The top bar changes with the tab. Share appears only on Workspace. The branch selector, Preview, and Publish appear only on Site.

Create a page

To create a page, click the plus button where you want it, then select New page.

Navigation section header: Adds a new page to the end of your navigation.
A group or other navigation element: Adds a new page inside that element.
Files section header or a folder in Files: Creates a file that isn’t in your navigation.

The New page button at the bottom of the Site tab also adds a page to the end of your navigation.

To add a page that already exists in your repository to your navigation, click the plus button and select Add existing page.

The same menus create navigation elements like groups, tabs, anchors, dropdowns, versions, languages, and products. For more information on each element, see Navigation.

Edit page settings

Set a page’s title, description, and icon directly at the top of the page. Hover above the title and click Add icon to pick an icon or emoji. When a page with an icon is open, your browser tab shows that icon.

For other settings, open the page’s options menu in the sidebar, or click More options in the top-right of the page, and select Page settings. The Page settings panel groups settings into sections:

URL: The page’s path and redirect URL. Changing the path moves the file.
Navigation: Sidebar title, tag, mode, and whether the page is hidden.
SEO & sharing: Open Graph image and keywords.

Groups, tabs, and other navigation elements have their own settings panels, like Group settings and Tab settings. Open them from the element’s options menu. See Pages for more information on specific settings.

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, or drag an image or video from the Files section onto the page.

Uploads save to your images/, videos/, and files/ folders and commit with your next publish. Before you insert an upload, you can edit its file path.
You can upload PNG, JPG, GIF, WebP, AVIF, ICO, and BMP images, MP4, WebM, and MOV videos, and PDF files. SVG files can’t be uploaded in the editor.
Each upload can be up to 20 MB.
To serve a different image in dark mode, select the image, click Edit Image, and set Dark mode image.
Type /embed to add an embed. On the Video link tab, paste a YouTube, Loom, or Vimeo URL, or a direct link to a video file. On the Embed code tab, paste an iframe or other embed snippet.

For formatting images and using the Frame component, see Images and embeds.

Drag elements in Navigation to reorder or nest them. The editor writes your changes to docs.json when you publish.

Some elements can’t nest inside others. Tabs can’t nest inside groups, for example. The editor prevents invalid combinations.

To select several items, Shift-click to select a range. Drag the selection or right-click it to move, duplicate, or delete every selected item at once. Press Esc to clear the selection.

To change a group or other element into a different type, open its options menu and select Convert to.

Global navigation elements, like anchors and tabs that appear across every section of your site, aren’t in the sidebar tree. To manage them, click Site settings at the bottom of the Site tab, then go to Navigation.

Drag a page from Files into Navigation to add it at that position. Drag a folder to add it as a group. You can also select Move to navigation from a file’s options menu.

To remove a page or group from your navigation without deleting its files, drag it from Navigation into Files, or select Move to files from its options menu. An undo toast appears after the move.

Files

Click a file in Files to open it.

Images open in a preview. Click the image to zoom.
Videos play in the editor.
docs.json opens in source mode.
Text and code files, like YAML, JSON, and CSS, open in the source editor.
Other files, like fonts and archives, can’t be previewed in the editor.

To upload files, drag them from your computer onto the Files section.

Move a page

To move a page to a different folder, open its options menu and select Move to, or press Cmd + Shift + P (macOS) or Ctrl + Shift + P (Windows) with the page open.

You can open a page’s options menu from:

More options in the top-right of an open page.
The menu next to a page in the sidebar.
Right-clicking a page in the sidebar.

In the picker, search to filter folders, expand folders to see nested destinations, and select a folder to move the page. The current folder is marked Current and can’t be selected. A toast with Revert appears after the move.

Moving a site page moves its file to the new folder. Editors and admins can move site pages. You can move workspace pages that you manage in Personal and Teamspace, but not pages in Shared with me.

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 sidebar.

Deleting a site page removes both the file and its navigation entry. A toast with Undo appears after you delete. To remove a page from your navigation without deleting its file, select Move to files instead.

Deleting a workspace page is permanent. For workspace pages, the More options menu shows Delete page.

Editors and admins can delete site pages.

Version history

Version history lets you compare a page with earlier saved versions and restore one. It isn’t available for docs.json.

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.

Click More options in the top-right of the page, then click Version history.
Select a version. The editor shows how the current page differs from that version.
To restore it, click Restore this version, then confirm.

To leave the comparison, click Exit comparison or press Cmd + Shift + D (macOS) or Ctrl + Shift + D (Windows).

Anyone can compare versions. Editors and admins can restore versions of site pages. For workspace pages, you need the Editor or Publisher role on the page to restore a version.

Restoring a version replaces the page’s current content. When you restore a site page, it is only restored on your current branch. When you restore a workspace page, it is restored on all branches.

Private pages

Private pages are drafts that live in the Personal section of the Workspace tab. They are private to you, are not committed to your repository, and never appear on your published site unless you move them to your site.

To create a private page or folder, click the plus button on the Personal section header, then select New page or New folder. The New page button at the bottom of the Workspace tab also creates a private page.

To set an icon or emoji on a workspace folder, open its options menu and select Change icon. Pick an icon from the Icons tab or an emoji from the Emojis tab, or select Remove to clear it.

To share a private page, open it and click Share in the top bar. To share a folder, open its options menu in the sidebar and select Share. Search for teammates and choose a role for each:

Publisher: Edit, review, and publish.
Editor: Create and edit content.
Viewer: View content only.

Under general access, choose Only people invited or Everyone at your organization. Only Publishers can change who has access.

Pages shared with you appear in Shared with me. To remove a page from your sidebar, open its options menu and select Leave.

Teamspace

Teamspace pages are available to everyone in your organization. Like private pages, they aren’t committed to your repository. Access follows your role. Editors and admins can edit and manage teamspace pages, and viewers can read them. Because everyone already has access, you can’t share individual teamspace pages.

To create a teamspace page or folder, click the plus button on the Teamspace section header, then select New page or New folder.

To move a private page into teamspace, drag it from Personal into Teamspace, or open its options menu, select Move to, and choose Teamspace. You can move pages, but not folders.

Move a page to your site

To publish a personal or teamspace page, open its options menu in the sidebar and select Move to site. The page moves into your navigation, and the sidebar switches to Site and highlights it. Moving a folder adds it to your navigation as a group, with all its pages and its icon.

Moving pages between sections is one-way. You can’t move a page from Teamspace back to Personal, or from Site back to Workspace.