Skip to content

configuration.cn.mdx

Latest commit

 

History

History
118 lines (93 loc) · 3.17 KB

configuration.cn.mdx

File metadata and controls

118 lines (93 loc) · 3.17 KB
title 配置
description 了解如何通过 JSON 文件自定义您的 ObjectDocs 站点。

import { Settings, Palette, Navigation, Layout } from 'lucide-react';

配置

ObjectDocs 遵循 配置即代码 (Configuration as Code) 的原则。所有的站点设置都通过 JSON 文件定义，易于版本控制和协作。

全局配置

docs.site.json

主配置文件位于 content/docs.site.json。该文件控制整个文档站点的全局设置，并在构建和开发期间自动同步到 content/.objectdocs。

{
  "branding": {
    "name": "ObjectDocs",
    "logo": {
       "light": "/logo.svg",
       "dark": "/logo-dark.svg"
    }
  },
  "links": [
    { "text": "Guide", "url": "/docs" },
    { "text": "GitHub", "url": "https://github.com/objectstack-ai", "icon": "github" }
  ],
  "i18n": {
    "defaultLanguage": "en",
    "languages": ["en", "zh-CN", "ja", "es", "fr", "de", "ko", "ru", "pt", "ar", "hi", "it", "tr", "vi"]
  }
}

工作原理:

  • 存储在 content/docs.site.json (你的内容目录)
  • 在每次 build/dev 命令前复制到 content/.objectdocs
  • 开发时监听 - 变化会触发服务器自动重启
  • 支持 14 种语言的国际化

配置项说明

属性 类型 说明
branding.name string 站点名称，显示在导航栏左侧。
branding.logo object 站点 Logo 图片路径，支持亮色/暗色模式。
links array 顶部导航栏链接列表。
i18n.defaultLanguage string 默认语言代码 (例如, "en", "zh-CN")。
i18n.languages array 支持的语言 (14种可选: en, zh-CN, ja, es, fr, de, ko, ru, pt, ar, hi, it, tr, vi)。

开发功能:

  • 配置更改在 npm run dev 期间自动检测
  • docs.site.json 被修改时服务器会重启
  • 配置更新无需手动重启

目录与导航配置

meta.json

每个文档目录下都可以放置一个 meta.json 文件，用于控制该目录下的侧边栏结构和页面顺序。

示例结构：

content/docs/
├── meta.json          # 根目录配置
├── index.mdx
└── getting-started/
    ├── meta.json      # 子目录配置
    ├── index.mdx
    └── configuration.mdx

content/docs/meta.json:

{
  "title": "Documentation",
  "pages": [
    "index",
    "getting-started",
    "components"
  ]
}

content/docs/getting-started/meta.json:

{
  "title": "快速开始",
  "pages": [
    "index",            // 对应 index.mdx (快速开始)
    "architecture",     // 对应 architecture.mdx (架构)
    "configuration"     // 对应 configuration.mdx (配置)
  ]
}

如果不使用 meta.json

如果没有 meta.json，ObjectDocs 会按字母顺序自动列出该目录下的所有 .mdx 文件。对于正式文档，我们强烈建议使用 meta.json 以确保顺序可控。

页面配置 (Frontmatter)

每个 MDX 文件的顶部都可以包含 Frontmatter 元数据：

---
title: 页面标题
description: 页面描述（用于 SEO 和搜索预览）
icon: Rocket  # 可选：页面图标名称
full: false   # 可选：是否隐藏右侧目录 (Table of Contents)
---