feat(docs): add blog: docs.yml config key [FSE-57]

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

@@ -75,6 +75,8 @@ function getAllPagesFromNavigationConfig(navigation: docsYml.DocsNavigationConfi
                     );
                 } else if (tab.child.type === "changelog") {
                     return tab.child.changelog;
+                } else if (tab.child.type === "blog") {
+                    return tab.child.blog;
                 }
                 return [];
             });
@@ -129,6 +131,8 @@ export function getAllPagesFromNavigationItem({ item }: { item: docsYml.DocsNavi
             ]);
         case "changelog":
             return item.changelog;
+        case "blog":
+            return item.blog;
         case "librarySection":
             // Library docs pages are generated locally, but referenced via _navigation.yml
             return [];

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

@@ -100,6 +100,7 @@ export function visitDocsNavigationItem({
         case "page":
         case "link":
         case "changelog":
+        case "blog":
         case "librarySection":
             return;
         default:

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

@@ -1280,6 +1280,23 @@ async function convertNavigationTabConfiguration({
         };
     }
 
+    if (tab.blog != null) {
+        return {
+            title: tab.displayName,
+            icon: resolveIconPath(tab.icon, absolutePathToConfig),
+            slug: tab.slug,
+            skipUrlSlug: tab.skipSlug,
+            hidden: tab.hidden,
+            child: {
+                type: "blog",
+                blog: await listFiles(resolveFilepath(tab.blog, absolutePathToConfig), "{md,mdx}")
+            },
+            viewers: parseRoles(tab.viewers),
+            orphaned: tab.orphaned,
+            featureFlags: convertFeatureFlag(tab.featureFlag)
+        };
+    }
+
     assertNever(tab as never);
 }
 
@@ -1334,6 +1351,7 @@ async function convertNavigationConfiguration({
 }
 
 const DEFAULT_CHANGELOG_TITLE = "Changelog";
+const DEFAULT_BLOG_TITLE = "Blog";
 
 async function expandFolderConfiguration({
     rawConfig,
@@ -1518,6 +1536,19 @@ async function convertNavigationItem({
             featureFlags: convertFeatureFlag(rawConfig.featureFlag)
         };
     }
+    if (isRawBlogConfig(rawConfig)) {
+        return {
+            type: "blog",
+            blog: await listFiles(resolveFilepath(rawConfig.blog, absolutePathToConfig), "{md,mdx}"),
+            hidden: rawConfig.hidden ?? false,
+            icon: resolveIconPath(rawConfig.icon, absolutePathToConfig),
+            title: rawConfig.title ?? DEFAULT_BLOG_TITLE,
+            slug: rawConfig.slug,
+            viewers: parseRoles(rawConfig.viewers),
+            orphaned: rawConfig.orphaned,
+            featureFlags: convertFeatureFlag(rawConfig.featureFlag)
+        };
+    }
     if (isRawFolderConfig(rawConfig)) {
         return await expandFolderConfiguration({
             rawConfig,
@@ -1741,6 +1772,10 @@ 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 isRawFolderConfig(item: unknown): item is docsYml.RawSchemas.FolderConfiguration {
     return isPlainObject(item) && typeof item.folder === "string";
 }

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

@@ -6,6 +6,8 @@ export const TabId = z.string();
 
 export const ChangelogFolderRelativePath = z.string();
 
+export const BlogFolderRelativePath = z.string();
+
 export const AudienceId = z.string();
 
 export const RoleId = z.string();
@@ -681,6 +683,19 @@ export const ChangelogConfiguration = WithPermissions.merge(WithFeatureFlags).me
     })
 );
 
+// ===== Blog Configuration =====
+// Mirrors ChangelogConfiguration — a directory of dated markdown posts rendered
+// as a card grid (vs. the changelog timeline). See ADR 0023 (fern-platform).
+export const BlogConfiguration = WithPermissions.merge(WithFeatureFlags).merge(
+    z.object({
+        blog: BlogFolderRelativePath,
+        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 +835,7 @@ export const NavigationItem: z.ZodType<unknown> = z.lazy(() =>
         LibraryReferenceConfiguration,
         LinkConfiguration,
         ChangelogConfiguration,
+        BlogConfiguration,
         FolderConfiguration
     ])
 );
@@ -884,7 +900,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: BlogFolderRelativePath.optional()
     })
 );
 

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

@@ -333,6 +333,7 @@ type TabbedNavigationChild =
     | TabbedNavigationChild.Layout
     | TabbedNavigationChild.Link
     | TabbedNavigationChild.Changelog
+    | TabbedNavigationChild.Blog
     | TabbedNavigationChild.Variants;
 
 export declare namespace TabbedNavigationChild {
@@ -352,6 +353,11 @@ export declare namespace TabbedNavigationChild {
         changelog: AbsoluteFilePath[];
     }
 
+    export interface Blog {
+        type: "blog";
+        blog: AbsoluteFilePath[];
+    }
+
     export interface Variants {
         type: "variants";
         variants: TabVariant[];
@@ -377,7 +383,8 @@ export type DocsNavigationItem =
     | DocsNavigationItem.ApiSection
     | DocsNavigationItem.LibrarySection
     | DocsNavigationItem.Link
-    | DocsNavigationItem.Changelog;
+    | DocsNavigationItem.Changelog
+    | DocsNavigationItem.Blog;
 
 export declare namespace DocsNavigationItem {
     export interface Page
@@ -455,6 +462,17 @@ export declare namespace DocsNavigationItem {
         slug: string | undefined;
     }
 
+    export interface Blog
+        extends CjsFdrSdk.navigation.v1.WithPermissions,
+            CjsFdrSdk.navigation.latest.WithFeatureFlags {
+        type: "blog";
+        blog: AbsoluteFilePath[];
+        title: string;
+        icon: string | AbsoluteFilePath | undefined;
+        hidden: boolean | undefined;
+        slug: string | undefined;
+    }
+
     export interface LibrarySection
         extends CjsFdrSdk.navigation.v1.WithPermissions,
             CjsFdrSdk.navigation.latest.WithFeatureFlags {

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/BlogConfiguration.ts

@@ -0,0 +1,11 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as FernDocsConfig from "../../../index.js";
+
+export interface BlogConfiguration extends FernDocsConfig.WithPermissions, FernDocsConfig.WithFeatureFlags {
+    blog: FernDocsConfig.BlogFolderRelativePath;
+    title?: string;
+    slug?: string;
+    icon?: string;
+    hidden?: boolean;
+}

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/BlogFolderRelativePath.ts

@@ -0,0 +1,15 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * The relative path to a folder containing markdown blog posts broken down by date.
+ *
+ * Example:
+ * ```
+ * blog: "blog"
+ * ```
+ *
+ * This will look for markdown files in the `/fern/blog` directory, which should contain files named like
+ * - `/fern/blog/2024-04-29-my-post.mdx`.
+ * - `/fern/blog/2023-01-02-another-post.mdx`.
+ */
+export type BlogFolderRelativePath = string;

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/NavigationItem.ts

@@ -9,4 +9,5 @@ export type NavigationItem =
     | FernDocsConfig.LibraryReferenceConfiguration
     | FernDocsConfig.LinkConfiguration
     | FernDocsConfig.ChangelogConfiguration
+    | FernDocsConfig.BlogConfiguration
     | FernDocsConfig.FolderConfiguration;

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/TabConfig.ts

@@ -16,4 +16,5 @@ export interface TabConfig extends FernDocsConfig.WithPermissions, FernDocsConfi
     href?: string;
     target?: FernDocsConfig.Target;
     changelog?: FernDocsConfig.ChangelogFolderRelativePath;
+    blog?: FernDocsConfig.BlogFolderRelativePath;
 }

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/index.ts

@@ -23,6 +23,8 @@ export * from "./BackgroundImageThemedConfig.js";
 export * from "./BodyThemeConfig.js";
 export * from "./ChangelogConfiguration.js";
 export * from "./ChangelogFolderRelativePath.js";
+export * from "./BlogConfiguration.js";
+export * from "./BlogFolderRelativePath.js";
 export * from "./ChangelogLayout.js";
 export * from "./CheckConfig.js";
 export * from "./CheckRuleSeverity.js";

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/BlogConfiguration.ts

@@ -0,0 +1,32 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as FernDocsConfig from "../../../../api/index.js";
+import * as core from "../../../../core/index.js";
+import type * as serializers from "../../../index.js";
+import { BlogFolderRelativePath } from "./BlogFolderRelativePath.js";
+import { WithFeatureFlags } from "./WithFeatureFlags.js";
+import { WithPermissions } from "./WithPermissions.js";
+
+export const BlogConfiguration: core.serialization.ObjectSchema<
+    serializers.BlogConfiguration.Raw,
+    FernDocsConfig.BlogConfiguration
+> = core.serialization
+    .object({
+        blog: BlogFolderRelativePath,
+        title: core.serialization.string().optional(),
+        slug: core.serialization.string().optional(),
+        icon: core.serialization.string().optional(),
+        hidden: core.serialization.boolean().optional(),
+    })
+    .extend(WithPermissions)
+    .extend(WithFeatureFlags);
+
+export declare namespace BlogConfiguration {
+    export interface Raw extends WithPermissions.Raw, WithFeatureFlags.Raw {
+        blog: BlogFolderRelativePath.Raw;
+        title?: string | null;
+        slug?: string | null;
+        icon?: string | null;
+        hidden?: boolean | null;
+    }
+}

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/BlogFolderRelativePath.ts

@@ -0,0 +1,14 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as FernDocsConfig from "../../../../api/index.js";
+import * as core from "../../../../core/index.js";
+import type * as serializers from "../../../index.js";
+
+export const BlogFolderRelativePath: core.serialization.Schema<
+    serializers.BlogFolderRelativePath.Raw,
+    FernDocsConfig.BlogFolderRelativePath
+> = core.serialization.string();
+
+export declare namespace BlogFolderRelativePath {
+    export type Raw = string;
+}

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/NavigationItem.ts

@@ -4,6 +4,7 @@ import type * as FernDocsConfig from "../../../../api/index.js";
 import * as core from "../../../../core/index.js";
 import * as serializers from "../../../index.js";
 import { ApiReferenceConfiguration } from "./ApiReferenceConfiguration.js";
+import { BlogConfiguration } from "./BlogConfiguration.js";
 import { ChangelogConfiguration } from "./ChangelogConfiguration.js";
 import { FolderConfiguration } from "./FolderConfiguration.js";
 import { LibraryReferenceConfiguration } from "./LibraryReferenceConfiguration.js";
@@ -18,6 +19,7 @@ export const NavigationItem: core.serialization.Schema<serializers.NavigationIte
         LibraryReferenceConfiguration,
         LinkConfiguration,
         ChangelogConfiguration,
+        BlogConfiguration,
         FolderConfiguration,
     ]);
 
@@ -29,5 +31,6 @@ export declare namespace NavigationItem {
         | LibraryReferenceConfiguration.Raw
         | LinkConfiguration.Raw
         | ChangelogConfiguration.Raw
+        | BlogConfiguration.Raw
         | FolderConfiguration.Raw;
 }

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/TabConfig.ts

@@ -3,6 +3,7 @@
 import type * as FernDocsConfig from "../../../../api/index.js";
 import * as core from "../../../../core/index.js";
 import type * as serializers from "../../../index.js";
+import { BlogFolderRelativePath } from "./BlogFolderRelativePath.js";
 import { ChangelogFolderRelativePath } from "./ChangelogFolderRelativePath.js";
 import { Target } from "./Target.js";
 import { WithFeatureFlags } from "./WithFeatureFlags.js";
@@ -19,6 +20,7 @@ export const TabConfig: core.serialization.ObjectSchema<serializers.TabConfig.Ra
             href: core.serialization.string().optional(),
             target: Target.optional(),
             changelog: ChangelogFolderRelativePath.optional(),
+            blog: BlogFolderRelativePath.optional(),
         })
         .extend(WithPermissions)
         .extend(WithFeatureFlags);
@@ -33,5 +35,6 @@ export declare namespace TabConfig {
         href?: string | null;
         target?: Target.Raw | null;
         changelog?: ChangelogFolderRelativePath.Raw | null;
+        blog?: BlogFolderRelativePath.Raw | null;
     }
 }

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/index.ts

@@ -23,6 +23,8 @@ export * from "./BackgroundImageThemedConfig.js";
 export * from "./BodyThemeConfig.js";
 export * from "./ChangelogConfiguration.js";
 export * from "./ChangelogFolderRelativePath.js";
+export * from "./BlogConfiguration.js";
+export * from "./BlogFolderRelativePath.js";
 export * from "./ChangelogLayout.js";
 export * from "./CheckConfig.js";
 export * from "./CheckRuleSeverity.js";