From 2ce8afac74df9b2558d9c298240eb0da55208fdc Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 10 Nov 2025 18:39:26 -0500 Subject: [PATCH 1/3] split pages, add intros, add redirects --- .vale/styles/FernStyles/Acronyms.yml | 1 + .vale/styles/FernStyles/Headings.yml | 2 + fern/docs.yml | 6 +- fern/products/docs/docs.yml | 9 ++- .../default-components/download.mdx | 2 +- .../writing-content/markdown-basics.mdx | 68 +++++++++++++++++ .../{markdown.mdx => markdown-media.mdx} | 76 ++----------------- 7 files changed, 90 insertions(+), 74 deletions(-) create mode 100644 fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx rename fern/products/docs/pages/component-library/writing-content/{markdown.mdx => markdown-media.mdx} (69%) diff --git a/.vale/styles/FernStyles/Acronyms.yml b/.vale/styles/FernStyles/Acronyms.yml index 04d45be74..9736ae5ae 100644 --- a/.vale/styles/FernStyles/Acronyms.yml +++ b/.vale/styles/FernStyles/Acronyms.yml @@ -101,3 +101,4 @@ exceptions: - SSR - SSG - REST + - MDN diff --git a/.vale/styles/FernStyles/Headings.yml b/.vale/styles/FernStyles/Headings.yml index 659a57756..4f19e76e1 100644 --- a/.vale/styles/FernStyles/Headings.yml +++ b/.vale/styles/FernStyles/Headings.yml @@ -80,3 +80,5 @@ exceptions: - fern.config.json - Font Awesome - MCP + - LaTeX + - MDN diff --git a/fern/docs.yml b/fern/docs.yml index 6c5fc6be7..09c8316d5 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -343,7 +343,9 @@ redirects: destination: /learn/docs/customization/search - source: /learn/docs/content/write-markdown - destination: /learn/docs/writing-content/markdown + destination: /learn/docs/writing-content/markdown-basics + - source: /learn/docs/writing-content/markdown + destination: /learn/docs/writing-content/markdown-basics - source: /learn/docs/content/components/:slug* destination: /learn/docs/writing-content/components/:slug* - source: /learn/docs/content/custom-react-components @@ -566,7 +568,7 @@ redirects: - source: /learn/docs/content/visual-editor destination: /learn/docs/writing-content/fern-editor - source: /learn/docs/content - destination: /learn/docs/writing-content/markdown + destination: /learn/docs/writing-content/markdown-basics - source: /learn/docs/config/overview destination: /learn/docs/configuration/site-level-settings - source: /learn/docs/llms.txt8 diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index a37a11b29..e52d1361a 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -30,9 +30,12 @@ navigation: path: ./pages/customization/frontmatter.mdx - section: Writing content contents: - - page: Markdown pages - path: ./pages/component-library/writing-content/markdown.mdx - slug: markdown + - page: Markdown basics + path: ./pages/component-library/writing-content/markdown-basics.mdx + slug: markdown-basics + - page: Rich media in Markdown + path: ./pages/component-library/writing-content/markdown-media.mdx + slug: markdown-media - section: Components contents: - page: Overview diff --git a/fern/products/docs/pages/component-library/default-components/download.mdx b/fern/products/docs/pages/component-library/default-components/download.mdx index bbd76590b..ca523c482 100644 --- a/fern/products/docs/pages/component-library/default-components/download.mdx +++ b/fern/products/docs/pages/component-library/default-components/download.mdx @@ -6,7 +6,7 @@ description: "Download assets like PDFs directly from your documentation" The `` component lets users download assets like PDFs directly from your documentation. -For information on how to embed assets, check out the documentation on [Images](/learn/docs/writing-content/markdown#images), [PDFs](/learn/docs/writing-content/markdown#pdfs), and [Videos](/learn/docs/writing-content/markdown#videos). +For information on how to embed images, PDFs, and other assets, check out the documentation on [Rich media in Markdown](/learn/docs/writing-content/markdown-media). ## Usage diff --git a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx new file mode 100644 index 000000000..f5a5b92df --- /dev/null +++ b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx @@ -0,0 +1,68 @@ +--- +title: Markdown basics +description: Use Markdown and MDX to add content to your Fern documentation site, including headers, components, and links. +--- + +Learn how to use Markdown and MDX to add content to your documentation, including headers, components, and links. + + +Throughout this documentation, "Markdown" refers to both Markdown and MDX. [MDX](https://mdxjs.com/) is a version of Markdown, extended to allow the use of JSX components. + + +## Add Markdown or MDX pages + +Add pages manually to your documentation by creating Markdown (`.md`) or MDX (`.mdx`) files. New to Markdown? See [Markdown Guide: Getting started](https://www.markdownguide.org/getting-started/). + +Place your pages inside your `fern/` folder and link to them from your [navigation settings](/learn/docs/building-your-docs/navigation) in the `docs.yml` file. + +In the example below, the MDX files are inside a folder named `pages/`. + + +```bash +fern/ +├─ fern.config.json +├─ docs.yml +└─ pages/ + ├─ welcome.mdx + └─ quickstart.mdx +``` + + + +```yml +navigation: + - section: Overview + contents: + - page: Welcome + path: ./pages/welcome.mdx + - page: Quickstart + path: ./pages/quickstart.mdx +``` + + +## Page header + +Fern automatically generates the `

` page header for each page from `docs.yml`. For example, here's the `docs.yml` entry that maps the page you are reading now: +```yml + - page: Write Markdown content + path: ./docs/pages/fern-docs/content/write-markdown.mdx +``` +The value for `page` is used as the content of the top `

` element of this page. Thus, when adding content to your Markdown pages, begin with `

` instead of `

`. + +## Fern components + +Fern has a built-in component library you can use in Markdown. [Explore the components.](/learn/docs/content/components/overview) + +## Links in Markdown + +### Link target +When clicked, links to relative URLs open in the same tab, whereas links to absolute URLs open in a new browser tab. + +### Link format +Use a `/` character to begin a relative URL to another page on your docs site. This routes to the `url` defined in your `docs.yml` file, such as `example-docs.buildwithfern.com`. For example, if you want to link to `https://example-docs.buildwithfern.com/overview/introduction`, you can write the link in Markdown as follows: + + +```mdx +Read the [Introduction](/learn/overview/introduction). +``` + diff --git a/fern/products/docs/pages/component-library/writing-content/markdown.mdx b/fern/products/docs/pages/component-library/writing-content/markdown-media.mdx similarity index 69% rename from fern/products/docs/pages/component-library/writing-content/markdown.mdx rename to fern/products/docs/pages/component-library/writing-content/markdown-media.mdx index e0e8cd264..d0ea98f08 100644 --- a/fern/products/docs/pages/component-library/writing-content/markdown.mdx +++ b/fern/products/docs/pages/component-library/writing-content/markdown-media.mdx @@ -1,69 +1,9 @@ --- -title: Write docs content using Markdown -description: Use Markdown and MDX to add content to your Fern documentation site, including Fern's built-in component library. +title: Rich media in Markdown +description: Embed images, videos, PDFs, LaTeX equations, and diagrams in your Fern documentation. --- -## Add Markdown or MDX pages - -Add pages manually to your documentation by creating Markdown (`.md`) or MDX (`.mdx`) files.New to Markdown? See [Markdown Guide: Getting started](https://www.markdownguide.org/getting-started/). - - -NOTE: Throughout our documentation, we refer to both Markdown and MDX as Markdown. [MDX](https://mdxjs.com/) is a version of Markdown, extended to allow the use of JSX components. - - -Place your pages inside your `fern/` folder and link to them from your [navigation settings](/learn/docs/building-your-docs/navigation) in the `docs.yml` file. - -In the example below, the MDX files are inside a folder named `pages/`. - - -```bash -fern/ -├─ fern.config.json -├─ docs.yml -└─ pages/ - ├─ welcome.mdx - └─ quickstart.mdx -``` - - - -```yml -navigation: - - section: Overview - contents: - - page: Welcome - path: ./pages/welcome.mdx - - page: Quickstart - path: ./pages/quickstart.mdx -``` - - -## Page header - -Fern automatically generates the `

` page header for each page from `docs.yml`. For example, here's the `docs.yml` entry that maps the page you are reading now: -```yml - - page: Write Markdown content - path: ./docs/pages/fern-docs/content/write-markdown.mdx -``` -The value for `page` is used as the content of the top `

` element of this page. Thus, when adding content to your Markdown pages, begin with `

` instead of `

`. - -## Fern components - -Fern has a built-in component library you can use in Markdown. [Explore the components.](/learn/docs/content/components/overview) - -## Links in Markdown - -### Link target -When clicked, links to relative URLs open in the same tab, whereas links to absolute URLs open in a new browser tab. - -### Link format -Use a `/` character to begin a relative URL to another page on your docs site. This routes to the `url` defined in your `docs.yml` file, such as `example-docs.buildwithfern.com`. For example, if you want to link to `https://example-docs.buildwithfern.com/overview/introduction`, you can write the link in Markdown as follows: - - -```mdx -Read the [Introduction](/learn/overview/introduction). -``` - +Enhance your documentation with rich media content including images, videos, PDFs, mathematical equations, and diagrams. ## Images @@ -101,7 +41,7 @@ Common image attributes: | `src` | URL or path to the image file | | `alt` | Alternative text for accessibility | | `title` | Tooltip text shown on hover | -| `width` and `height` | Dimensions of the image in pixels | +| `width` and `height` | Dimensions of the image (px) | | `noZoom` | Disables image zoom functionality | @@ -133,7 +73,7 @@ You can embed videos in your documentation using the HTML `