feat(docs): add blog navigation item as an alias for changelog

docs-yml.schema.json

@@ -1112,6 +1112,16 @@
               "type": "null"
             }
           ]
+        },
+        "blog": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.ChangelogFolderRelativePath"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       },
       "required": [
@@ -2954,6 +2964,89 @@
       ],
       "additionalProperties": false
     },
+    "docs.BlogConfiguration": {
+      "type": "object",
+      "properties": {
+        "viewers": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.Role"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "orphaned": {
+          "oneOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "When `orphaned` is set to `true`, the roles will not inherit from parents."
+        },
+        "feature-flag": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.FeatureFlagConfiguration"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "blog": {
+          "$ref": "#/definitions/docs.ChangelogFolderRelativePath"
+        },
+        "title": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "slug": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "icon": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "hidden": {
+          "oneOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "blog"
+      ],
+      "additionalProperties": false
+    },
     "docs.TitleSource": {
       "type": "string",
       "enum": [
@@ -3130,6 +3223,9 @@
         {
           "$ref": "#/definitions/docs.ChangelogConfiguration"
         },
+        {
+          "$ref": "#/definitions/docs.BlogConfiguration"
+        },
         {
           "$ref": "#/definitions/docs.FolderConfiguration"
         }

fern/apis/docs-yml/definition/docs.yml

@@ -626,6 +626,7 @@ types:
           Tabs with `href` must not have children in the navigation config.
       target: optional<Target>
       changelog: optional<ChangelogFolderRelativePath>
+      blog: optional<ChangelogFolderRelativePath>
 
   ChangelogFolderRelativePath:
     type: string
@@ -816,6 +817,7 @@ types:
       - LibraryReferenceConfiguration
       - LinkConfiguration
       - ChangelogConfiguration
+      - BlogConfiguration
       - FolderConfiguration
 
   LogoConfiguration:
@@ -1411,6 +1413,16 @@ types:
       hidden: optional<boolean>
       # skip-slug: optional<boolean> # skip-slug is not needed for changelog
 
+  BlogConfiguration:
+    extends: [WithPermissions, WithFeatureFlags]
+    properties:
+      blog: ChangelogFolderRelativePath
+      title: optional<string> # defaults to "Blog"
+      slug: optional<string>
+      icon: optional<string>
+      hidden: optional<boolean>
+      # skip-slug: optional<boolean> # skip-slug is not needed for blog
+
   SectionConfiguration:
     extends: [WithPermissions, WithFeatureFlags]
     properties:

packages/cli/cli/changes/unreleased/add-blog-navigation-item.yml

@@ -0,0 +1,5 @@
+# yaml-language-server: $schema=../../../../../fern-changes-yml.schema.json
+
+- summary: |
+    Add a blog navigation item as an alias for changelog navigation.
+  type: feat

packages/cli/configuration-loader/src/docs-yml/__test__/blogNavigationAlias.test.ts

@@ -0,0 +1,115 @@
+import { docsYml } from "@fern-api/configuration";
+import { AbsoluteFilePath } from "@fern-api/fs-utils";
+import { createMockTaskContext } from "@fern-api/task-context";
+import { describe, expect, it } from "vitest";
+
+import { parseDocsConfiguration } from "../parseDocsConfiguration.js";
+
+const FAKE_FERN_DIR = "/fern" as AbsoluteFilePath;
+const FAKE_CONFIG_PATH = "/fern/docs.yml" as AbsoluteFilePath;
+
+async function parseRawDocsYml(rawDocsYml: unknown): Promise<docsYml.ParsedDocsConfiguration> {
+    const rawDocsConfiguration = docsYml.RawSchemas.Serializer.DocsConfiguration.parseOrThrow(rawDocsYml);
+    return await parseDocsConfiguration({
+        rawDocsConfiguration,
+        absolutePathToFernFolder: FAKE_FERN_DIR,
+        absoluteFilepathToDocsConfig: FAKE_CONFIG_PATH,
+        context: createMockTaskContext()
+    });
+}
+
+describe("blog navigation alias", () => {
+    it("normalizes a top-level blog item to a changelog item", async () => {
+        const changelog = await parseRawDocsYml({
+            instances: [],
+            navigation: [{ changelog: "blog" }]
+        });
+        const blog = await parseRawDocsYml({
+            instances: [],
+            navigation: [{ blog: "blog" }]
+        });
+        if (changelog.navigation.type !== "untabbed" || blog.navigation.type !== "untabbed") {
+            throw new Error("Expected untabbed navigation");
+        }
+
+        expect(changelog.navigation).toEqual({
+            type: "untabbed",
+            items: [
+                {
+                    type: "changelog",
+                    changelog: [],
+                    hidden: false,
+                    icon: undefined,
+                    title: "Changelog",
+                    slug: undefined,
+                    viewers: undefined,
+                    orphaned: undefined,
+                    featureFlags: undefined
+                }
+            ]
+        });
+        expect(blog.navigation).toEqual({
+            ...changelog.navigation,
+            items: [{ ...changelog.navigation.items[0], title: "Blog" }]
+        });
+    });
+
+    it("normalizes a tab blog item to a changelog child", async () => {
+        const changelog = await parseRawDocsYml({
+            instances: [],
+            tabs: {
+                posts: {
+                    "display-name": "Posts",
+                    changelog: "blog"
+                }
+            },
+            navigation: [{ tab: "posts" }]
+        });
+        const blog = await parseRawDocsYml({
+            instances: [],
+            tabs: {
+                posts: {
+                    "display-name": "Posts",
+                    blog: "blog"
+                }
+            },
+            navigation: [{ tab: "posts" }]
+        });
+
+        expect(changelog.navigation).toEqual({
+            type: "tabbed",
+            items: [
+                {
+                    title: "Posts",
+                    icon: undefined,
+                    slug: undefined,
+                    skipUrlSlug: undefined,
+                    hidden: undefined,
+                    child: {
+                        type: "changelog",
+                        changelog: []
+                    },
+                    viewers: undefined,
+                    orphaned: undefined,
+                    featureFlags: undefined
+                }
+            ]
+        });
+        expect(blog.navigation).toEqual(changelog.navigation);
+    });
+
+    it("preserves an explicit blog title", async () => {
+        const parsed = await parseRawDocsYml({
+            instances: [],
+            navigation: [{ blog: "blog", title: "Engineering Blog" }]
+        });
+
+        if (parsed.navigation.type !== "untabbed") {
+            throw new Error("Expected untabbed navigation");
+        }
+        expect(parsed.navigation.items[0]).toMatchObject({
+            type: "changelog",
+            title: "Engineering Blog"
+        });
+    });
+});

packages/cli/configuration-loader/src/docs-yml/parseDocsConfiguration.ts

@@ -1263,7 +1263,8 @@ async function convertNavigationTabConfiguration({
         };
     }
 
-    if (tab.changelog != null) {
+    const changelogPath = docsYml.getChangelogFolderFromTabConfig(tab);
+    if (changelogPath != null) {
         return {
             title: tab.displayName,
             icon: resolveIconPath(tab.icon, absolutePathToConfig),
@@ -1272,7 +1273,7 @@ async function convertNavigationTabConfiguration({
             hidden: tab.hidden,
             child: {
                 type: "changelog",
-                changelog: await listFiles(resolveFilepath(tab.changelog, absolutePathToConfig), "{md,mdx}")
+                changelog: await listFiles(resolveFilepath(changelogPath, absolutePathToConfig), "{md,mdx}")
             },
             viewers: parseRoles(tab.viewers),
             orphaned: tab.orphaned,
@@ -1409,7 +1410,7 @@ async function expandFolderConfiguration({
 }
 
 async function convertNavigationItem({
-    rawConfig,
+    rawConfig: rawConfigInput,
     absolutePathToFernFolder,
     absolutePathToConfig,
     context,
@@ -1421,6 +1422,8 @@ async function convertNavigationItem({
     context: TaskContext;
     folderTitleSource?: docsYml.RawSchemas.TitleSource;
 }): Promise<docsYml.DocsNavigationItem> {
+    const rawConfig = normalizeNavigationItem(rawConfigInput);
+
     if (isRawPageConfig(rawConfig)) {
         return parsePageConfig(rawConfig, absolutePathToConfig);
     }
@@ -1741,6 +1744,25 @@ function isRawChangelogConfig(item: unknown): item is docsYml.RawSchemas.Changel
     return isPlainObject(item) && typeof item.changelog === "string";
 }
 
+function isRawBlogConfig(item: unknown): item is docsYml.RawSchemas.BlogConfiguration {
+    return isPlainObject(item) && typeof item.blog === "string";
+}
+
+function normalizeNavigationItem(
+    rawConfig: docsYml.RawSchemas.NavigationItem
+): Exclude<docsYml.RawSchemas.NavigationItem, docsYml.RawSchemas.BlogConfiguration> {
+    if (!isRawBlogConfig(rawConfig)) {
+        return rawConfig;
+    }
+
+    const { blog, ...rest } = rawConfig;
+    return {
+        ...rest,
+        changelog: blog,
+        title: rawConfig.title ?? "Blog"
+    };
+}
+
 function isRawFolderConfig(item: unknown): item is docsYml.RawSchemas.FolderConfiguration {
     return isPlainObject(item) && typeof item.folder === "string";
 }

packages/cli/configuration/src/docs-yml/DocsYmlSchemas.ts

@@ -681,6 +681,16 @@ export const ChangelogConfiguration = WithPermissions.merge(WithFeatureFlags).me
     })
 );
 
+export const BlogConfiguration = WithPermissions.merge(WithFeatureFlags).merge(
+    z.object({
+        blog: ChangelogFolderRelativePath,
+        title: z.string().optional(),
+        slug: z.string().optional(),
+        icon: z.string().optional(),
+        hidden: z.boolean().optional()
+    })
+);
+
 // ===== Library Reference Configuration =====
 
 export const LibraryReferenceConfiguration = WithPermissions.merge(WithFeatureFlags).merge(
@@ -820,6 +830,7 @@ export const NavigationItem: z.ZodType<unknown> = z.lazy(() =>
         LibraryReferenceConfiguration,
         LinkConfiguration,
         ChangelogConfiguration,
+        BlogConfiguration,
         FolderConfiguration
     ])
 );
@@ -884,7 +895,8 @@ export const TabConfig = WithPermissions.merge(WithFeatureFlags).merge(
         hidden: z.boolean().optional(),
         href: z.string().optional(),
         target: Target.optional(),
-        changelog: ChangelogFolderRelativePath.optional()
+        changelog: ChangelogFolderRelativePath.optional(),
+        blog: ChangelogFolderRelativePath.optional()
     })
 );
 

packages/cli/configuration/src/docs-yml/index.ts

@@ -1,4 +1,5 @@
 export * as DocsYmlSchemas from "./DocsYmlSchemas.js";
+export * from "./navigation.js";
 export * from "./ParsedDocsConfiguration.js";
 export * as RawSchemas from "./schemas/index.js";
 export * from "./themeEligibleFields.js";

packages/cli/configuration/src/docs-yml/navigation.ts

@@ -0,0 +1,19 @@
+import * as RawSchemas from "./schemas/index.js";
+
+export function getChangelogFolderFromNavigationItem(
+    item: RawSchemas.NavigationItem
+): RawSchemas.ChangelogFolderRelativePath | undefined {
+    if ("changelog" in item) {
+        return item.changelog;
+    }
+    if ("blog" in item) {
+        return item.blog;
+    }
+    return undefined;
+}
+
+export function getChangelogFolderFromTabConfig(
+    tab: RawSchemas.TabConfig
+): RawSchemas.ChangelogFolderRelativePath | undefined {
+    return tab.changelog ?? tab.blog;
+}