From 2c72e2afa728ea0374a6a3aa766fb3741f735b49 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Thu, 5 Feb 2026 00:22:58 +0000 Subject: [PATCH 1/5] docs: add custom header and footer component documentation --- .../docs/pages/changelog/2026-02-05.mdx | 28 ++++++ .../custom-components/custom-css-js.mdx | 90 +++++++++++++++++-- 2 files changed, 112 insertions(+), 6 deletions(-) create mode 100644 fern/products/docs/pages/changelog/2026-02-05.mdx diff --git a/fern/products/docs/pages/changelog/2026-02-05.mdx b/fern/products/docs/pages/changelog/2026-02-05.mdx new file mode 100644 index 000000000..d386b8ae7 --- /dev/null +++ b/fern/products/docs/pages/changelog/2026-02-05.mdx @@ -0,0 +1,28 @@ +## Server-side rendered custom header and footer + +Replace Fern's default header or footer with your own React components using the new `header` and `footer` properties in `docs.yml`. Components are server-side rendered for better SEO and performance, with no layout shifts or flashes during page load. + +```yaml docs.yml +header: ./components/CustomHeader.tsx +footer: ./components/CustomFooter.tsx + +experimental: + mdx-components: + - ./components +``` + +Create a TSX or JSX file with a default export: + +```tsx components/CustomFooter.tsx +export default function CustomFooter() { + return ( + + ); +} +``` + +Learn more about [custom header and footer components](/learn/docs/customization/custom-css-js#custom-header-and-footer). diff --git a/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx b/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx index aa875cf98..4f8593950 100644 --- a/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx +++ b/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx @@ -230,13 +230,91 @@ js: - Implement custom search (also requires [your Algolia credentials](/docs/customization/search)) - Insert scripts and widgets -## Custom components +## Custom header and footer -You can use custom CSS and JS to replace Fern's default UI components with your own. The `header` and `footer` -are the most commonly replaced components. You can replace any component in the docs, -including the sidebar, tabs, search bar, and more. +Replace Fern's default header or footer with your own React components. Custom components are server-side rendered for better SEO and performance. + + +### Create a component file + +Create a TSX or JSX file with a default export that returns your component: + + +```tsx +export default function CustomFooter() { + return ( + + ); +} +``` + + +### Reference in docs.yml + +Add the `header` or `footer` property to your `docs.yml` file, pointing to your component: + + +```yaml +header: ./components/CustomHeader.tsx +footer: ./components/CustomFooter.tsx +``` + + +### Add to mdx-components (required) + +Include your components directory in the `experimental.mdx-components` configuration so the CLI can upload the files: + + +```yaml +experimental: + mdx-components: + - ./components +``` + + + +### Component requirements + +Custom header and footer components must meet these requirements: + +- The file must have a **default export** returning a React component +- Use standard React and JSX syntax (TSX or JSX files) +- Tailwind CSS classes are available for styling +- Use the `.dark` class prefix for dark mode styles + +### Benefits over client-side injection + +Server-side rendered custom components provide several advantages over the [client-side JavaScript approach](#custom-components-client-side): + +- **No layout shifts**: Components render with the initial page load, eliminating flashes or jumps +- **Better SEO**: Search engines can index the rendered content +- **Faster page loads**: No additional JavaScript bundle to download and execute + +## Custom components (client-side) + +For components other than header and footer, or if you need more control over rendering, you can use client-side JavaScript to inject custom components into the DOM. To implement your own components in Fern Docs, write JavaScript to render your custom components in the DOM. Build to CSS and JavaScript files that @@ -268,7 +346,7 @@ js: ./dist/output.js See this [GitHub repo](https://github.com/fern-api/docs-custom-js-example) and its [generated docs page](https://custom-js-example.docs.buildwithfern.com/get-started/welcome) -for an example of how to replace the Fern `header` and `footer` with custom React components. +for an example of how to replace the Fern `header` and `footer` with custom React components using client-side JavaScript. #### Example custom header @@ -305,4 +383,4 @@ ReactDOM.render( This approach is subject to change, with notice, as we make improvements to the plugin architecture. - \ No newline at end of file + \ No newline at end of file From ec189d572abd77d3e104e791b7bc511effcdec4a Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Thu, 5 Feb 2026 01:00:21 +0000 Subject: [PATCH 2/5] docs: move custom header/footer to React components page, add properties to site-level settings --- .../docs/pages/changelog/2026-02-05.mdx | 2 +- .../custom-components/custom-css-js.mdx | 84 +------------------ .../custom-react-components.mdx | 32 ++++++- .../customization/site-level-settings.mdx | 8 ++ 4 files changed, 39 insertions(+), 87 deletions(-) diff --git a/fern/products/docs/pages/changelog/2026-02-05.mdx b/fern/products/docs/pages/changelog/2026-02-05.mdx index d386b8ae7..4be6fb0db 100644 --- a/fern/products/docs/pages/changelog/2026-02-05.mdx +++ b/fern/products/docs/pages/changelog/2026-02-05.mdx @@ -25,4 +25,4 @@ export default function CustomFooter() { } ``` -Learn more about [custom header and footer components](/learn/docs/customization/custom-css-js#custom-header-and-footer). +Learn more about [custom header and footer components](/learn/docs/writing-content/custom-react-components#custom-header-and-footer). diff --git a/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx b/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx index 4f8593950..fbef8fd0f 100644 --- a/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx +++ b/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx @@ -230,88 +230,6 @@ js: - Implement custom search (also requires [your Algolia credentials](/docs/customization/search)) - Insert scripts and widgets -## Custom header and footer - - - -Replace Fern's default header or footer with your own React components. Custom components are server-side rendered for better SEO and performance. - - -### Create a component file - -Create a TSX or JSX file with a default export that returns your component: - - -```tsx -export default function CustomFooter() { - return ( - - ); -} -``` - - -### Reference in docs.yml - -Add the `header` or `footer` property to your `docs.yml` file, pointing to your component: - - -```yaml -header: ./components/CustomHeader.tsx -footer: ./components/CustomFooter.tsx -``` - - -### Add to mdx-components (required) - -Include your components directory in the `experimental.mdx-components` configuration so the CLI can upload the files: - - -```yaml -experimental: - mdx-components: - - ./components -``` - - - -### Component requirements - -Custom header and footer components must meet these requirements: - -- The file must have a **default export** returning a React component -- Use standard React and JSX syntax (TSX or JSX files) -- Tailwind CSS classes are available for styling -- Use the `.dark` class prefix for dark mode styles - -### Benefits over client-side injection - -Server-side rendered custom components provide several advantages over the [client-side JavaScript approach](#custom-components-client-side): - -- **No layout shifts**: Components render with the initial page load, eliminating flashes or jumps -- **Better SEO**: Search engines can index the rendered content -- **Faster page loads**: No additional JavaScript bundle to download and execute - ## Custom components (client-side) For components other than header and footer, or if you need more control over rendering, you can use client-side JavaScript to inject custom components into the DOM. @@ -383,4 +301,4 @@ ReactDOM.render( This approach is subject to change, with notice, as we make improvements to the plugin architecture. - \ No newline at end of file + \ No newline at end of file diff --git a/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx b/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx index 740605409..69ca7a9a2 100644 --- a/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx +++ b/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx @@ -5,14 +5,40 @@ description: Add custom React components to your Fern docs for interactive, serv -You can extend Fern's built-in component library by adding your own custom React components. -This allows you to create unique, interactive elements that match your documentation needs. +You can extend Fern's built-in component library by adding your own custom React components. This allows you to create unique, interactive elements that match your documentation needs. Components are server-side rendered for better SEO and performance, with no layout shifts. Don't use a React component to define a constant. Instead, consider using [reusable snippets](/docs/writing-content/reusable-snippets). -## How it works +## Custom header and footer + +Replace Fern's default header or footer with your own React components using the `header` and `footer` properties in `docs.yml`: + +```yaml docs.yml +header: ./components/CustomHeader.tsx +footer: ./components/CustomFooter.tsx + +experimental: + mdx-components: + - ./components +``` + +Your component file must have a default export returning a React component. Tailwind CSS classes are available, and you can use the `.dark` class prefix for dark mode styles: + +```tsx components/CustomFooter.tsx +export default function CustomFooter() { + return ( +
+
+ Plant Store API Documentation +
+
+ ); +} +``` + +## Custom components in MDX ### Create a React component diff --git a/fern/products/docs/pages/customization/site-level-settings.mdx b/fern/products/docs/pages/customization/site-level-settings.mdx index 319517dd3..18ddce60b 100644 --- a/fern/products/docs/pages/customization/site-level-settings.mdx +++ b/fern/products/docs/pages/customization/site-level-settings.mdx @@ -111,6 +111,14 @@ navbar-links: [`metadata` configuration](/learn/docs/getting-started/global-configuration#seo-metadata-configuration). + + Path to a custom React component file (TSX or JSX) to replace Fern's default header. The component must have a default export. Learn more about [custom header and footer components](/learn/docs/writing-content/custom-react-components#custom-header-and-footer). + + + + Path to a custom React component file (TSX or JSX) to replace Fern's default footer. The component must have a default export. Learn more about [custom header and footer components](/learn/docs/writing-content/custom-react-components#custom-header-and-footer). + + ## Instances configuration An `instance` is the backend of a distinct docs website. Each instance is published to a unique domain using the `--instance` flag. It is most common to use instances to configure staging and production docs which publish to separate URLs. From 68377eca6ccfa054aff8cf8c9210777a6dc4e1e5 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Thu, 5 Feb 2026 01:01:19 +0000 Subject: [PATCH 3/5] docs: update dark mode styling example to show Tailwind syntax --- .../custom-components/custom-react-components.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx b/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx index 69ca7a9a2..88a1a06ff 100644 --- a/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx +++ b/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx @@ -24,7 +24,7 @@ experimental: - ./components ``` -Your component file must have a default export returning a React component. Tailwind CSS classes are available, and you can use the `.dark` class prefix for dark mode styles: +Your component file must have a default export returning a React component. Tailwind CSS classes are available, including the `dark:` prefix for dark mode styles (e.g., `dark:bg-gray-900`, `dark:text-gray-400`): ```tsx components/CustomFooter.tsx export default function CustomFooter() { From bd40357c679e1db508b7f38df7023c1a4861a974 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Thu, 5 Feb 2026 01:17:51 +0000 Subject: [PATCH 4/5] docs: remove client-side header/footer examples, add pointer to React components page --- .../custom-components/custom-css-js.mdx | 73 +------------------ 1 file changed, 2 insertions(+), 71 deletions(-) diff --git a/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx b/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx index fbef8fd0f..cb2cf6cfe 100644 --- a/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx +++ b/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx @@ -230,75 +230,6 @@ js: - Implement custom search (also requires [your Algolia credentials](/docs/customization/search)) - Insert scripts and widgets -## Custom components (client-side) +## Custom React components -For components other than header and footer, or if you need more control over rendering, you can use client-side JavaScript to inject custom components into the DOM. - -To implement your own components in Fern Docs, write JavaScript to render your -custom components in the DOM. Build to CSS and JavaScript files that -are stored in `fern/` and referenced in `docs.yml`: - - - -```bash {5-7} - fern/ - ├─ openapi/ - ├─ pages/ - ├─ images/ - ├─ dist/ - └─ output.css - └─ output.js - ├─ docs.yml - └─ fern.config.json -``` - - -```yaml -css: ./dist/output.css -js: ./dist/output.js -``` - - - -### Example custom components - -See this [GitHub repo](https://github.com/fern-api/docs-custom-js-example) -and its [generated docs page](https://custom-js-example.docs.buildwithfern.com/get-started/welcome) -for an example of how to replace the Fern `header` and `footer` with custom React components using client-side JavaScript. - -#### Example custom header - - - Custom header - - -```JavaScript -ReactDOM.render( - React.createElement(NavHeader), - document.getElementById('fern-header'), -) -``` - -#### Example custom footer - - - Custom footer - - -```JavaScript -ReactDOM.render( - React.createElement(NavFooter), - document.getElementById('fern-footer'), -) -``` - -### Important notes - -- `ReactDOM.render()` may need to be called multiple times to prevent it from unmounting (this side-effect will be removed in the future). -- `yarn build` or `npm build` must generate files with deterministic names to be referenced in `docs.yml`. The above example uses a [`vite` config](https://github.com/fern-api/docs-custom-js-example/blob/main/custom-app/vite.config.ts) to accomplish this. -- For your hosted Docs site, you may need to update your CD steps to include building the react-app. -- Custom components aren't supported in local development, but are supported in preview links. - - -This approach is subject to change, with notice, as we make improvements to the plugin architecture. - \ No newline at end of file +For custom header and footer components, or other reusable React components in your documentation, see [Custom React components](/learn/docs/writing-content/custom-react-components). \ No newline at end of file From 678339cc8350671ebbfed40ab9b919bdaeb7dd34 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 4 Feb 2026 20:43:16 -0500 Subject: [PATCH 5/5] clarify info --- .../docs/pages/changelog/2026-02-05.mdx | 20 +------ .../custom-components/custom-css-js.mdx | 13 ++-- .../custom-react-components.mdx | 60 ++++++++++--------- 3 files changed, 42 insertions(+), 51 deletions(-) diff --git a/fern/products/docs/pages/changelog/2026-02-05.mdx b/fern/products/docs/pages/changelog/2026-02-05.mdx index 4be6fb0db..cc236ebd9 100644 --- a/fern/products/docs/pages/changelog/2026-02-05.mdx +++ b/fern/products/docs/pages/changelog/2026-02-05.mdx @@ -1,28 +1,12 @@ ## Server-side rendered custom header and footer -Replace Fern's default header or footer with your own React components using the new `header` and `footer` properties in `docs.yml`. Components are server-side rendered for better SEO and performance, with no layout shifts or flashes during page load. +Replace Fern's default header or footer with your own React components using the new `header` and `footer` properties in `docs.yml`. ```yaml docs.yml header: ./components/CustomHeader.tsx footer: ./components/CustomFooter.tsx - -experimental: - mdx-components: - - ./components ``` -Create a TSX or JSX file with a default export: - -```tsx components/CustomFooter.tsx -export default function CustomFooter() { - return ( -
-
- Plant Store API Documentation -
-
- ); -} -``` +Components are server-side rendered for better SEO and performance, with no layout shifts during page load. Learn more about [custom header and footer components](/learn/docs/writing-content/custom-react-components#custom-header-and-footer). diff --git a/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx b/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx index cb2cf6cfe..1ef451c97 100644 --- a/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx +++ b/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx @@ -4,7 +4,14 @@ subtitle: Add custom CSS, global JavaScript, and UI components. description: Learn how to add custom CSS, JavaScript, and UI components to your Fern documentation. Style your docs with custom classes and scripts. --- -This page covers how to customize your docs with CSS, JavaScript, and custom components. However, you can [customize many things directly in your `docs.yml` file](/docs/configuration/site-level-settings), including colors, typography, navbar links, layout, analytics, and metadata. Try these built-in options first before adding custom code. +This page covers CSS and JavaScript customization: + +- **CSS** for styling, visual changes, and hiding elements +- **JavaScript** for client-side behavior, third-party integrations, and widgets + +For server-rendered components like custom headers, footers, or reusable elements in your MDX content, see [Custom React components](/learn/docs/writing-content/custom-react-components). + +You can also [customize many things directly in your `docs.yml` file](/docs/configuration/site-level-settings), including colors, typography, navbar links, layout, analytics, and metadata. Try these built-in options first before adding custom code. ## Custom CSS @@ -230,6 +237,4 @@ js: - Implement custom search (also requires [your Algolia credentials](/docs/customization/search)) - Insert scripts and widgets -## Custom React components - -For custom header and footer components, or other reusable React components in your documentation, see [Custom React components](/learn/docs/writing-content/custom-react-components). \ No newline at end of file + \ No newline at end of file diff --git a/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx b/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx index 88a1a06ff..e88abde1c 100644 --- a/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx +++ b/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx @@ -11,40 +11,13 @@ You can extend Fern's built-in component library by adding your own custom React Don't use a React component to define a constant. Instead, consider using [reusable snippets](/docs/writing-content/reusable-snippets). -## Custom header and footer - -Replace Fern's default header or footer with your own React components using the `header` and `footer` properties in `docs.yml`: - -```yaml docs.yml -header: ./components/CustomHeader.tsx -footer: ./components/CustomFooter.tsx - -experimental: - mdx-components: - - ./components -``` - -Your component file must have a default export returning a React component. Tailwind CSS classes are available, including the `dark:` prefix for dark mode styles (e.g., `dark:bg-gray-900`, `dark:text-gray-400`): - -```tsx components/CustomFooter.tsx -export default function CustomFooter() { - return ( -
-
- Plant Store API Documentation -
-
- ); -} -``` - ## Custom components in MDX ### Create a React component - Let's start by creating a `components` folder where you can define your react components. Note - that the react components can be defined in `.ts`, `.tsx`, `.js` or `.mdx` files. + Let's start by creating a `components` folder where you can define your React components. Note + that the React components can be defined in `.ts`, `.tsx`, `.js` or `.mdx` files. ```ts components/CustomCard.tsx export const CustomCard = ({ title, text, link, sparkle = false }) => { @@ -91,6 +64,35 @@ import { CustomCard } from "../components/CustomCard" ``` +## Custom header and footer + +Replace Fern's default header or footer with your own React components. + + + ### Create your component + + Your component file must have a default export returning a React component. Tailwind CSS classes are available, including the `dark:` prefix for dark mode styles (e.g., `dark:bg-gray-900`, `dark:text-gray-400`): + + ```tsx components/CustomFooter.tsx + export default function CustomFooter() { + return ( + + ); + } + ``` + + ### Add the component paths to `docs.yml` + + ```yaml docs.yml + header: ./components/CustomHeader.tsx + footer: ./components/CustomFooter.tsx + ``` + + ## Why not just use custom CSS and JS instead? While you can bundle React components as custom JavaScript, using Fern's built-in React component support provides several key advantages: