Create and edit pages

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

Sidebar sections

The editor sidebar groups your pages into sections.

• 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: The last three private pages you opened.
• Starred: Private pages you starred. To star a page, open its options menu and select Star. Stars are personal to you.
• Personal: Your private pages.
• Shared with me: Pages that teammates shared with you directly.

Personal, Shared with me, Recents, and Starred only appear after you create a private page or a teammate shares one with you. Recents, Starred, and Shared with me stay hidden while they’re empty.

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

The top bar changes with the page you have open. On a site page, it has the branch selector, Preview, and Publish. On a private page, it has Share.

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 sidebar 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.
• Thumbnails: Thumbnail overrides for the page’s social preview image. Each setting uses the inherited value unless you change it.

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. Groups, tabs, anchors, dropdowns, products, versions, languages, and menu items also have a Thumbnails section that sets thumbnail overrides for the pages in that section. See Pages for more information on specific settings.

Edit API reference pages

Pages with an openapi, openapi-schema, or api field in their frontmatter show the endpoint and its fields in the editor, the same way they appear on your published site. The editor labels these sections Generated from OpenAPI. You can’t edit them in the editor. To change them, update your OpenAPI specification or the page’s frontmatter. See OpenAPI setup.

Write your own content on the page between the endpoint and the fields.

If the page has no description in its frontmatter, the editor shows the operation’s description from your OpenAPI specification. Click the description to edit it. If you change it, the editor saves your text as the page’s description, which replaces the specification’s description on that page.

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. You can’t upload SVG files in the editor.
• Each upload can be up to 20 MB.
• Click an image to select it. Drag the image to move it, including into or out of components like frames, cards, tabs, and callouts. Drag the handles on its edges to resize it. Press Delete or Backspace to remove it.
• 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.

Organize navigation

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, or Cmd-click (macOS) or Ctrl-click (Windows) to add or remove individual items. 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, open a site page, click Site configuration at the bottom of the sidebar, then go to 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

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.
• The editor can’t preview other files, like fonts and archives.

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 within project, 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.

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

Copy a page to another project

To copy a page to another project in your organization, open its options menu and select Copy to a project, then pick the project. You must have an editor or admin role and access to both projects.

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 private page is permanent. For private 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 version about 10 seconds after you stop editing a page. If you edit continuously, the editor records a version at least once a minute. Changes that sync from your Git repository also create versions, which list Git sync as an author. Version history is branch-scoped. Only the current branch’s version history is available.

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

To leave the comparison, click Exit comparison.

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

Restoring a version replaces the page’s current content. Restoring a site page only affects your current branch. Restoring a private page affects all branches.

Private pages

Private pages are drafts that live in the Personal section of the sidebar. They stay private to you, and Mintlify doesn’t commit them to your repository. They save automatically and have no publish step. They never appear on your published site unless you move them to your site.

If you already use private pages, create a page or folder by clicking the plus button on the Personal section header, then selecting New page or New folder. On sites, Personal only appears for people who have private pages or have had one shared with them.

To import Markdown files as private pages, drag Markdown and MDX files from your computer onto Personal or a private folder.

To set an icon or emoji on a private 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

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 select a role for each:

• Full Access: Edit and share. The page’s owner can also move it to your site.
• Editor: Create and edit content.
• Viewer: View content only.

Under general access, select Only people invited or Everyone at your organization. Only people with Full Access can change who has access.

If you have Viewer access to a page, click View only in the top bar, then Request edit access. People with Full Access can approve the request.

Pages shared with you appear in Shared with me. When a teammate shares a page or folder with you directly, it also appears in your inbox. To remove a page from your sidebar, open its options menu and select Leave.

Move a page to your site

To add a private page to your site, open its options menu in the sidebar and select Move to site, or drag it into Navigation. The page moves into your navigation on your current branch as an unpublished change, and the sidebar highlights it. Publish to make it live. You need the editor or admin role. Moving a folder adds it to your navigation as a group, with all its pages and its icon. The Move to site option moves up to 20 pages at a time.

Moving a page to your site is one-way. The private page is removed right away, and discarding the change on your branch doesn’t restore it. You can’t move a site page back to Personal.