【免费下载链接】blumeThe open-source docs framework for humans and agents.项目地址https://gitcode.com/gh_mirrors/blum/blume点击查看免费下载Blume 是一个面向人类与 AI Agent 的开源文档框架docs framework它把你仓库里的 Markdown / MDX 文件直接变成带侧边栏、目录、搜索和 SEO 元数据的文档站点。本指南面向新手系统讲解在 Blume 中编写内容的三大支柱Frontmatter 页面元数据、Markdown/MDX 语法特性以及用于跨页面复用内容的Includes 机制帮助你从写第一页到高效维护一套文档全程无坑。一、一个文件就是一个页面Blume 内容组织方式在 Blume 中文档就是内容根目录默认docs/下的一堆文件每个文件自动映射为一个页面路由无需任何清单文件。文件类型只有两种.md— 纯 Markdown适合文字为主的页面.mdx— 在 Markdown 基础上支持 JSX 组件、:::指令、数学公式等高级特性文件路径即路由嵌套文件夹变成嵌套路径文件生成的路由docs/index.mdx/docs/quickstart.mdx/quickstartdocs/guides/theming.mdx/guides/themingdocs/guides/index.mdx/guides三个新手友好的小技巧数字前缀排序01-introduction.mdx会按01排序且 URL 中不含前缀随时可调整顺序而不破坏链接草稿页Frontmatter 里加draft: trueblume dev可预览、blume build则跳过内容类型type: blog或type: changelog的页面会自动生成 RSS Feed 官方文档中对应的内容组织说明见 pages.mdx。二、Frontmatter 详解一页元数据搞定标题、SEO 与侧边栏Frontmatter 是页面顶部的 YAML 块所有字段都是可选的。一份典型页面长这样--- title: 安装指南 description: 三步完成 Blume 安装与初始化。 type: doc sidebar: label: Install order: 2 badge: New ---核心字段速查表字段作用title/description页面标题与摘要同时用于 SEOtype内容类型默认docblog/changelog会驱动 Feeddate/authors博客与更新日志的发布日期和作者draft: true排除在生产构建之外deprecated: true侧边栏显示已弃用徽标hidden: true从侧边栏、搜索、sitemap 中隐藏noindex: true禁止搜索引擎收录lastModified固定最后更新日期related页面底部推荐的相关页面卡片最多 10 个页面布局模式mode控制页面在内容之外显示什么共 5 种default完整布局、wide宽表/图表页、center发布公告、frame嵌入工具页、custom纯自定义落地页仅保留顶栏。进阶SEO、搜索与自定义字段seo:子对象可覆盖标题、描述、社交分享图、canonical 链接search:子对象支持tags、keywords和boost排序加权自定义字段任何未声明的键都会让构建失败这是特性不是缺陷——拼写错误会被立刻抓住。团队自有元数据可通过frontmatter.extend用 Zod 等 schema 声明还可以按type给特定内容类型强制字段⚠️常见坑YAML 中含冒号空格的值必须加引号例如description: 安装最简单的姿势否则 Blume 会报BLUME_FRONTMATTER_INVALID错误并指出文件与行号。 完整字段参考见 frontmatter.mdx解析逻辑源码在 frontmatter.ts。三、Markdown 语法开箱即用的特性清单Blume 渲染标准的 GitHub 风格 Markdown另加一批零配置的增强特性无需任何 import 或配置标题与目录每个##/###标题自动生成锚点链接悬停显示#可一键复制永久链接并进入页面右侧本页目录自定义锚点标题末尾追加[#custom-id]即使日后改标题文字链接依然有效代码块增强最实用的部分import { defineConfig } from blume; export default defineConfig({ title: My docs, });一行围栏语法可以叠加多个选项互不冲突选项效果lineNumbers显示行号wrap长行自动换行不再横向滚动expandable长代码折叠点击Show more展开{1,4-5}按行号高亮twoslashTypeScript 代码显示真实类型悬停可查还支持 GitHub 风格的行内注释标注// [!code highlight]高亮、[!code ]/[!code --]绿红 diff、[!code warning]警示——注释本身不会出现在渲染结果中复制粘贴依然干净。Callout 提示块与 GitHub Alerts:::tip[小提示] 在 blume.config.ts 中设置 deployment.sitesitemap 就能使用绝对 URL。 :::支持note/info/tip/success/warning/danger六种类型嵌套时用更长的围栏::::。GitHub 的 [!TIP]语法也会被自动识别为 Callout。其他值得一提的特性表格标准 GFM 表格列对齐用:控制无表头表格可直接写键值对键盘按键kbd⌘/kbd kbdK/kbd渲染为带边框的按键徽标上标/下标E mc^2^、H~2~O数学公式$$...$$由 KaTeX 自动渲染写了才加载不写则零成本安装命令标签页package-install围栏自动把一条npm i blume展开为 npm / pnpm / yarn / bun 等标签页Mermaid 图表mermaid围栏直接渲染流程图、时序图等跟随站点深浅色主题智能标点直引号自动变弯引号--变短破折号图片优化相对路径引用的本地图片在构建时自动压缩为 WebP 并写入固有宽高点击可放大 每项特性都有实时预览 源码的官方参考页 syntax.mdx组件库文档见 components.mdx。四、Includes 机制一次编写处处复用文档写到一定规模你一定会遇到这段前置说明要在 5 个页面出现的问题。Blume 的include就是为此设计的构建期内联机制。基本用法独占一行写一条 include 语句构建时把目标文件的内容缝进当前页面——就像直接写在页面里一样标题会进入本页目录正文会被搜索索引也会出现在页面的 Markdown 镜像中include./_snippets/prerequisites.mdx/include include/_snippets/prerequisites.mdx/include路径以当前文件为基准解析以/开头则从内容根目录解析深层页面引用公共片段再也不用写../../..。下划线 Partial 约定文件名或文件夹名以下划线开头的文件会被排除在路由、导航、搜索和 sitemap 之外——这正好是共享片段的天然归属地docs/ _snippets/ prerequisites.mdx cli-flags.md guides/ quickstart.mdx ← include../_snippets/prerequisites.mdx/include index.mdxPartial 就是一个普通的 Markdown/MDX 文件Callout、代码块、组件、公式全部照常渲染。它的 frontmatter 会被剥离以宿主页面为准但它内部可以嵌套 include 其他片段循环引用会被检测并报错。blume dev运行时编辑一个 partial 会自动刷新所有引用它的页面。用 Props 让一个片段服务多个页面给 include 加属性即可传值片段内用{{name}}读取升级到 **{{plan}}** 套餐后即可使用 {{feature}}。include planEnterprise featureSSO ./_snippets/upgrade.mdx /include顺带 include 代码文件目标不是.md/.mdx时会被自动渲染为带语法高亮的代码围栏语言从扩展名推断可用lang覆盖、meta传标题include./examples/config.ts/include include metatitleconfig.ts./examples/config.ts/includeIncludes 常见诊断一览诊断码含义BLUME_INCLUDE_NOT_FOUND目标文件不存在BLUME_INCLUDE_CYCLE检测到循环引用BLUME_INCLUDE_OUTSIDE_ROOT目标越出内容根目录BLUME_INCLUDE_MALFORMEDinclude 语句格式无法解析 完整机制说明见 includes.mdx一个可运行的示例片段见 include-demo.mdx核心实现源码在 includes.ts。五、附赠技巧站点级变量 {{name}}版本号、API 地址这类全站值定义一次即可处处引用——在blume.config.ts里声明variables页面中写{{version}}就会替换。替换发生在任何读取页面之前所以渲染结果、搜索索引、Markdown 镜像里看到的都是最终值。正文中引用了一个未定义的变量会直接报构建错误BLUME_UNDEFINED_VARIABLE拼写错误到不了读者眼前。 详见 variables.mdx。六、新手检查清单✅ 纯文字页用.md需要组件/指令/公式的页用.mdx✅ 每页写好titledescriptionSEO 与分享卡片就齐了✅ 排序用数字前缀、分组用括号文件夹(internal)/URL 保持干净✅ 含冒号的 YAML 值加引号构建失败先看诊断码提示的文件与行号✅ 公共内容抽到_snippets/下用include引入并传 props✅ 用blume validate/blume check在提交前检查死链与语法问题掌握 Frontmatter、Markdown 语法与 Includes 这三件套你就能在 Blume 中高效地编写、组织和复用文档内容——剩下的只需要持续写下去。赞分享【免费下载链接】blumeThe open-source docs framework for humans and agents.项目地址https://gitcode.com/gh_mirrors/blum/blume点击查看免费下载相关推荐Slidev Block Frontmatter 详解以 YAML 代码块编写单页 Frontmatter获得语法高亮与格式化支持Slidev Block Frontmatter 详解以 YAML 代码块编写单页 Frontmatter获得语法高亮与格式化支持 在 Slidev面向开前端开发工具Slidev Markdown 语法全指南分页、Frontmatter、代码块与图表创作Slidev Markdown 语法全指南分页、Frontmatter、代码块与图表创作 Slidevslide dev读作 /slaɪdɪv/ 以前端开发工具Pelican 内容写作完全指南文章、页面、元数据、内部链接与语法高亮Pelican 内容写作完全指南文章、页面、元数据、内部链接与语法高亮 Pelican 是一个基于 Python 的静态站点生成器同时支持 Markdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/10 23:45:36 · 阅读 1.2k Blume内容编写完全指南：Frontmatter、Markdown语法与页面Includes机制详解
【免费下载链接】blumeThe open-source docs framework for humans and agents.项目地址https://gitcode.com/gh_mirrors/blum/blume点击查看免费下载Blume 是一个面向人类与 AI Agent 的开源文档框架docs framework它把你仓库里的 Markdown / MDX 文件直接变成带侧边栏、目录、搜索和 SEO 元数据的文档站点。本指南面向新手系统讲解在 Blume 中编写内容的三大支柱Frontmatter 页面元数据、Markdown/MDX 语法特性以及用于跨页面复用内容的Includes 机制帮助你从写第一页到高效维护一套文档全程无坑。一、一个文件就是一个页面Blume 内容组织方式在 Blume 中文档就是内容根目录默认docs/下的一堆文件每个文件自动映射为一个页面路由无需任何清单文件。文件类型只有两种.md— 纯 Markdown适合文字为主的页面.mdx— 在 Markdown 基础上支持 JSX 组件、:::指令、数学公式等高级特性文件路径即路由嵌套文件夹变成嵌套路径文件生成的路由docs/index.mdx/docs/quickstart.mdx/quickstartdocs/guides/theming.mdx/guides/themingdocs/guides/index.mdx/guides三个新手友好的小技巧数字前缀排序01-introduction.mdx会按01排序且 URL 中不含前缀随时可调整顺序而不破坏链接草稿页Frontmatter 里加draft: trueblume dev可预览、blume build则跳过内容类型type: blog或type: changelog的页面会自动生成 RSS Feed 官方文档中对应的内容组织说明见 pages.mdx。二、Frontmatter 详解一页元数据搞定标题、SEO 与侧边栏Frontmatter 是页面顶部的 YAML 块所有字段都是可选的。一份典型页面长这样--- title: 安装指南 description: 三步完成 Blume 安装与初始化。 type: doc sidebar: label: Install order: 2 badge: New ---核心字段速查表字段作用title/description页面标题与摘要同时用于 SEOtype内容类型默认docblog/changelog会驱动 Feeddate/authors博客与更新日志的发布日期和作者draft: true排除在生产构建之外deprecated: true侧边栏显示已弃用徽标hidden: true从侧边栏、搜索、sitemap 中隐藏noindex: true禁止搜索引擎收录lastModified固定最后更新日期related页面底部推荐的相关页面卡片最多 10 个页面布局模式mode控制页面在内容之外显示什么共 5 种default完整布局、wide宽表/图表页、center发布公告、frame嵌入工具页、custom纯自定义落地页仅保留顶栏。进阶SEO、搜索与自定义字段seo:子对象可覆盖标题、描述、社交分享图、canonical 链接search:子对象支持tags、keywords和boost排序加权自定义字段任何未声明的键都会让构建失败这是特性不是缺陷——拼写错误会被立刻抓住。团队自有元数据可通过frontmatter.extend用 Zod 等 schema 声明还可以按type给特定内容类型强制字段⚠️常见坑YAML 中含冒号空格的值必须加引号例如description: 安装最简单的姿势否则 Blume 会报BLUME_FRONTMATTER_INVALID错误并指出文件与行号。 完整字段参考见 frontmatter.mdx解析逻辑源码在 frontmatter.ts。三、Markdown 语法开箱即用的特性清单Blume 渲染标准的 GitHub 风格 Markdown另加一批零配置的增强特性无需任何 import 或配置标题与目录每个##/###标题自动生成锚点链接悬停显示#可一键复制永久链接并进入页面右侧本页目录自定义锚点标题末尾追加[#custom-id]即使日后改标题文字链接依然有效代码块增强最实用的部分import { defineConfig } from blume; export default defineConfig({ title: My docs, });一行围栏语法可以叠加多个选项互不冲突选项效果lineNumbers显示行号wrap长行自动换行不再横向滚动expandable长代码折叠点击Show more展开{1,4-5}按行号高亮twoslashTypeScript 代码显示真实类型悬停可查还支持 GitHub 风格的行内注释标注// [!code highlight]高亮、[!code ]/[!code --]绿红 diff、[!code warning]警示——注释本身不会出现在渲染结果中复制粘贴依然干净。Callout 提示块与 GitHub Alerts:::tip[小提示] 在 blume.config.ts 中设置 deployment.sitesitemap 就能使用绝对 URL。 :::支持note/info/tip/success/warning/danger六种类型嵌套时用更长的围栏::::。GitHub 的 [!TIP]语法也会被自动识别为 Callout。其他值得一提的特性表格标准 GFM 表格列对齐用:控制无表头表格可直接写键值对键盘按键kbd⌘/kbd kbdK/kbd渲染为带边框的按键徽标上标/下标E mc^2^、H~2~O数学公式$$...$$由 KaTeX 自动渲染写了才加载不写则零成本安装命令标签页package-install围栏自动把一条npm i blume展开为 npm / pnpm / yarn / bun 等标签页Mermaid 图表mermaid围栏直接渲染流程图、时序图等跟随站点深浅色主题智能标点直引号自动变弯引号--变短破折号图片优化相对路径引用的本地图片在构建时自动压缩为 WebP 并写入固有宽高点击可放大 每项特性都有实时预览 源码的官方参考页 syntax.mdx组件库文档见 components.mdx。四、Includes 机制一次编写处处复用文档写到一定规模你一定会遇到这段前置说明要在 5 个页面出现的问题。Blume 的include就是为此设计的构建期内联机制。基本用法独占一行写一条 include 语句构建时把目标文件的内容缝进当前页面——就像直接写在页面里一样标题会进入本页目录正文会被搜索索引也会出现在页面的 Markdown 镜像中include./_snippets/prerequisites.mdx/include include/_snippets/prerequisites.mdx/include路径以当前文件为基准解析以/开头则从内容根目录解析深层页面引用公共片段再也不用写../../..。下划线 Partial 约定文件名或文件夹名以下划线开头的文件会被排除在路由、导航、搜索和 sitemap 之外——这正好是共享片段的天然归属地docs/ _snippets/ prerequisites.mdx cli-flags.md guides/ quickstart.mdx ← include../_snippets/prerequisites.mdx/include index.mdxPartial 就是一个普通的 Markdown/MDX 文件Callout、代码块、组件、公式全部照常渲染。它的 frontmatter 会被剥离以宿主页面为准但它内部可以嵌套 include 其他片段循环引用会被检测并报错。blume dev运行时编辑一个 partial 会自动刷新所有引用它的页面。用 Props 让一个片段服务多个页面给 include 加属性即可传值片段内用{{name}}读取升级到 **{{plan}}** 套餐后即可使用 {{feature}}。include planEnterprise featureSSO ./_snippets/upgrade.mdx /include顺带 include 代码文件目标不是.md/.mdx时会被自动渲染为带语法高亮的代码围栏语言从扩展名推断可用lang覆盖、meta传标题include./examples/config.ts/include include metatitleconfig.ts./examples/config.ts/includeIncludes 常见诊断一览诊断码含义BLUME_INCLUDE_NOT_FOUND目标文件不存在BLUME_INCLUDE_CYCLE检测到循环引用BLUME_INCLUDE_OUTSIDE_ROOT目标越出内容根目录BLUME_INCLUDE_MALFORMEDinclude 语句格式无法解析 完整机制说明见 includes.mdx一个可运行的示例片段见 include-demo.mdx核心实现源码在 includes.ts。五、附赠技巧站点级变量 {{name}}版本号、API 地址这类全站值定义一次即可处处引用——在blume.config.ts里声明variables页面中写{{version}}就会替换。替换发生在任何读取页面之前所以渲染结果、搜索索引、Markdown 镜像里看到的都是最终值。正文中引用了一个未定义的变量会直接报构建错误BLUME_UNDEFINED_VARIABLE拼写错误到不了读者眼前。 详见 variables.mdx。六、新手检查清单✅ 纯文字页用.md需要组件/指令/公式的页用.mdx✅ 每页写好titledescriptionSEO 与分享卡片就齐了✅ 排序用数字前缀、分组用括号文件夹(internal)/URL 保持干净✅ 含冒号的 YAML 值加引号构建失败先看诊断码提示的文件与行号✅ 公共内容抽到_snippets/下用include引入并传 props✅ 用blume validate/blume check在提交前检查死链与语法问题掌握 Frontmatter、Markdown 语法与 Includes 这三件套你就能在 Blume 中高效地编写、组织和复用文档内容——剩下的只需要持续写下去。赞分享【免费下载链接】blumeThe open-source docs framework for humans and agents.项目地址https://gitcode.com/gh_mirrors/blum/blume点击查看免费下载相关推荐Slidev Block Frontmatter 详解以 YAML 代码块编写单页 Frontmatter获得语法高亮与格式化支持Slidev Block Frontmatter 详解以 YAML 代码块编写单页 Frontmatter获得语法高亮与格式化支持 在 Slidev面向开前端开发工具Slidev Markdown 语法全指南分页、Frontmatter、代码块与图表创作Slidev Markdown 语法全指南分页、Frontmatter、代码块与图表创作 Slidevslide dev读作 /slaɪdɪv/ 以前端开发工具Pelican 内容写作完全指南文章、页面、元数据、内部链接与语法高亮Pelican 内容写作完全指南文章、页面、元数据、内部链接与语法高亮 Pelican 是一个基于 Python 的静态站点生成器同时支持 Markdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考