diff --git a/fern/products/docs/pages/navigation/products.mdx b/fern/products/docs/pages/navigation/products.mdx index 4406fc3b3..880170cb7 100644 --- a/fern/products/docs/pages/navigation/products.mdx +++ b/fern/products/docs/pages/navigation/products.mdx @@ -1,5 +1,5 @@ --- -title: Product Switching +title: Product switching subtitle: Allow users to seamlessly navigate between different products you offer. --- @@ -24,7 +24,7 @@ subtitle: Allow users to seamlessly navigate between different products you offe Each product can contain its own distinct versions, tabs, sections, pages, and API references. Products can share content as well. -## Add Products to Your Docs +## Add products to your docs @@ -104,16 +104,24 @@ products: subtitle: Product A subtitle # optional - display-name: Product B - path: ./products/product-b/latest.yml # <-- default showing latest + path: ./products/product-b/versions/latest/latest.yml # <-- default showing latest image: ./images/product-b.png # optional slug: product-b # optional subtitle: Product B subtitle # optional ``` - + + +If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure to remove. Those fields should now belong in the product-specific `.yml` files. + + + +### Add versioning to your products (optional) + +You can optionally add versions to your products. Versioned and unversioned products can live next to each other in your site. -You can optionally add versions to a product. Versioned and unversioned products can live next to each other in your site. Each version of a single product has its own `yml` file. +For standalone versioning without products, see our [Versioning guide](/docs/configuration/versions). In the below example, Product A is **unversioned** and Product B is **versioned**: @@ -140,41 +148,69 @@ In the below example, Product A is **unversioned** and Product B is **versioned* ``` + + +Create a `versions` folder inside of folder of the product you want to version. + +Each version of a single product has its own `yml` file. To specify the contents of each version, add a `.yml` file to the `versions` folder to define the navigational structure of that version. Make sure to include the `navigation` and `tabs` properties, if applicable. + +Version-specific `yml` files: + + + + + + +Define a version in the top-level `docs.yml` by adding an item to the `versions` list and specifying the `display-name` and `path`. + The top-level `doc.yml` configuration for a Fern Docs website containing two products, one unversioned and one versioned, might look something like this: -```yaml {2, 8, 13-19} +```yaml {2, 8, 12-16} products: - display-name: Product A # unversioned - path: ./products/product-a.yml + path: ./products/product-a.yml icon: fa-solid fa-leaf # optional slug: product-a # optional subtitle: Product A subtitle # optional - - display-name: Product B # versioned - path: ./products/product-b/latest.yml # <-- default showing latest + path: ./products/product-b/versions/latest/latest.yml # <-- default showing latest image: ./images/product-b.png # optional slug: product-b # optional subtitle: Product B subtitle # optional - versions: # optional + versions: - display-name: Latest - path: ./products/product-b/latest.yml - availability: beta + path: ./products/product-b/versions/latest/latest.yml # relative path to the version file - display-name: V2 - path: ./products/product-b/v2.yml - availability: ga + path: ./products/product-b/versions/v2/v2.yml # relative path to the version file ``` -For more information on setting up versioned products, follow our [versioning docs](/docs/configuration/versions). - + -If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure to remove. Those fields should now belong in the product-specific `.yml` files. + + + +```yaml {4} +versions: + - display-name: Latest + path: ./products/product-b/versions/latest/latest.yml + availability: beta + - display-name: V2 + path: ./products/product-b/versions/v2/v2.yml + availability: stable +``` + + + + +If your product-specific `.yml` files for **versioned products** includes a `navigation` field or a `tabs` field, be sure to remove. Those fields should now belong in the version-specific `.yml` files. -## Customizing Selector Styling + +## Customize selector styling You can directly customize the appearance of the product and version selectors by targeting their CSS classes: @@ -185,13 +221,9 @@ You can directly customize the appearance of the product and version selectors b Example of a styled product selector -### Common Styling Adjustments - -**Adjusting positioning:** -Use `transform: translateY(Npx)` to adjust the vertical positioning of the selectors. This ensures that the product and version selectors match the line height of your logo for better visual alignment. +### Common styling adjustments -**Enhancing visual prominence:** -You can modify the border radius and add borders to make the selectors more prominent and better integrated with your site's design aesthetic. + ```css .fern-product-selector { @@ -207,7 +239,7 @@ You can modify the border radius and add borders to make the selectors more prom } ``` -## Customizing Dropdown Styling +### Customize dropdown styling The dropdown menus for product and version selectors can be customized using these specific CSS classes: diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index c7fc0bb46..2b4c2312f 100644 --- a/fern/products/docs/pages/navigation/versions.mdx +++ b/fern/products/docs/pages/navigation/versions.mdx @@ -9,7 +9,7 @@ subtitle: Allow users to navigate between different versions of your docs. Each version of your docs can contain its own distinct tabs, sections, pages, and API references. Versions can share content, as well. -**To add versions to your docs:** +## Add versions to your docs @@ -25,107 +25,76 @@ fern/ ├─ pages/ ├─ ... └─ versions/ - ├─ v2-1/pages/... - ├─ v2-1.yml - ├─ v2-2/pages/... - └─ v2-2.yml + ├─ latest/pages/... + ├─ latest.yml + ├─ v2/pages/... + └─ v2.yml ``` - Version-specific `yml` files: - - -```yaml -navigation: - - section: Introduction - contents: - - page: My Page - path: ./v2-1/pages/my-page.mdx # relative path to the file - - page: Shared Resource - path: ../shared-pages/shared-resource.mdx - - api: API Reference -``` - - -```yaml -tabs: - api: - title: API Reference - icon: puzzle - help: - title: Help Center - icon: home - - navigation: - - tab: api - contents: - - section: Introduction - contents: - - page: My Page - path: ./v2-2/pages/my-page.mdx # relative path to the file - - page: Shared Resource - path: ../shared-pages/shared-resource.mdx - - api: API Reference - - tab: help - contents: - - section: Help Center - contents: - - page: Contact Us - path: contact-us.mdx -``` - - + You can also have multiple products, some versioned and some unversioned. For more information on setting up multiple products, follow our [product switching docs](/docs/configuration/products). -To define a version, in `docs.yml`, add an item to the `versions` list, specifying the `display-name` and `path`. - -```bash -fern/ - ├─ fern.config.json - ├─ generators.yml - ├─ docs.yml - └─ versions/ - ├─ ... - ├─ v2-1.yml - └─ v2-2.yml -``` +Define a version in the top-level `docs.yml` by adding an item to the `versions` list and specifying the `display-name` and `path`. ```yaml versions: - - display-name: v2.2 # shown in the dropdown - path: ./versions/v2-2.yml # relative path to the version file - - display-name: v2.1 - path: ./versions/v2-1.yml + - display-name: Latest # shown in the dropdown + path: ./versions/latest.yml # relative path to the version file + - display-name: V2 + path: ./versions/v2.yml ``` -You can optionally set the availability status for each version. Options are `deprecated`, `ga`, `stable`, and `beta`. + ```yaml {4} versions: - - display-name: v2.2 - path: ./versions/v2-2.yml + - display-name: Latest + path: ./versions/latest.yml availability: beta - - display-name: v2.1 - path: ./versions/v2-1.yml + - display-name: v2 + path: ./versions/v2.yml availability: stable ``` -Version availability is distinct from [section and page availability](/learn/docs/configuration/navigation#section-and-page-availability), with different options. If you want to set section and page availability, do so in your version-specific `yml` files. - If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure to remove. Those fields should now belong in the version-specific `.yml` files. - \ No newline at end of file + + +## Customize version selector styling + +You can directly customize the appearance of the version selector by targeting the `fern-version-selector` CSS class. + +### Common styling adjustments + + + +```css +.fern-version-selector { + transform: translateY(1px); + border-radius: 1000px; + border: 1px solid var(--border); +} +``` + +### Customize the dropdown + +The dropdown menu for the version selector can be customized using the `fern-version-selector-radio-group` CSS class. + + + Example of a styled version selector + \ No newline at end of file diff --git a/fern/snippets/common-selector-styling.mdx b/fern/snippets/common-selector-styling.mdx new file mode 100644 index 000000000..8e3c17305 --- /dev/null +++ b/fern/snippets/common-selector-styling.mdx @@ -0,0 +1,5 @@ +**Adjusting positioning:** +Use `transform: translateY(Npx)` to adjust the vertical positioning of the selectors. This ensures that the selectors match the line height of your logo for better visual alignment. + +**Enhancing visual prominence:** +You can modify the border radius and add borders to make the selectors more prominent and better integrated with your site's design aesthetic. \ No newline at end of file diff --git a/fern/snippets/version-availability.mdx b/fern/snippets/version-availability.mdx new file mode 100644 index 000000000..cc6cab394 --- /dev/null +++ b/fern/snippets/version-availability.mdx @@ -0,0 +1,3 @@ +You can optionally set the availability status for each version. Options are `deprecated`, `ga`, `stable`, and `beta`. + +Version availability is distinct from [section and page availability](/learn/docs/configuration/navigation#section-and-page-availability), with different options. If you want to set section and page availability, do so in your version-specific `yml` files. \ No newline at end of file diff --git a/fern/snippets/version-specific-yml-files.mdx b/fern/snippets/version-specific-yml-files.mdx new file mode 100644 index 000000000..5e37c7081 --- /dev/null +++ b/fern/snippets/version-specific-yml-files.mdx @@ -0,0 +1,42 @@ + + +```yaml +navigation: + - section: Introduction + contents: + - page: My Page + path: ./latest/pages/my-page.mdx # relative path to the file + - page: Shared Resource + path: ../shared-pages/shared-resource.mdx + - api: API Reference +``` + + +```yaml +tabs: + api: + title: API Reference + icon: puzzle + help: + title: Help Center + icon: home + + navigation: + - tab: api + contents: + - section: Introduction + contents: + - page: My Page + path: ./v2/pages/my-page.mdx # relative path to the file + - page: Shared Resource + path: ../shared-pages/shared-resource.mdx + - api: API Reference + - tab: help + contents: + - section: Help Center + contents: + - page: Contact Us + path: contact-us.mdx +``` + + \ No newline at end of file