From 6e6ab8d1807d143ddb0b560e30006210cedad731 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Thu, 22 Aug 2024 13:02:24 -0700 Subject: [PATCH 1/2] update versioning docs --- advanced/user-auth/overview.mdx | 2 +- settings/versioning.mdx | 179 ++++++++++++++------------------ 2 files changed, 80 insertions(+), 101 deletions(-) diff --git a/advanced/user-auth/overview.mdx b/advanced/user-auth/overview.mdx index 796d55026..b992dbb2a 100644 --- a/advanced/user-auth/overview.mdx +++ b/advanced/user-auth/overview.mdx @@ -85,4 +85,4 @@ Here's a table that displays whether a page is shown for different combinations | `groups: []` in metadata | ❌ | ❌ | ❌ | | `groups: ['admin']` in metadata | ❌ | ❌ | ✅ | -Note that an empty array in the page metadata is interpreted as "No groups should see this page." */} +Note that an empty array in the page metadata is interpreted as "No groups should see this page." diff --git a/settings/versioning.mdx b/settings/versioning.mdx index 1110a3ac4..499afc698 100644 --- a/settings/versioning.mdx +++ b/settings/versioning.mdx @@ -4,132 +4,111 @@ description: 'Build separate versions' icon: 'square-chevron-down' --- +These guides will assume `v1` pages are in a folder named `v1`, `v2` pages are in a folder named `v2`, and so on. While this method of structuring your files isn't strictly necessary, it's a great way to keep your files organized. + ## Setup -Add `"versions": ["v2", "v1"]` to your `mint.json` file where "v1" and "v2" are the names of your versions. You can put any number of versions in this array. The first version from the array serves as the default version. +Add `"versions": ["v2", "v1"]` to your `mint.json` file where `v1` and `v2` are the names of your versions. You can put any number of versions in this array. The first version from the array serves as the default version. The versions dropdown will show your versions in the order you include them in `mint.json`. -## Versioning Options - -You can add version values to anchors, groups, or individual pages. - -### Anchors - -You can hide an entire anchor based on a version. This is useful when you have dozens of pages you want to hide. For example, for an API reference section. - -In `mint.json`, simply add `version` to your anchor. Anchors without a version value are shown in every version. - -```json -"anchors": [ - { - "name": "API Reference V1", - "url": "v1/api-reference", - "version": "v1" - }, - { - "name": "API Reference V2", - "url": "v2/api-reference", - "version": "v2" - }, - { - "name": "Anchor Without a Version", - "url": "example-anchor" - } -] -``` - -You don't need to add `v1/` or `v2/` to the start of your URLs, but some customers do it to keep their doc files organized. - -### Tabs - -Similarly, you can version with tabs. In the `mint.json`, add `version` to the tab. Tabs without a version value are shown in every version. +## Versioning Groups and Pages -```json - "tabs": [ - { - "name": "API Reference V1", - "url": "v1/api-reference", - "version": "v1" - }, - { - "name": "API Reference V2", - "url": "v2/api-reference", - "version": "v2" - }, - { - "name": "Tabs Without a Version", - "url": "example-tab" - } - ] - ``` +The best way to specify page versions is by adding a version value to a group in the navigation. When you specify the version of a group, that version is applied to all pages within that group. +You can also specify the version of a single page in the page metadata. Versions on individual pages always take precedence. -### Groups - -You can version specific groups. This is useful when a few pages changed but everything else stayed the same. - -Simply add `version` to your groups. Groups without a version value are shown in every version. - -In the example below, pages in `Nested Group V1` only show up when `v1` docs are shown. - -```json + +```json Groups (mint.json) "navigation": [ - { - "group": "Group without a version", - "pages": [ - { - "group": "Nested Group V1", - "pages": ["page-with-version", "other-page-with-version"], - "version": "v1" - }, - { - "group": "Nested Group Always Shows", - "pages": ["nested-page", "other-nested-page"], - }, - "page" - ] - } -] + { + "group": "Getting Started", + "version": "v1", + "pages": [...] + } +], ``` -### Pages - -You can version a single page. Add `version` to the top of your page metadata like so: - -```md +```yaml Pages (quickstart.mdx) --- -title: 'My page title' -description: 'My page description' -version: 'v1' +title: 'Quickstart' +version: 'v2' --- ``` + + + + While it is possible to nest versioned groups within versioned groups, it is not recommended. If you do take this approach, the more deeply-nested version takes precedence. + + +### Versioning Tabs and Anchors + +You can hide a tab or anchor based on a version. This is useful if you have links that are only relevant in one version. Importantly, this does **not** apply the version to the pages within that anchor. + +In `mint.json`, simply add `version` to your tab or anchor. Tabs and anchors without a specified version are shown in every version. + + +```json Tabs +"tabs": [ + { + "name": "API Reference V1", + "url": "v1/api-reference", + "version": "v1" + }, + { + "name": "API Reference V2", + "url": "v2/api-reference", + "version": "v2" + }, + { + "name": "Migrating from V1 to V2", + "url": "https://mintlify.com/changelog/v2" + }, +], +``` -Your navigation config in `mint.json` should include the page like normal, but the page will only show up when the correct version is selected. +```json Anchors +"anchors": [ + { + "name": "API Reference V1", + "url": "v1/api-reference", + "version": "v1" + }, + { + "name": "API Reference V2", + "url": "v2/api-reference", + "version": "v2" + }, + { + "name": "Migrating from V1 to V2", + "url": "https://mintlify.com/changelog/v2", + "version": "v2" + }, +], +``` + -### Reusable Pages +### Sharing Between Versions -Not _all_ content has to be hidden though! Any content without a version value shows up in every version so you never duplicate content! +Not _all_ content has to be hidden though! Any content without a specified version appears in every version so you never duplicate content! ## Troubleshooting Common errors and how to fix them - -You likely nested a version inside of another. For example, your group had version "v1" but your page had version "v2". - -We do not recommend nesting versions inside of each other because it's hard to maintain your docs later. - - + + You likely nested a version inside of another. For example, your group had version "v1" but your page had version "v2". - + We do not recommend nesting versions inside of each other because it's hard to maintain your docs later. + - If you add versions to your docs and the pages disappeared from your - navigation, make sure you spelled the version the same as in your `versions` - array in `mint.json`. - + + If you add versions to your docs and the pages disappeared from your + navigation, make sure you spelled the version the same as in your `versions` + array in `mint.json`. + From ee9d08fa72e89d57b0f21f3114d6cc56bad3ae7c Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Fri, 23 Aug 2024 06:47:46 -0700 Subject: [PATCH 2/2] Update versioning.mdx Co-authored-by: Hahnbee Lee <55263191+hahnbeelee@users.noreply.github.com> --- settings/versioning.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings/versioning.mdx b/settings/versioning.mdx index 499afc698..dbafd459c 100644 --- a/settings/versioning.mdx +++ b/settings/versioning.mdx @@ -93,7 +93,7 @@ In `mint.json`, simply add `version` to your tab or anchor. Tabs and anchors wit ### Sharing Between Versions -Not _all_ content has to be hidden though! Any content without a specified version appears in every version so you never duplicate content! +Not _all_ content has to be hidden though! Any content without a specified version appears in every version so you don't have to duplicate content! ## Troubleshooting