# Create and edit pages (/editor/pages)

<!-- agent-signals: reading_time_min: 11 · est_tokens: 4227 · updated: 2026-09-23 -->
Related: [How to use the editor](/editor/tutorial.md), [Publish changes](/editor/publish.md), [Review changes](/editor/review.md), [Collaborate in the editor](/editor/collaborate.md), [Ask agent](/editor/agent.md), [Editor settings for AI and publishing](/editor/settings.md)

## Workspace and Site [#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](#private-pages).
* **Teamspace**: Pages shared with everyone in your organization. See [Teamspace](#teamspace).
* **Shared with me**: Pages that teammates [shared with you](#share-a-private-page) 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 [#create-a-page]

To create a page, click the <Icon icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M12.001 5.00003V19.002&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/><path d=&#x22;M19.002 12.002L4.99998 12.002&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" /> 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.

<Tip>
  To add a page that already exists in your repository to your navigation, click the <Icon icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M12.001 5.00003V19.002&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/><path d=&#x22;M19.002 12.002L4.99998 12.002&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" /> plus button and select **Add existing page**.
</Tip>

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

## Edit page settings [#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 <Icon icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M12 12.002H12.5M19 12.002H19.5M5 12.002H5.5M12 13.002C12.5523 13.002 13 12.5542 13 12.002C13 11.4497 12.5523 11.002 12 11.002C11.4477 11.002 11 11.4497 11 12.002C11 12.5542 11.4477 13.002 12 13.002ZM19 13.002C19.5523 13.002 20 12.5542 20 12.002C20 11.4497 19.5523 11.002 19 11.002C18.4477 11.002 18 11.4497 18 12.002C18 12.5542 18.4477 13.002 19 13.002ZM5 13.002C5.55228 13.002 6 12.5542 6 12.002C6 11.4497 5.55228 11.002 5 11.002C4.44772 11.002 4 11.4497 4 12.002C4 12.5542 4.44772 13.002 5 13.002Z&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" /> **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](/organize/pages) for more information on specific settings.

## Add media [#add-media]

Type <kbd>/image</kbd> or <kbd>/video</kbd> 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 <kbd>/embed</kbd> 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](/create/image-embeds).

## Organize navigation [#organize-navigation]

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

<Note>
  Some elements can't nest inside others. Tabs can't nest inside groups, for example. The editor prevents invalid combinations.
</Note>

To select several items, <kbd>Shift</kbd>-click to select a range. Drag the selection or right-click it to move, duplicate, or delete every selected item at once. Press <kbd>Esc</kbd> 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**.

### Add and remove pages from your navigation [#add-and-remove-pages-from-your-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 [#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 [#move-a-page]

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

You can open a page's options menu from:

* <Icon icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M12 12.002H12.5M19 12.002H19.5M5 12.002H5.5M12 13.002C12.5523 13.002 13 12.5542 13 12.002C13 11.4497 12.5523 11.002 12 11.002C11.4477 11.002 11 11.4497 11 12.002C11 12.5542 11.4477 13.002 12 13.002ZM19 13.002C19.5523 13.002 20 12.5542 20 12.002C20 11.4497 19.5523 11.002 19 11.002C18.4477 11.002 18 11.4497 18 12.002C18 12.5542 18.4477 13.002 19 13.002ZM5 13.002C5.55228 13.002 6 12.5542 6 12.002C6 11.4497 5.55228 11.002 5 11.002C4.44772 11.002 4 11.4497 4 12.002C4 12.5542 4.44772 13.002 5 13.002Z&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" /> **More options** in the top-right of an open page.
* The <Icon icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M12 12.002H12.5M19 12.002H19.5M5 12.002H5.5M12 13.002C12.5523 13.002 13 12.5542 13 12.002C13 11.4497 12.5523 11.002 12 11.002C11.4477 11.002 11 11.4497 11 12.002C11 12.5542 11.4477 13.002 12 13.002ZM19 13.002C19.5523 13.002 20 12.5542 20 12.002C20 11.4497 19.5523 11.002 19 11.002C18.4477 11.002 18 11.4497 18 12.002C18 12.5542 18.4477 13.002 19 13.002ZM5 13.002C5.55228 13.002 6 12.5542 6 12.002C6 11.4497 5.55228 11.002 5 11.002C4.44772 11.002 4 11.4497 4 12.002C4 12.5542 4.44772 13.002 5 13.002Z&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" /> 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 [#delete-a-page]

To delete a page, click <Icon icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M12 12.002H12.5M19 12.002H19.5M5 12.002H5.5M12 13.002C12.5523 13.002 13 12.5542 13 12.002C13 11.4497 12.5523 11.002 12 11.002C11.4477 11.002 11 11.4497 11 12.002C11 12.5542 11.4477 13.002 12 13.002ZM19 13.002C19.5523 13.002 20 12.5542 20 12.002C20 11.4497 19.5523 11.002 19 11.002C18.4477 11.002 18 11.4497 18 12.002C18 12.5542 18.4477 13.002 19 13.002ZM5 13.002C5.55228 13.002 6 12.5542 6 12.002C6 11.4497 5.55228 11.002 5 11.002C4.44772 11.002 4 11.4497 4 12.002C4 12.5542 4.44772 13.002 5 13.002Z&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" /> **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]

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.

1. Click <Icon icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M12 12.002H12.5M19 12.002H19.5M5 12.002H5.5M12 13.002C12.5523 13.002 13 12.5542 13 12.002C13 11.4497 12.5523 11.002 12 11.002C11.4477 11.002 11 11.4497 11 12.002C11 12.5542 11.4477 13.002 12 13.002ZM19 13.002C19.5523 13.002 20 12.5542 20 12.002C20 11.4497 19.5523 11.002 19 11.002C18.4477 11.002 18 11.4497 18 12.002C18 12.5542 18.4477 13.002 19 13.002ZM5 13.002C5.55228 13.002 6 12.5542 6 12.002C6 11.4497 5.55228 11.002 5 11.002C4.44772 11.002 4 11.4497 4 12.002C4 12.5542 4.44772 13.002 5 13.002Z&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" /> **More options** in the top-right of the page, then click **Version history**.
2. Select a version. The editor shows how the current page differs from that version.
3. To restore it, click **Restore this version**, then confirm.

To leave the comparison, click **Exit comparison** or press <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>D</kbd> (macOS) or <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>D</kbd> (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]

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 <Icon icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M12.001 5.00003V19.002&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/><path d=&#x22;M19.002 12.002L4.99998 12.002&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" /> 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.

### Share a private page [#share-a-private-page]

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]

Teamspace pages are available to everyone in your organization. Like private pages, they aren't committed to your repository. Access follows your [role](/dashboard/roles). 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 <Icon icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M12.001 5.00003V19.002&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/><path d=&#x22;M19.002 12.002L4.99998 12.002&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" /> 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 [#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.

<Warning>
  Moving pages between sections is one-way. You can't move a page from **Teamspace** back to **Personal**, or from **Site** back to **Workspace**.
</Warning>