Clarify relative path resolution across all docs configuration references (#4649)

devin-ai-integration[bot] · bot_apk · devalog · web-flow · commit 4a374150f716 · 2026-03-31T13:14:25.000-04:00
Co-authored-by: Devin AI &lt;158243242+devin-ai-integration[bot]@users.noreply.github.com&gt;
Co-authored-by: bot_apk &lt;apk@cognition.ai&gt;
Co-authored-by: Devin Logan &lt;devinannlogan@gmail.com&gt;
diff --git a/fern/products/docs/pages/changelog/2025-11-03.mdx b/fern/products/docs/pages/changelog/2025-11-03.mdx
@@ -35,7 +35,7 @@ You can use your own image files as icons throughout your `docs.yml` navigation
 
 Icons support three formats:
 - **Font Awesome icons**: Use icon names like `fa-solid fa-seedling` or `fa-regular fa-leaf`. Pro and Brand icons from Font Awesome are supported.
-- **Custom image files**: Use relative paths to custom image files (e.g., `./assets/icons/plant-icon.svg`). Paths are relative to the `docs.yml` file.
+- **Custom image files**: Use relative paths to custom image files (e.g., `./assets/icons/plant-icon.svg`). Paths are relative to the YAML file where the icon is referenced (e.g., `docs.yml`).
 - **Inline SVG**: Provide an SVG string wrapped in quotes.
 
 ```yaml Sidebar icons in docs.yml
diff --git a/fern/products/docs/pages/changelog/2025-12-20.mdx b/fern/products/docs/pages/changelog/2025-12-20.mdx
@@ -4,7 +4,7 @@ tags: ["components", "customization"]
 
 ## Custom SVG icons in card and icon components
 
-The Card and Icon components support relative paths to SVG files. Use a relative path like `./images/icon.svg` to display custom SVG icons from your project.
+The Card and Icon components support relative paths to SVG files. Use a relative path like `./images/icon.svg` to display custom SVG icons from your project. Paths are relative to the page where the component is used.
 
 ```jsx Markdown
 <Card 
diff --git a/fern/products/docs/pages/customization/site-level-settings.mdx b/fern/products/docs/pages/customization/site-level-settings.mdx
@@ -61,7 +61,7 @@ navbar-links:
 </ParamField>
 
 <ParamField path="favicon" type="string" required={false} toc={true}>
-  Relative filepath to the favicon.
+  Relative filepath to the favicon. The path is relative to the YAML file where it is set (e.g., `docs.yml`).
 </ParamField>
 
 <ParamField path="colors" type="objects" required={true} toc={true}>
@@ -234,11 +234,11 @@ logo:
 </ParamField>
 
 <ParamField path="logo.dark" type="string" required={false} toc={true}>
-  Path to your dark mode logo file, relative to the docs root. SVG format is recommended for optimal quality. Example: `assets/images/logo-dark.svg`
+  Path to your dark mode logo file, relative to the YAML file where it is set (e.g., `docs.yml`). SVG format is recommended for optimal quality. Example: `assets/images/logo-dark.svg`
 </ParamField>
 
 <ParamField path="logo.light" type="string" required={false} toc={true}>
-  Path to your light mode logo file, relative to the docs root. SVG format is recommended for optimal quality. Example: `assets/images/logo-light.svg`
+  Path to your light mode logo file, relative to the YAML file where it is set (e.g., `docs.yml`). SVG format is recommended for optimal quality. Example: `assets/images/logo-light.svg`
 </ParamField>
 
 <ParamField path="logo.right-text" type="string" required={false} toc={true}>
@@ -436,11 +436,11 @@ background-image:
 ```
 
 <ParamField path="background-image.light" type="string" required={false} toc={true}>
-  Relative filepath to the light-mode background image. 
+  Relative filepath to the light-mode background image. The path is relative to the YAML file where it is set (e.g., `docs.yml`).
 </ParamField>
 
 <ParamField path="background-image.dark" type="string" required={false} toc={true}>
-  Relative filepath to the dark-mode background image.
+  Relative filepath to the dark-mode background image. The path is relative to the YAML file where it is set (e.g., `docs.yml`).
 </ParamField>
 
 
@@ -534,7 +534,7 @@ typography:
 </ParamField>
 
 <ParamField path="path" type="string" required={false} toc={true}>
-  The path to your font file, relative to your docs folder. Use this when you have a single font file. For multiple font files (like separate files for bold, italic etc), use `paths` instead.
+  The path to your font file, relative to the YAML file where it is set (e.g., `docs.yml`). Use this when you have a single font file. For multiple font files (like separate files for bold, italic etc), use `paths` instead.
 </ParamField>
 
 <ParamField path="weight" type="string | number" required={false} toc={true}>
@@ -947,7 +947,7 @@ landing-page:
 </ParamField>
 
 <ParamField path="path" type="string" required={true}>
-  Relative filepath to the desired landing page Markdown file. 
+  Relative filepath to the desired landing page Markdown file. The path is relative to the YAML file where it is set (e.g., `docs.yml`).
 </ParamField>
 
 <ParamField path="slug" type="string" required={false} toc={true}>
diff --git a/fern/products/docs/pages/navigation/tabs.mdx b/fern/products/docs/pages/navigation/tabs.mdx
@@ -113,7 +113,7 @@ theme:
 </ParamField>
 
 <ParamField path="changelog" type="string">
-  Path to a [changelog](/learn/docs/configuration/changelogs) folder relative to the `fern` directory
+  Path to a [changelog](/learn/docs/configuration/changelogs) folder, relative to the YAML file where it is set (e.g., `docs.yml`)
 </ParamField>
 
 <ParamField path="viewers" type="string | list">
diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx
@@ -121,7 +121,7 @@ metadata:
 </ParamField>
 
 <ParamField path="metadata.og:background-image" type="string" required={false} toc={true}>
-  A custom background image for dynamically generated OG images. Can be a URL or a relative file path. When set, this image is used as the background instead of a solid color.
+  A custom background image for dynamically generated OG images. Can be a URL or a relative file path. Relative paths are resolved from the YAML file where this property is set (e.g., `docs.yml`). When set, this image is used as the background instead of a solid color.
 </ParamField>
 
 ### Twitter / X
diff --git a/fern/snippets/icons.mdx b/fern/snippets/icons.mdx
@@ -1,4 +1,4 @@
 Icons can be in three formats:
   - **Font Awesome icons**: Use icon names like `fa-solid fa-rocket`. Pro and Brand Icons from Font Awesome are supported.
-  - **Custom image files**: Use relative paths to image files (e.g., `./assets/icons/my-icon.svg` or `../assets/icons/my-icon.png`). Paths are relative to the `docs.yml` file.
-  - **Inline SVG**: Provide an SVG string wrapped in quotes (e.g., `"<svg>...</svg>"`).
+  - **Custom image files**: Use relative paths to image files (e.g., `./assets/icons/my-icon.svg` or `../assets/icons/my-icon.png`). Paths are relative to the YAML file where the icon is referenced (e.g., `docs.yml`). For example, if you set an icon in `fern/products/my-product.yml`, the path `./assets/icon.svg` resolves to `fern/products/assets/icon.svg`. If you set it in `fern/docs.yml`, the same path resolves to `fern/assets/icon.svg`.
+  - **Inline SVG**: Provide an SVG string wrapped in quotes (e.g., `"<svg>...</svg>"`).
diff --git a/fern/snippets/seo-metadata-site.mdx b/fern/snippets/seo-metadata-site.mdx
@@ -92,7 +92,7 @@ metadata:
 </ParamField>
 
 <ParamField path="metadata.og:background-image" type="string" required={false}>
-  A custom background image for dynamically generated OG images. Can be a URL or a relative file path.
+  A custom background image for dynamically generated OG images. Can be a URL or a relative file path. Relative paths are resolved from the YAML file where this property is set (e.g., `docs.yml`).
 </ParamField>
 
 <ParamField path="metadata.canonical-host" type="string" required={false}>
