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），仅供参考

Blume内容编写完全指南：Frontmatter、Markdown语法与页面Includes机制详解

相关推荐

二维Navier-Stokes方程的Fourier-Galerkin谱方法：MATLAB实现与去混叠详解

AI编码质量治理实战：工程规范、代码评审与风险驱动测试

足球目标检测数据集构建：VOC与YOLO双格式标注实战指南

更多资讯

基于YOLO11的飞鸟检测：从STS数据集训练到部署全流程

AE Tips：用 TaoToken 统一 Key 批量获取属性表中的所有记录

烟雾明火烟火火灾数据集：VOC+YOLO双格式3000张实战指南

YOLOv8 TensorRT C++部署实战：从PyTorch到高效推理

钓鱼检测数据集全流程：VOC转YOLO与训练避坑指南

Python基础语法一站式指南：从环境搭建到项目实战

今日更新

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？