docs: add custom header and footer component documentation (#3478)

Co-authored-by: fern-api[bot] <115122769+fern-api[bot]@users.noreply.github.com>
Co-authored-by: Devin Logan <devinannlogan@gmail.com>

Author: 3 people

fern/products/docs/pages/changelog/2026-02-05.mdx

@@ -0,0 +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`.
+
+```yaml docs.yml
+header: ./components/CustomHeader.tsx
+footer: ./components/CustomFooter.tsx
+```
+
+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).

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,79 +237,4 @@ js:
 - Implement custom search (also requires [your Algolia credentials](/docs/customization/search))
 - Insert scripts and widgets
 
-## Custom components
-
-<Markdown src="/snippets/pro-plan.mdx"/>
-
-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.
-
-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`:
-
-<CodeBlocks>
-<CodeBlock title="fern/">
-```bash {5-7}
-  fern/
-  ├─ openapi/
-  ├─ pages/
-  ├─ images/
-  ├─ dist/
-    └─ output.css
-    └─ output.js
-  ├─ docs.yml
-  └─ fern.config.json
-```
-</CodeBlock>
-<CodeBlock title="docs.yml">
-```yaml
-css: ./dist/output.css
-js: ./dist/output.js
-```
-</CodeBlock>
-</CodeBlocks>
-
-### 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. 
-
-#### Example custom header
-
-<Frame>
-   <img alt="Custom header" src="./custom-header.png" />
-</Frame>
-
-```JavaScript
-ReactDOM.render(
-  React.createElement(NavHeader),
-  document.getElementById('fern-header'),
-)
-```
-
-#### Example custom footer
-
-<Frame>
-   <img alt="Custom footer" src="./custom-footer.png" />
-</Frame>
-
-```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.
-
-<Info>
-This approach is subject to change, with notice, as we make improvements to the plugin architecture.
-</Info>        
+                                                                                

fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx

@@ -5,20 +5,19 @@ description: Add custom React components to your Fern docs for interactive, serv
 
 <Markdown src="/snippets/pro-plan.mdx"/>
 
-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.
 
 <Note title="Defining a constant">
   Don't use a React component to define a constant. Instead, consider using [reusable snippets](/docs/writing-content/reusable-snippets).
 </Note>
 
-## How it works
+## Custom components in MDX
 
 <Steps>
   ### 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 }) => {
@@ -65,6 +64,35 @@ import { CustomCard } from "../components/CustomCard"
   ```
 </Steps>
 
+## Custom header and footer
+
+Replace Fern's default header or footer with your own React components.
+
+<Steps>
+  ### 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 (
+          <footer className="w-full py-8 px-6 bg-gray-100 dark:bg-gray-900">
+              <div className="max-w-7xl mx-auto">
+                  Plant Store API Documentation
+              </div>
+          </footer>
+      );
+  }
+  ```
+
+  ### Add the component paths to `docs.yml`
+
+  ```yaml docs.yml
+  header: ./components/CustomHeader.tsx
+  footer: ./components/CustomFooter.tsx
+  ```
+</Steps>
+
 ## 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:

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).
 </ParamField>
 
+<ParamField path="header" type="string" required={false} toc={true}>
+  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).
+</ParamField>
+
+<ParamField path="footer" type="string" required={false} toc={true}>
+  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).
+</ParamField>
+
 ## 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.