marimo 中的mo.outline为 Notebook 自动生成可点击的 Markdown 目录大纲【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo导读mo.outline是 marimo 提供的无状态布局函数用于在 Notebook 中渲染一个目录大纲组件它会自动提取已执行单元格中所有 Markdown 标题h1–h6按层级结构展示并支持点击跳转、滚动高亮。本文基于 docs/api/layouts/outline.md 展开结合后端输出实现与前端渲染源码讲解它的用法、参数、工作原理与适用场景读完你可以直接在 Notebook 中复现一个带目录的大纲组件并理解它与编辑器侧边栏大纲、悬浮大纲之间的协作关系。一、它是什么无状态布局函数家族的一员在 marimo 中marimo.outline属于无状态Stateless的布局函数。与marimo.ui下带有交互值如tabs记录选中标签、table记录选中行的元素不同无状态布局函数不携带任何值只负责以特定方式渲染内容。docs/api/layouts/index.md 中将其描述为Display table of contents outline展示目录大纲与accordion折叠区、carousel轮播、sidebar侧边栏、tree树形结构等函数并列。这一点在实现层面也有印证后端 marimo/_output/outline.py 通过build_stateless_plugin(component_namemarimo-outline, ...)构建组件返回的是Html对象而非带值的 UI 元素前端 frontend/src/plugins/layout/OutlinePlugin.tsx 中的OutlinePlugin也实现了IStatelessPluginData接口。因此大纲组件只输出视图不产生任何可供程序读取的值。二、最小可用示例三行代码得到一份目录outline的官方文档给出了一个非常简洁的完整示例见 docs/api/layouts/outline.md。在 Notebook 中创建三个单元格# 单元格 1定义一个一级标题 import marimo as mo app.cell def __(): mo.md(# Header 1) return # 单元格 2定义一个二级标题 app.cell def __(): mo.md(## Header 2) return # 单元格 3渲染目录大纲 app.cell def __(): mo.outline(labelTable of Contents) return运行全部单元格后mo.outline的位置会渲染出一个带标题栏内容为label参数传入的 Table of Contents的目录列表其中包含# Header 1与## Header 2两个条目并呈现层级缩进。点击任意条目页面会平滑滚动到对应的标题位置。需要说明的是上面示例中的app.cell是 marimo 脚本/导出场景下的装饰器写法每个单元格一个函数在日常交互式 Notebook 中你只需要直接依次输入mo.md(# Header 1)、mo.md(## Header 2)和mo.outline(labelTable of Contents)三个单元格即可效果完全相同。三、参数说明labeloutline是纯关键字参数函数签名如下见 marimo/_output/outline.pydef outline(*, label: str ) - Html参数类型默认值说明labelstr大纲组件顶部显示的描述性标题文本。传入后会在目录列表上方渲染一个标题栏不传则没有标题栏label只是给组件本身命名的说明性文本与大纲的内容无关。官方示例中将其设为Table of Contents目录你也可以按需设置例如mo.outline(label 本章导航)或mo.outline(labelSections)。前端渲染时label会显示在组件顶部见 frontend/src/plugins/layout/OutlinePlugin.tsx 中OutlineContent的实现——当label非空时会在带边框的容器顶部渲染一个px-4 py-2 border-b font-medium text-sm样式的标题栏。四、大纲从哪里来自动提取已执行单元格中的 Markdown 标题mo.outline的内容并非手动传入而是自动扫描整个 Notebook 中已执行单元格的 Markdown 标题聚合而成。其解析逻辑位于前端 frontend/src/core/dom/outline.ts对每个输出的 HTML 字符串使用DOMParser解析并通过querySelectorAll(h1, h2, h3, h4, h5, h6)收集全部标题注释中说明此前只支持到 h3因用户请求扩展到了 h6每个标题生成一个OutlineItem包含name纯文本标题、level1–6 级与定位信息by优先使用id无 id 时退化为 XPath 定位类型定义见 frontend/src/core/cells/outline.ts若标题内部 HTML 与纯文本不一致例如包含 LaTeX 公式、行内样式会额外保留html字段大纲渲染该富文本而非纯文本保证数学公式等内容在大纲中原样呈现被marimo-carousel、marimo-tabs、marimo-accordion、marimo-sidebar等组件包裹的标题会被显式排除excludedTags避免轮播、页签等嵌套区域内的标题污染顶层目录。对 LaTeX 标题的支持在仓库中有专门的冒烟测试验证marimo/_smoke_tests/markdown/latex_outline.py 构造了包含$E mc^2$、行内公式、展示公式与混合文本标题的 Notebook用于测试这些标题在大纲面板中的渲染正确性。前端另有 frontend/src/core/dom/tests/outline.test.ts 对标题提取、排除规则与折叠范围计算进行单元测试。还有一个关键前提大纲只来自已执行的单元格。后端 docstring 明确写道 The outline automatically extracts all markdown headers fromexecuted cells见 marimo/_output/outline.py未运行过的单元格中的标题不会出现在大纲中。因此若要生成完整目录请确保所有含标题的 Markdown 单元格都已执行。五、交互行为点击跳转、滚动高亮与空状态大纲组件的交互由 frontend/src/components/editor/chrome/panels/outline/useActiveOutline.tsx 与 frontend/src/components/editor/chrome/panels/outline/floating-outline.tsx 中的OutlineList共同实现点击跳转scrollToOutlineItem通过scrollIntoView({ behavior: smooth, block: start })平滑滚动到目标标题并给该标题添加 3 秒的outline-item-highlight高亮样式帮助读者定位当前章节高亮useActiveOutline使用IntersectionObserver监听各标题在视口内的可见性始终将最靠上的可见标题标记为活动项使大纲能跟随阅读进度实时高亮空状态当 Notebook 中没有可提取的标题时items.length 0组件渲染一条虚线边框的提示文案 No outline found. Add markdown headings to your notebook to create an outline.引导用户先添加 Markdown 标题见 OutlinePlugin.tsx重复标题处理定位信息相同的标题如同名标题出现多次会按出现次序区分occurrences保证点击与高亮都能命中正确的那个。六、与编辑器侧边栏大纲 / 悬浮大纲的关系mo.outline组件与 marimo 编辑器的两个内置大纲能力共享同一套数据源与解析逻辑但定位不同侧边栏大纲面板编辑器左侧/右侧的开发面板Developer Panel中自带大纲视图对应 frontend/src/components/editor/chrome/panels/outline-panel.tsx面向编辑 Notebook场景悬浮大纲 迷你地图FloatingOutline见 floating-outline.tsx在屏幕右侧提供一个悬浮的目录入口当大纲条目少于 2 个时不显示鼠标悬停时展开一个 300px 宽的目录面板旁边还附带一条按标题层级缩进的小刻度组成的MiniMap迷你地图点击刻度即可跳转它在小屏md以下与打印场景print:hidden下自动隐藏mo.outline组件是用户显式放入 Notebook 单元格的可见目录适合演示文稿、导出的应用App或长文阅读场景——尤其当你把 Notebook 部署为 App 时只有mo.outline这种显式写入单元格的组件会出现在最终页面中。三者读取的都是同一个notebookOutline状态见 frontend/src/core/cells/cells.ts因此无论你通过哪种方式查看得到的目录结构与高亮行为都是一致的。七、典型使用建议在长篇教程、研究报告或演示型 Notebook 的顶部放置mo.outline(labelTable of Contents)为读者提供全局导航与mo.md标题配合使用时注意保持标题层级语义正确h1 → h2 → h3 逐级递减因为大纲的缩进与折叠判断依赖level值大纲只汇总已执行单元格中的标题演示前务必全部运行一遍若希望排除某些区域如页签、轮播、折叠区、侧边栏内部的标题无需额外配置——解析层已默认排除这些容器内的标题。参考实现路径速查关注点仓库路径官方 API 文档docs/api/layouts/outline.md无状态布局函数总览docs/api/layouts/index.md后端实现outline函数marimo/_output/outline.py公开导出__all__marimo/init.py前端组件插件frontend/src/plugins/layout/OutlinePlugin.tsx标题提取与排除规则frontend/src/core/dom/outline.ts大纲条目类型定义frontend/src/core/cells/outline.ts高亮 / 跳转 / 悬浮大纲 / 迷你地图frontend/src/components/editor/chrome/panels/outline/useActiveOutline.tsx、floating-outline.tsxLaTeX 标题冒烟测试marimo/_smoke_tests/markdown/latex_outline.py标题解析单元测试frontend/src/core/dom/tests/outline.test.ts【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 marimo 中的 `mo.outline`：为 Notebook 自动生成可点击的 Markdown 目录大纲
marimo 中的mo.outline为 Notebook 自动生成可点击的 Markdown 目录大纲【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo导读mo.outline是 marimo 提供的无状态布局函数用于在 Notebook 中渲染一个目录大纲组件它会自动提取已执行单元格中所有 Markdown 标题h1–h6按层级结构展示并支持点击跳转、滚动高亮。本文基于 docs/api/layouts/outline.md 展开结合后端输出实现与前端渲染源码讲解它的用法、参数、工作原理与适用场景读完你可以直接在 Notebook 中复现一个带目录的大纲组件并理解它与编辑器侧边栏大纲、悬浮大纲之间的协作关系。一、它是什么无状态布局函数家族的一员在 marimo 中marimo.outline属于无状态Stateless的布局函数。与marimo.ui下带有交互值如tabs记录选中标签、table记录选中行的元素不同无状态布局函数不携带任何值只负责以特定方式渲染内容。docs/api/layouts/index.md 中将其描述为Display table of contents outline展示目录大纲与accordion折叠区、carousel轮播、sidebar侧边栏、tree树形结构等函数并列。这一点在实现层面也有印证后端 marimo/_output/outline.py 通过build_stateless_plugin(component_namemarimo-outline, ...)构建组件返回的是Html对象而非带值的 UI 元素前端 frontend/src/plugins/layout/OutlinePlugin.tsx 中的OutlinePlugin也实现了IStatelessPluginData接口。因此大纲组件只输出视图不产生任何可供程序读取的值。二、最小可用示例三行代码得到一份目录outline的官方文档给出了一个非常简洁的完整示例见 docs/api/layouts/outline.md。在 Notebook 中创建三个单元格# 单元格 1定义一个一级标题 import marimo as mo app.cell def __(): mo.md(# Header 1) return # 单元格 2定义一个二级标题 app.cell def __(): mo.md(## Header 2) return # 单元格 3渲染目录大纲 app.cell def __(): mo.outline(labelTable of Contents) return运行全部单元格后mo.outline的位置会渲染出一个带标题栏内容为label参数传入的 Table of Contents的目录列表其中包含# Header 1与## Header 2两个条目并呈现层级缩进。点击任意条目页面会平滑滚动到对应的标题位置。需要说明的是上面示例中的app.cell是 marimo 脚本/导出场景下的装饰器写法每个单元格一个函数在日常交互式 Notebook 中你只需要直接依次输入mo.md(# Header 1)、mo.md(## Header 2)和mo.outline(labelTable of Contents)三个单元格即可效果完全相同。三、参数说明labeloutline是纯关键字参数函数签名如下见 marimo/_output/outline.pydef outline(*, label: str ) - Html参数类型默认值说明labelstr大纲组件顶部显示的描述性标题文本。传入后会在目录列表上方渲染一个标题栏不传则没有标题栏label只是给组件本身命名的说明性文本与大纲的内容无关。官方示例中将其设为Table of Contents目录你也可以按需设置例如mo.outline(label 本章导航)或mo.outline(labelSections)。前端渲染时label会显示在组件顶部见 frontend/src/plugins/layout/OutlinePlugin.tsx 中OutlineContent的实现——当label非空时会在带边框的容器顶部渲染一个px-4 py-2 border-b font-medium text-sm样式的标题栏。四、大纲从哪里来自动提取已执行单元格中的 Markdown 标题mo.outline的内容并非手动传入而是自动扫描整个 Notebook 中已执行单元格的 Markdown 标题聚合而成。其解析逻辑位于前端 frontend/src/core/dom/outline.ts对每个输出的 HTML 字符串使用DOMParser解析并通过querySelectorAll(h1, h2, h3, h4, h5, h6)收集全部标题注释中说明此前只支持到 h3因用户请求扩展到了 h6每个标题生成一个OutlineItem包含name纯文本标题、level1–6 级与定位信息by优先使用id无 id 时退化为 XPath 定位类型定义见 frontend/src/core/cells/outline.ts若标题内部 HTML 与纯文本不一致例如包含 LaTeX 公式、行内样式会额外保留html字段大纲渲染该富文本而非纯文本保证数学公式等内容在大纲中原样呈现被marimo-carousel、marimo-tabs、marimo-accordion、marimo-sidebar等组件包裹的标题会被显式排除excludedTags避免轮播、页签等嵌套区域内的标题污染顶层目录。对 LaTeX 标题的支持在仓库中有专门的冒烟测试验证marimo/_smoke_tests/markdown/latex_outline.py 构造了包含$E mc^2$、行内公式、展示公式与混合文本标题的 Notebook用于测试这些标题在大纲面板中的渲染正确性。前端另有 frontend/src/core/dom/tests/outline.test.ts 对标题提取、排除规则与折叠范围计算进行单元测试。还有一个关键前提大纲只来自已执行的单元格。后端 docstring 明确写道 The outline automatically extracts all markdown headers fromexecuted cells见 marimo/_output/outline.py未运行过的单元格中的标题不会出现在大纲中。因此若要生成完整目录请确保所有含标题的 Markdown 单元格都已执行。五、交互行为点击跳转、滚动高亮与空状态大纲组件的交互由 frontend/src/components/editor/chrome/panels/outline/useActiveOutline.tsx 与 frontend/src/components/editor/chrome/panels/outline/floating-outline.tsx 中的OutlineList共同实现点击跳转scrollToOutlineItem通过scrollIntoView({ behavior: smooth, block: start })平滑滚动到目标标题并给该标题添加 3 秒的outline-item-highlight高亮样式帮助读者定位当前章节高亮useActiveOutline使用IntersectionObserver监听各标题在视口内的可见性始终将最靠上的可见标题标记为活动项使大纲能跟随阅读进度实时高亮空状态当 Notebook 中没有可提取的标题时items.length 0组件渲染一条虚线边框的提示文案 No outline found. Add markdown headings to your notebook to create an outline.引导用户先添加 Markdown 标题见 OutlinePlugin.tsx重复标题处理定位信息相同的标题如同名标题出现多次会按出现次序区分occurrences保证点击与高亮都能命中正确的那个。六、与编辑器侧边栏大纲 / 悬浮大纲的关系mo.outline组件与 marimo 编辑器的两个内置大纲能力共享同一套数据源与解析逻辑但定位不同侧边栏大纲面板编辑器左侧/右侧的开发面板Developer Panel中自带大纲视图对应 frontend/src/components/editor/chrome/panels/outline-panel.tsx面向编辑 Notebook场景悬浮大纲 迷你地图FloatingOutline见 floating-outline.tsx在屏幕右侧提供一个悬浮的目录入口当大纲条目少于 2 个时不显示鼠标悬停时展开一个 300px 宽的目录面板旁边还附带一条按标题层级缩进的小刻度组成的MiniMap迷你地图点击刻度即可跳转它在小屏md以下与打印场景print:hidden下自动隐藏mo.outline组件是用户显式放入 Notebook 单元格的可见目录适合演示文稿、导出的应用App或长文阅读场景——尤其当你把 Notebook 部署为 App 时只有mo.outline这种显式写入单元格的组件会出现在最终页面中。三者读取的都是同一个notebookOutline状态见 frontend/src/core/cells/cells.ts因此无论你通过哪种方式查看得到的目录结构与高亮行为都是一致的。七、典型使用建议在长篇教程、研究报告或演示型 Notebook 的顶部放置mo.outline(labelTable of Contents)为读者提供全局导航与mo.md标题配合使用时注意保持标题层级语义正确h1 → h2 → h3 逐级递减因为大纲的缩进与折叠判断依赖level值大纲只汇总已执行单元格中的标题演示前务必全部运行一遍若希望排除某些区域如页签、轮播、折叠区、侧边栏内部的标题无需额外配置——解析层已默认排除这些容器内的标题。参考实现路径速查关注点仓库路径官方 API 文档docs/api/layouts/outline.md无状态布局函数总览docs/api/layouts/index.md后端实现outline函数marimo/_output/outline.py公开导出__all__marimo/init.py前端组件插件frontend/src/plugins/layout/OutlinePlugin.tsx标题提取与排除规则frontend/src/core/dom/outline.ts大纲条目类型定义frontend/src/core/cells/outline.ts高亮 / 跳转 / 悬浮大纲 / 迷你地图frontend/src/components/editor/chrome/panels/outline/useActiveOutline.tsx、floating-outline.tsxLaTeX 标题冒烟测试marimo/_smoke_tests/markdown/latex_outline.py标题解析单元测试frontend/src/core/dom/tests/outline.test.ts【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考