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..cc236ebd9 --- /dev/null +++ b/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). 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..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,79 +237,4 @@ js: - Implement custom search (also requires [your Algolia credentials](/docs/customization/search)) - Insert scripts and widgets -## Custom components - - - -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`: - - - -```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. - -#### 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 + \ 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..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 @@ -5,20 +5,19 @@ 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 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 }) => { @@ -65,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 ( +
+
+ Plant Store API Documentation +
+
+ ); + } + ``` + + ### 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: 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.