use a somewhat easier format

packages/cli/configuration/fern/definition/docs.yml

@@ -442,24 +442,22 @@ types:
           Keyed by subpackage ID, this object allows you to group endpoints and pages together.
       - PageConfiguration
       - LinkConfiguration
-      - ApiPackageConfiguration
+      - ApiReferenceSectionConfiguration
+      - ApiReferencePackageConfiguration
 
   SubpackageOrSubpackages:
     discriminated: false
     union:
       - string
       - list<string>
 
-  ApiPackageConfiguration:
+  ApiReferenceSectionConfiguration:
     properties:
-      package:
+      section:
         type: string
         docs: |
           The title of the api package that will be displayed in the sidebar.
-
-          Alternatively, `subpackage` is unset, and this is a Subpackage ID. The title of this section will be inherited from the subpackage.
-          Any endpoints that are not explicitly defined within the contents of this object will be implicitly included.
-      subpackage:
+      package:
         type: optional<SubpackageOrSubpackages>
         docs: If `subpackage` is set, this section will inherit the endpoints from the specified subpackage(s).
       summary:
@@ -472,6 +470,19 @@ types:
       hidden: optional<boolean>
       skip-slug: optional<boolean>
 
+  ApiReferencePackageConfiguration:
+    properties:
+      package: string
+      summary:
+        type: optional<string>
+        docs: |
+          Relative path to the markdown file. This summary is displayed at the top of the API section.
+      contents: ApiNavigationItems
+      slug: optional<string>
+      icon: optional<string>
+      hidden: optional<boolean>
+      skip-slug: optional<boolean>
+
   ApiNavigationItems:
     type: list<ApiNavigationItem>
     examples:

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

@@ -213,10 +213,20 @@ export declare namespace DocsNavigationItem {
 }
 
 export declare namespace ParsedApiNavigationItem {
+    export interface Section {
+        type: "section";
+        section: string; // title
+        subpackages: string[]; // subpackage IDs
+        summaryAbsolutePath: AbsoluteFilePath | undefined;
+        contents: ParsedApiNavigationItem[];
+        slug: string | undefined;
+        hidden: boolean | undefined;
+        icon: string | undefined;
+        skipUrlSlug: boolean | undefined;
+    }
     export interface Package {
         type: "package";
-        package: string; // title or subpackage ID
-        subpackages: string[]; // subpackage IDs
+        package: string; // subpackage ID
         summaryAbsolutePath: AbsoluteFilePath | undefined;
         contents: ParsedApiNavigationItem[];
         slug: string | undefined;
@@ -233,6 +243,7 @@ export declare namespace ParsedApiNavigationItem {
 
 export type ParsedApiNavigationItem =
     | ParsedApiNavigationItem.Item
+    | ParsedApiNavigationItem.Section
     | ParsedApiNavigationItem.Package
     | DocsNavigationItem.Page
     | DocsNavigationItem.Link;

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

@@ -587,12 +587,25 @@ function parseApiNavigationItem(
                 icon: item.icon
             }
         ];
-    } else if (isRawApiPackageConfiguration(item)) {
+    } else if (isRawApiRefSectionConfiguration(item)) {
+        return [
+            {
+                type: "section",
+                section: item.section,
+                subpackages: typeof item.package === "string" ? [item.package] : item.package ?? [],
+                summaryAbsolutePath: resolveFilepath(item.summary, absolutePathToConfig),
+                contents: item.contents.flatMap((value) => parseApiNavigationItem(value, absolutePathToConfig)),
+                slug: item.slug,
+                hidden: item.hidden,
+                skipUrlSlug: item.skipSlug,
+                icon: item.icon
+            }
+        ];
+    } else if (isRawApiRefPackageConfiguration(item)) {
         return [
             {
                 type: "package",
                 package: item.package,
-                subpackages: typeof item.subpackage === "string" ? [item.subpackage] : item.subpackage ?? [],
                 summaryAbsolutePath: resolveFilepath(item.summary, absolutePathToConfig),
                 contents: item.contents.flatMap((value) => parseApiNavigationItem(value, absolutePathToConfig)),
                 slug: item.slug,
@@ -607,7 +620,6 @@ function parseApiNavigationItem(
         ([key, values]): ParsedApiNavigationItem.Package => ({
             type: "package",
             package: key,
-            subpackages: [],
             summaryAbsolutePath: undefined,
             contents: values.flatMap((value) => parseApiNavigationItem(value, absolutePathToConfig)),
             hidden: false,
@@ -650,8 +662,14 @@ function isRawLinkConfig(item: unknown): item is RawDocs.LinkConfiguration {
     return isPlainObject(item) && typeof item.link === "string" && typeof item.href === "string";
 }
 
-function isRawApiPackageConfiguration(item: unknown): item is RawDocs.ApiPackageConfiguration {
-    return isPlainObject(item) && typeof item.package === "string" && Array.isArray(item.contents);
+function isRawApiRefSectionConfiguration(item: unknown): item is RawDocs.ApiReferenceSectionConfiguration {
+    return isPlainObject(item) && typeof item.section === "string" && Array.isArray(item.contents);
+}
+
+function isRawApiRefPackageConfiguration(item: unknown): item is RawDocs.ApiReferencePackageConfiguration {
+    return (
+        isPlainObject(item) && item.section == null && typeof item.package === "string" && Array.isArray(item.contents)
+    );
 }
 
 export function resolveFilepath(unresolvedFilepath: string, absolutePath: AbsoluteFilePath): AbsoluteFilePath;

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

@@ -19,4 +19,5 @@ export type ApiNavigationItem =
     | Record<string, FernDocsConfig.ApiNavigationItems>
     | FernDocsConfig.PageConfiguration
     | FernDocsConfig.LinkConfiguration
-    | FernDocsConfig.ApiPackageConfiguration;
+    | FernDocsConfig.ApiReferenceSectionConfiguration
+    | FernDocsConfig.ApiReferencePackageConfiguration;

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

@@ -0,0 +1,16 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as FernDocsConfig from "../../..";
+
+export interface ApiReferencePackageConfiguration {
+    package: string;
+    /** Relative path to the markdown file. This summary is displayed at the top of the API section. */
+    summary?: string;
+    contents: FernDocsConfig.ApiNavigationItems;
+    slug?: string;
+    icon?: string;
+    hidden?: boolean;
+    skipSlug?: boolean;
+}

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/ApiPackageConfiguration.ts → packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/ApiReferenceSectionConfiguration.ts

@@ -4,16 +4,11 @@
 
 import * as FernDocsConfig from "../../..";
 
-export interface ApiPackageConfiguration {
-    /**
-     * The title of the api package that will be displayed in the sidebar.
-     *
-     * Alternatively, `subpackage` is unset, and this is a Subpackage ID. The title of this section will be inherited from the subpackage.
-     * Any endpoints that are not explicitly defined within the contents of this object will be implicitly included.
-     */
-    package: string;
+export interface ApiReferenceSectionConfiguration {
+    /** The title of the api package that will be displayed in the sidebar. */
+    section: string;
     /** If `subpackage` is set, this section will inherit the endpoints from the specified subpackage(s). */
-    subpackage?: FernDocsConfig.SubpackageOrSubpackages;
+    package?: FernDocsConfig.SubpackageOrSubpackages;
     /** Relative path to the markdown file. This summary is displayed at the top of the API section. */
     summary?: string;
     contents: FernDocsConfig.ApiNavigationItems;

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

@@ -32,7 +32,8 @@ export * from "./SectionConfiguration";
 export * from "./ApiSectionConfiguration";
 export * from "./ApiNavigationItem";
 export * from "./SubpackageOrSubpackages";
-export * from "./ApiPackageConfiguration";
+export * from "./ApiReferenceSectionConfiguration";
+export * from "./ApiReferencePackageConfiguration";
 export * from "./ApiNavigationItems";
 export * from "./LinkConfiguration";
 export * from "./VersionedSnippetLanguageConfiguration";

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

@@ -17,7 +17,8 @@ export const ApiNavigationItem: core.serialization.Schema<
     ),
     core.serialization.lazyObject(async () => (await import("../../..")).PageConfiguration),
     core.serialization.lazyObject(async () => (await import("../../..")).LinkConfiguration),
-    core.serialization.lazyObject(async () => (await import("../../..")).ApiPackageConfiguration),
+    core.serialization.lazyObject(async () => (await import("../../..")).ApiReferenceSectionConfiguration),
+    core.serialization.lazyObject(async () => (await import("../../..")).ApiReferencePackageConfiguration),
 ]);
 
 export declare namespace ApiNavigationItem {
@@ -26,5 +27,6 @@ export declare namespace ApiNavigationItem {
         | Record<string, serializers.ApiNavigationItems.Raw>
         | serializers.PageConfiguration.Raw
         | serializers.LinkConfiguration.Raw
-        | serializers.ApiPackageConfiguration.Raw;
+        | serializers.ApiReferenceSectionConfiguration.Raw
+        | serializers.ApiReferencePackageConfiguration.Raw;
 }

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/ApiPackageConfiguration.ts → packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/ApiReferencePackageConfiguration.ts

@@ -6,12 +6,11 @@ import * as serializers from "../../..";
 import * as FernDocsConfig from "../../../../api";
 import * as core from "../../../../core";
 
-export const ApiPackageConfiguration: core.serialization.ObjectSchema<
-    serializers.ApiPackageConfiguration.Raw,
-    FernDocsConfig.ApiPackageConfiguration
+export const ApiReferencePackageConfiguration: core.serialization.ObjectSchema<
+    serializers.ApiReferencePackageConfiguration.Raw,
+    FernDocsConfig.ApiReferencePackageConfiguration
 > = core.serialization.object({
     package: core.serialization.string(),
-    subpackage: core.serialization.lazy(async () => (await import("../../..")).SubpackageOrSubpackages).optional(),
     summary: core.serialization.string().optional(),
     contents: core.serialization.lazy(async () => (await import("../../..")).ApiNavigationItems),
     slug: core.serialization.string().optional(),
@@ -20,10 +19,9 @@ export const ApiPackageConfiguration: core.serialization.ObjectSchema<
     skipSlug: core.serialization.property("skip-slug", core.serialization.boolean().optional()),
 });
 
-export declare namespace ApiPackageConfiguration {
+export declare namespace ApiReferencePackageConfiguration {
     interface Raw {
         package: string;
-        subpackage?: serializers.SubpackageOrSubpackages.Raw | null;
         summary?: string | null;
         contents: serializers.ApiNavigationItems.Raw;
         slug?: string | null;

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

@@ -0,0 +1,34 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as serializers from "../../..";
+import * as FernDocsConfig from "../../../../api";
+import * as core from "../../../../core";
+
+export const ApiReferenceSectionConfiguration: core.serialization.ObjectSchema<
+    serializers.ApiReferenceSectionConfiguration.Raw,
+    FernDocsConfig.ApiReferenceSectionConfiguration
+> = core.serialization.object({
+    section: core.serialization.string(),
+    package: core.serialization.lazy(async () => (await import("../../..")).SubpackageOrSubpackages).optional(),
+    summary: core.serialization.string().optional(),
+    contents: core.serialization.lazy(async () => (await import("../../..")).ApiNavigationItems),
+    slug: core.serialization.string().optional(),
+    icon: core.serialization.string().optional(),
+    hidden: core.serialization.boolean().optional(),
+    skipSlug: core.serialization.property("skip-slug", core.serialization.boolean().optional()),
+});
+
+export declare namespace ApiReferenceSectionConfiguration {
+    interface Raw {
+        section: string;
+        package?: serializers.SubpackageOrSubpackages.Raw | null;
+        summary?: string | null;
+        contents: serializers.ApiNavigationItems.Raw;
+        slug?: string | null;
+        icon?: string | null;
+        hidden?: boolean | null;
+        "skip-slug"?: boolean | null;
+    }
+}

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

@@ -32,7 +32,8 @@ export * from "./SectionConfiguration";
 export * from "./ApiSectionConfiguration";
 export * from "./ApiNavigationItem";
 export * from "./SubpackageOrSubpackages";
-export * from "./ApiPackageConfiguration";
+export * from "./ApiReferenceSectionConfiguration";
+export * from "./ApiReferencePackageConfiguration";
 export * from "./ApiNavigationItems";
 export * from "./LinkConfiguration";
 export * from "./VersionedSnippetLanguageConfiguration";