feat(packages/config,packages/core): add root section type for flat sidebar grouping

.changeset/feat-root-section.md

@@ -0,0 +1,5 @@
+---
+'@zpress/core': minor
+---
+
+feat: support root sections that promote children to top-level sidebar and nav

examples/kitchen-sink/docs/references/api/authentication.md

@@ -0,0 +1,21 @@
+---
+title: Authentication
+---
+
+# Authentication
+
+All API requests require a Bearer token in the `Authorization` header.
+
+## Obtaining a Token
+
+Send a `POST` request to `/auth/token` with your client credentials:
+
+```bash
+curl -X POST https://api.acme.com/auth/token \
+  -H "Content-Type: application/json" \
+  -d '{"client_id": "...", "client_secret": "..."}'
+```
+
+## Token Refresh
+
+Tokens expire after 1 hour. Use the refresh token to obtain a new access token without re-authenticating.

examples/kitchen-sink/docs/references/api/endpoints.md

@@ -0,0 +1,23 @@
+---
+title: Endpoints
+---
+
+# Endpoints
+
+## Users
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/users` | List all users |
+| `GET` | `/users/:id` | Get user by ID |
+| `POST` | `/users` | Create a user |
+| `PATCH` | `/users/:id` | Update a user |
+| `DELETE` | `/users/:id` | Delete a user |
+
+## Projects
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/projects` | List all projects |
+| `GET` | `/projects/:id` | Get project by ID |
+| `POST` | `/projects` | Create a project |

examples/kitchen-sink/docs/references/api/errors.md

@@ -0,0 +1,16 @@
+---
+title: Error Codes
+---
+
+# Error Codes
+
+All errors return a JSON body with `code`, `message`, and optional `details`.
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| `auth_required` | 401 | Missing or invalid authentication |
+| `forbidden` | 403 | Insufficient permissions |
+| `not_found` | 404 | Resource does not exist |
+| `validation_error` | 422 | Request body failed validation |
+| `rate_limited` | 429 | Too many requests |
+| `internal_error` | 500 | Unexpected server error |

examples/kitchen-sink/docs/references/cli/commands.md

@@ -0,0 +1,29 @@
+---
+title: Commands
+---
+
+# Commands
+
+## `acme init`
+
+Initialize a new Acme project in the current directory.
+
+```bash
+acme init [--template <name>]
+```
+
+## `acme deploy`
+
+Deploy the current project to production.
+
+```bash
+acme deploy [--env <environment>] [--dry-run]
+```
+
+## `acme status`
+
+Show the current deployment status.
+
+```bash
+acme status [--json]
+```

examples/kitchen-sink/docs/references/cli/configuration.md

@@ -0,0 +1,27 @@
+---
+title: Configuration
+---
+
+# Configuration
+
+The CLI reads configuration from `acme.config.ts` in the project root.
+
+```ts
+export default {
+  org: 'acme',
+  project: 'web',
+  region: 'us-east-1',
+  deploy: {
+    strategy: 'rolling',
+    timeout: 300,
+  },
+}
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ACME_TOKEN` | API authentication token | — |
+| `ACME_ORG` | Organization slug | from config |
+| `ACME_LOG_LEVEL` | Log verbosity (`debug`, `info`, `warn`, `error`) | `info` |

examples/kitchen-sink/docs/references/cli/installation.md

@@ -0,0 +1,22 @@
+---
+title: Installation
+---
+
+# Installation
+
+Install the Acme CLI globally:
+
+```bash
+npm install -g @acme/cli
+```
+
+Verify the installation:
+
+```bash
+acme --version
+```
+
+## System Requirements
+
+- Node.js 18 or later
+- macOS, Linux, or Windows (WSL)

examples/kitchen-sink/zpress.config.ts

@@ -141,6 +141,26 @@ export default defineConfig({
         },
       ],
     },
+    {
+      title: 'Reference',
+      icon: 'pixelarticons:book-open',
+      path: '/references',
+      root: true,
+      items: [
+        {
+          title: 'API',
+          path: '/references/api',
+          include: 'docs/references/api/*.md',
+          sort: 'alpha',
+        },
+        {
+          title: 'CLI',
+          path: '/references/cli',
+          include: 'docs/references/cli/*.md',
+          sort: 'alpha',
+        },
+      ],
+    },
   ],
   sidebar: {
     above: [

packages/config/schemas/schema.json

@@ -98,30 +98,7 @@
             "type": "object",
             "properties": {
               "title": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "object",
-                    "properties": {
-                      "from": {
-                        "type": "string",
-                        "enum": [
-                          "auto",
-                          "filename",
-                          "heading",
-                          "frontmatter"
-                        ]
-                      },
-                      "transform": {}
-                    },
-                    "required": [
-                      "from"
-                    ],
-                    "additionalProperties": false
-                  }
-                ]
+                "type": "string"
               },
               "icon": {
                 "anyOf": [
@@ -193,7 +170,30 @@
                   "type": "object",
                   "properties": {
                     "title": {
-                      "$ref": "#/definitions/ZpressConfig/properties/apps/items/properties/title"
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "from": {
+                              "type": "string",
+                              "enum": [
+                                "auto",
+                                "filename",
+                                "heading",
+                                "frontmatter"
+                              ]
+                            },
+                            "transform": {}
+                          },
+                          "required": [
+                            "from"
+                          ],
+                          "additionalProperties": false
+                        }
+                      ]
                     },
                     "description": {
                       "type": "string"
@@ -392,6 +392,9 @@
                     },
                     "standalone": {
                       "type": "boolean"
+                    },
+                    "root": {
+                      "type": "boolean"
                     }
                   },
                   "required": [
@@ -478,7 +481,7 @@
             "type": "object",
             "properties": {
               "title": {
-                "$ref": "#/definitions/ZpressConfig/properties/apps/items/properties/title"
+                "type": "string"
               },
               "description": {
                 "type": "string"
@@ -511,7 +514,7 @@
             "type": "object",
             "properties": {
               "title": {
-                "$ref": "#/definitions/ZpressConfig/properties/apps/items/properties/title"
+                "type": "string"
               },
               "description": {
                 "type": "string"

packages/config/src/schema.ts

@@ -116,6 +116,7 @@ const entrySchema: z.ZodType<Section> = z.lazy(() =>
       icon: iconConfigSchema.optional(),
       card: cardConfigSchema.optional(),
       standalone: z.boolean().optional(),
+      root: z.boolean().optional(),
     })
     .strict()
 )
@@ -131,7 +132,7 @@ const openapiConfigSchema = z
 
 const workspaceItemSchema = z
   .object({
-    title: titleConfigSchema,
+    title: z.string(),
     icon: iconConfigSchema.optional(),
     description: z.string(),
     tags: z.array(z.string()).optional(),
@@ -150,7 +151,7 @@ const workspaceItemSchema = z
 
 const workspaceGroupSchema = z
   .object({
-    title: titleConfigSchema,
+    title: z.string(),
     description: z.string().optional(),
     icon: iconIdSchema,
     items: z.array(workspaceItemSchema).min(1),
@@ -160,7 +161,7 @@ const workspaceGroupSchema = z
 
 const featureSchema = z
   .object({
-    title: titleConfigSchema,
+    title: z.string(),
     description: z.string(),
     link: z.string().optional(),
     icon: iconConfigSchema.optional(),

packages/config/src/types.ts

@@ -264,6 +264,7 @@ export interface Section {
   readonly icon?: IconConfig
   readonly card?: CardConfig
   readonly standalone?: boolean
+  readonly root?: boolean
 }
 
 /**
@@ -285,7 +286,7 @@ export interface Section {
  * ```
  */
 export interface Workspace {
-  readonly title: TitleConfig
+  readonly title: string
   readonly icon?: IconConfig
   readonly description: string
   readonly tags?: readonly string[]
@@ -324,7 +325,7 @@ export interface Workspace {
  * ```
  */
 export interface WorkspaceCategory {
-  readonly title: TitleConfig
+  readonly title: string
   readonly description?: string
   readonly icon: IconId
   readonly items: readonly Workspace[]
@@ -395,7 +396,7 @@ export interface OpenAPIConfig {
  * ```
  */
 export interface Feature {
-  readonly title: TitleConfig
+  readonly title: string
   readonly description: string
   readonly link?: string
   readonly icon?: IconConfig

packages/core/src/define-config.ts

@@ -139,16 +139,6 @@ function validateWorkspaces(items: readonly Workspace[]): ConfigResult<true> {
         }
       }
 
-      if (typeof item.title !== 'string') {
-        return {
-          error: configError(
-            'invalid_field',
-            `Workspace "${String(item.title)}": "title" must be a string (TitleConfig not supported on Workspace)`
-          ),
-          seen: acc.seen,
-        }
-      }
-
       if (!item.description) {
         return {
           error: configError(
@@ -209,13 +199,6 @@ function validateWorkspaceCategories(categories: readonly WorkspaceCategory[]):
       return configError('missing_field', 'WorkspaceCategory: "title" is required')
     }
 
-    if (typeof category.title !== 'string') {
-      return configError(
-        'invalid_field',
-        `WorkspaceCategory: "title" must be a string (TitleConfig not supported on WorkspaceCategory)`
-      )
-    }
-
     if (!category.icon) {
       return configError(
         'missing_field',
@@ -393,17 +376,6 @@ function validateFeature(feature: Feature): ConfigError | null {
     return configError('missing_field', 'Feature: "title" is required')
   }
 
-  const titleStr = match(feature.title)
-    .with(P.string, (t) => t)
-    .otherwise(() => 'Feature')
-
-  if (typeof feature.title !== 'string') {
-    return configError(
-      'invalid_field',
-      `Feature "${titleStr}": "title" must be a string (TitleConfig not supported on Feature)`
-    )
-  }
-
   if (!feature.description) {
     return configError('missing_field', `Feature "${feature.title}": "description" is required`)
   }

packages/core/src/sync/index.ts

@@ -389,7 +389,7 @@ function concatPage(pages: readonly PageData[], page: PageData | undefined): Pag
  * @returns Array of standalone scope path strings
  */
 function collectStandaloneScopePaths(entries: readonly ResolvedEntry[]): readonly string[] {
-  return entries.filter((e) => e.standalone && e.link).map((e) => e.link as string)
+  return entries.filter((e) => (e.standalone || e.root) && e.link).map((e) => e.link as string)
 }
 
 /**