开发工具【免费下载链接】jupytextJupyter Notebooks as Markdown Documents, Julia, Python or R scripts项目地址https://gitcode.com/gh_mirrors/ju/jupytext点击查看免费下载Jupytext 不仅能把 Jupyter 笔记本保存为脚本还支持将笔记本完整映射为多种 Markdown 风格文档MyST、Quarto.qmd、R Markdown.Rmd、Jupytext 原生 Markdown 以及 Pandoc Markdown。本文以 Jupytext 官方文档中《Notebooks as Markdown》一章为核心骨架结合仓库源码与demo/目录下的真实示例如World population系列文件逐格式讲解其语法细节、元数据编码方式、往返转换行为与前置依赖帮助读者掌握用 Markdown 编辑笔记本的完整技能。五种 Markdown 格式一览在 src/jupytext/formats.py 中所有文本笔记本格式被统一登记为NotebookFormatDescription。其中与 Markdown 相关的格式如下格式名format_name扩展名实现方式版本号核心依赖markdown.md/.markdownJupytext 内置读写MarkdownCellReader/MarkdownCellExportermarkdown为 1.3.markdown为 1.2无rmarkdown.RmdJupytext 内置读写RMarkdownCellReader/RMarkdownCellExporter1.2无RStudio 可运行myst.md/.myst/.mystnb/.mnb调用 MyST 解析myst_to_notebook/notebook_to_myst0.13Python 3.6、markdown-it-pypandoc.md直接调用pandoc子进程随 Pandoc 版本Pandoc 2.7.2quarto.qmd直接调用quarto convert1.0Quarto 0.2.134从源码注释可以看到各格式的演进历史markdown格式自 2018 年 8 月的 v1.0 起经历了Markdown regions 与 cell metadatav1.1raw 区域改用 HTML 注释v1.2代码单元可用多于三个反引号v1.3等多次迭代当前版本号为 1.3、最低可读版本 1.0。这些版本号会自动写入每个文本笔记本的 YAML 头部的text_representation字段中作为往返转换时的兼容性依据。五种格式可以同时存在于一个笔记本的配对配置中。例如 demo/World population.md 的 YAML 头部就声明了jupyter: jupytext: formats: ipynb,.pct.py:percent,.lgt.py:light,.spx.py:sphinx,md,Rmd,.pandoc.md:pandoc这意味着同一个.ipynb笔记本可以同步维护.md、.Rmd、.pandoc.md等多个 Markdown 变体。MyST Markdown在 Markdown 中调用 Sphinx 指令MySTMarkedly Structured Text是一种实现了 reStructuredText 最佳特性的 Markdown 变体它通过 Markdown 的轻量扩展支持调用 Sphinx 指令与角色。MyST-NB 与 Jupyter Book 正是基于这一风味提供将 Jupyter 笔记本直接转换为 Sphinx 文档的能力。代码单元{code-cell}指令与 Jupytext Markdown 类似MyST Markdown 也用代码块承载代码单元但元数据不是放在反引号后面的keyvalue中而是放进代码块内部的 YAML 块里{code-cell} ipython3 --- other: more: true tags: [hide-output, show-input] --- print(Hallo!) 其中ipython3纯粹是可选的语法高亮提示。在往返转换中它取自notebook.metadata.language_info.pygments_lexer若该字段不存在则回退到default_lexer。这一点在 src/jupytext/myst.py 的notebook_to_myst中有明确实现写回文档时代码单元的分隔符由three_backticks_or_more按源码内容决定保证不会与代码体内的反引号冲突指令后附上 pygments lexer 名称。元数据的两种写法只要可能转换会优先采用 MyST 的短横线简写形式:前缀即 Sphinx 指令的参数化语法{code-cell} ipython3 :tags: [hide-output, show-input] print(Hallo!) 读取端由parse_directive_optionssrc/jupytext/myst.py处理以---包裹的块按 YAML 解析以:开头的行则逐行剥离冒号后同样交给 YAML 解析。写回端由dump_yaml_blocks决定采用哪种风格——当所有元数据行都以字母开头即不含嵌套字典时输出:key: value紧凑形式否则退回到---包裹的完整 YAML 块。Raw 单元{raw-cell}指令Raw 单元使用同样的指令风格raw 的 MIME 类型通过:raw_mimetype:参数指定{raw-cell} :raw_mimetype: text/html bBold textb Markdown 单元与 block breakMarkdown 单元不被包裹。当某个 Markdown 单元带有元数据或者紧跟在另一个 Markdown 单元之后时上方会插入一个 block break后面可以跟一行可选的JSON 形式的元数据 {slide: true} This is a markdown cell with metadata This is a new markdown cell with no metadata解析端通过myst_block_breaktoken 处理read_cell_metadata将后的内容按 JSON 解析为 dictsrc/jupytext/myst.py非 dict 或非法 JSON 会抛出MystMetadataParsingError。写回端则在单元有元数据或上一个单元也是 Markdown两种情况下输出标记。完整的 MyST 表示可以直接对照仓库中的 demo/World population.myst.md 示例阅读。此外myst格式要求 Python 3.6raise_if_myst_is_not_available会在缺少markdown-it-py时抛出ImportError并建议安装 VS Code 的 myst-highlight 扩展以获得更好的语法高亮。Quarto.qmd文档即笔记本Quarto 是构建在 Pandoc 之上的科学出版与文档系统。只要安装了quartoJupytext 就可以让你在 Jupyter 中像编辑笔记本一样编辑.qmd文档并把.ipynb与.qmd配对同步。关键事实与注意点.ipynb与.qmd之间的双向转换直接调用quarto convert命令因此要求 Quarto v0.2.134 或更高版本该版本号同时也记录在 src/jupytext/formats.py 的格式描述中作为quarto格式的当前版本号。.ipynb → .qmd → .ipynb的往返会产生两个副作用连续的 Markdown 单元会被拼接Raw 单元会被转成 Markdown 单元——因为.qmd文件把所有内容都表示为 Markdown 或代码单元两种形态无法保留 raw 与连续 Markdown 单元的分隔信息。R Markdown.Rmd双栖于 Jupyter 与 RStudioR Markdown 是 RStudio 的笔记本格式支持 R、Python 及众多其他语言。Jupytext 的 R Markdown 实现与 Markdown 格式非常相似主要差异在代码单元语言与选项用花括号包裹遵循 R Markdown 惯例单元元数据编码为 R 对象。例如带parameters标签的单元表示为{python tagsc(parameters)} param 5因此用 R Markdown 表示的 Python 与 R 笔记本可以同时在 Jupyter 和 RStudio 中运行。若需在 RStudio 中修改默认的 Python 环境可以在 .Renviron 文件中设置 RETICULATE_PYTHON 环境变量。 仓库中的 [demo/World population.Rmd](https://link.gitcode.com/i/b1368d778debd2fbbae747148af07454) 给出了完整示例——从头部来看它与 .md 版本共用同一套 YAML 元数据formats 列表中同时包含 md 和 Rmd正文中的代码单元则全部改用 {python} 花括号写法。值得注意的是两个文件的内容主体完全一致说明同一笔记本在不同 Markdown 变体间可以保持逻辑等价。 ## Jupytext Markdown面向教程与书籍的原生格式 Jupytext 可以把笔记本保存为纯 Markdown 文档。这种格式非常适合教程、书籍以及任何文字多于代码的笔记本——用 GitHub 或绝大多数 Markdown 编辑器/渲染器都能良好渲染。 ### YAML 头部存放笔记本级元数据 与所有 Jupytext 格式一样Jupytext Markdown 笔记本以一个可选的YAML 头部开始用于存放选定的笔记本元数据如内核信息以及 Jupytext 自身的格式与版本信息 yaml --- jupyter: jupytext: text_representation: extension: .md format_name: markdown format_version: 1.1 jupytext_version: 1.1.0 kernelspec: display_name: Python 3 language: python name: python3 ---你可以在jupyter:段下追加自定义笔记本元数据如author、title它们会与笔记本元数据双向同步。如果希望导出更多笔记本元数据可以参考 advanced-options 文档中的 metadata filtering默认notebook_metadata_filterkernelspec,jupytext只保留内核与 Jupytext 元数据可通过jupytext --opt notebook_metadata_filterall,-widgets,-varInspector或配置文件中修改。Markdown 单元的切分规则在 Markdown 格式中Markdown 单元按原文逐字保留单元之间用两个空行分隔。如果你希望 Markdown 标题#也触发单元切分可以在 YAML 头部的jupytext段加入split_at_heading: truejupytext: split_at_heading: true若希望该选项成为 Jupyter 中所有 Markdown 文档的默认行为则在 jupytext.toml 配置文件 中全局开启split_at_heading true该选项在 src/jupytext/cell_reader.py 的MarkdownCellReader.__init__中被读取并保存为实例属性作为 Markdown 单元结束判定两个连续空行之外的额外切分依据。代码单元三重反引号 语言 元数据代码单元使用经典的三重反引号后跟笔记本语言。单元元数据以keyvalue语法追加在语言信息之后value按 JSON 编码。例如 Python 笔记本中一个带parameters标签的代码单元python tags[parameters] param 5解析由 MarkdownCellReader 的正则完成[src/jupytext/cell_reader.py](https://link.gitcode.com/i/a8781ee150f1450c548080a96787291e)start_code_re 匹配 加 Jupyter 支持的语言名options_to_metadata 再从行尾解析出元数据单元结束符则依据开头的反引号数量动态生成end_code_re因此代码单元也可以用四个或更多反引号开头以规避代码体内的反引号冲突。 ### 让代码片段不被当作可执行单元 只要代码片段带有显式语言、且该语言在 Jupyter 中受支持Jupytext 就会把它当作代码单元。如果你有一段不想在 Jupyter 中执行的代码片段有以下四种做法 1. **去掉语言信息**如直接写 2. 用**三个波浪号**代替反引号开头例如 ~~~python 而非 python 3. 添加 activemd 单元元数据或在语言信息后加 .noeval 属性例如 python .noeval 源码中检测到 .noeval 后单元类型会被强制置为 markdown 并清空元数据见 [src/jupytext/cell_reader.py](https://link.gitcode.com/i/a6ea0af8388cdba95da1a56b3b980e6c) 4. 用显式的 Markdown 单元标记把代码片段包围起来见下文。 ### Raw 单元HTML 注释定界 Raw 单元用 HTML 注释定界并接受同样的 keyvalue 元数据格式 md !-- #raw -- raw text !-- #endraw -- !-- #raw keyvalue-- raw cell with metadata !-- #endraw --start_region_re正则^!--\s*#(region|markdown|md|raw)(.*)--\s*$负责识别这些注释标记src/jupytext/cell_reader.pyraw对应的单元类型为 raw其余为 markdown。显式 Markdown 单元标记与折叠Markdown 单元也可以使用显式标记!-- #md --、!-- #markdown --或!-- #region --以及对应的!-- #end... --收尾标记。其中!-- #region --/!-- #endregion --在 VS Code 中可折叠还可以在标记中插入标题例如!-- #region This is a title for my protected cell --。这类标记同样接受keyvalueJSON 编码格式的单元元数据。从源码看#region标记的名称会被捕获并用于生成对应的结束正则^!--\s*#end{region_name}\s*--\s*$若区域名为markdown/md还会在元数据中记录region_name以便写回时保留标记风格。完整的 Markdown 表示可对照 demo/World population.md 阅读——该文件还展示了cell_markers: region,endregion配置与formats配对列表的实际写法。Pandoc Markdownpandoc div 包裹的通用转换格式Pandoc 作为万能文档转换器本身就支持读写 Jupyter 笔记本。在 Pandoc Markdown 中所有单元都用 pandoc div:::标记因此格式比 Jupytext Markdown 略显冗长::: {.cell .markdown} # A quick insight at world population ## Collecting population data ... ::: ::: {.cell .code} {.python} import pandas as pd ...:::完整示例见 [demo/World population.pandoc.md](https://link.gitcode.com/i/67884c761eefbc362628f2c10e7a0972)其头部中 format_name: pandoc、format_version: 2.7.2 直接记录了所用 Pandoc 的版本。 底层实现位于 [src/jupytext/pandoc.py](https://link.gitcode.com/i/b25aade98a51d23349e2170f5105ed2a)md_to_notebook 与 notebook_to_md 通过临时文件调用 pandoc 子进程完成双向转换。转换参数会随版本调整——Pandoc 2.11.2 使用 --markdown-headingsatx更早版本使用 --atx-headers同时以 --wrappreserve --preserve-tabs 保留原文换行与制表符。若未安装 Pandoc 或版本过低raise_if_pandoc_is_not_available 会抛出包含版本要求的明确错误。 使用该格式前请安装 **Pandoc 2.7.2 或以上版本**例如 bash conda install pandoc -c conda-forge实战在同一仓库中对比五种表示demo/目录恰好提供了同一本World population.ipynb的五种 Markdown 变体是理解各格式差异的最佳对照材料demo/World population.mdJupytext 原生 Markdown代码单元为pythondemo/World population.myst.mdMyST 格式代码单元为{code-cell} ipython3demo/World population.RmdR Markdown 格式代码单元为{python}demo/World population.pandoc.mdPandoc 格式全部单元被::: {.cell ...}div 包裹demo/World population.ipynb原始的 JSON 笔记本。选择哪种格式取决于你的目标场景面向 Sphinx/Jupyter Book 文档站选择 MyST面向 RStudio 双栖工作流选择 R Markdown面向出版级转换链选择 Pandoc 或 Quarto而 Jupytext Markdown 则是最通用、最轻量的选择——任何 Markdown 渲染器都能直接呈现适合教程与书籍写作。常见问题速查如何阻止某段代码在 Jupyter 中被当作可执行单元去掉语言、改用~~~、添加activemd或.noeval属性、或用 Markdown 单元标记包围四种方式任选其一。.qmd往返后单元变了这是预期行为Quarto 往返会拼接连续 Markdown 单元并把 Raw 单元转为 Markdown 单元。myst格式报错确认 Python 3.6 且已安装markdown-it-py该格式的可用扩展名为.md、.myst、.mystnb、.mnb见 src/jupytext/myst.py。pandoc格式报错确认pandoc --version 2.7.2可用conda install pandoc -c conda-forge安装。想把更多元数据写进 Markdown通过notebook_metadata_filter/cell_metadata_filter控制导出范围详见 metadata filtering 说明。赞分享开发工具【免费下载链接】jupytextJupyter Notebooks as Markdown Documents, Julia, Python or R scripts项目地址https://gitcode.com/gh_mirrors/ju/jupytext点击查看免费下载相关推荐Jupytext 的 Pandoc Markdown 格式Notebook 与 Pandoc Markdown 的双向转换实战Jupytext 的 Pandoc Markdown 格式Notebook 与 Pandoc Markdown 的双向转换实战 导读 本文以 Jupytext开发工具Jupytext 的 Pandoc Markdown 格式实战Raw Cell 与 .cell 语法完全解析Jupytext 的 Pandoc Markdown 格式实战Raw Cell 与 .cell 语法完全解析 Jupytext 提供了一种特殊的 Pandoc开发工具Jupytext 的 Pandoc Markdown 格式md:pandoc从 ipynb 到 Pandoc 兼容 Markdown 的完整转换指南Jupytext 的 Pandoc Markdown 格式md:pandoc从 ipynb 到 Pandoc 兼容 Markdown 的完整转换指南 导读开发工具上一篇Smanga终极指南3分钟打造你的私人漫画流媒体帝国下一篇aeneas性能优化技巧C扩展加速与内存管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
开发工具【免费下载链接】jupytextJupyter Notebooks as Markdown Documents, Julia, Python or R scripts项目地址https://gitcode.com/gh_mirrors/ju/jupytext点击查看免费下载Jupytext 不仅能把 Jupyter 笔记本保存为脚本还支持将笔记本完整映射为多种 Markdown 风格文档MyST、Quarto.qmd、R Markdown.Rmd、Jupytext 原生 Markdown 以及 Pandoc Markdown。本文以 Jupytext 官方文档中《Notebooks as Markdown》一章为核心骨架结合仓库源码与demo/目录下的真实示例如World population系列文件逐格式讲解其语法细节、元数据编码方式、往返转换行为与前置依赖帮助读者掌握用 Markdown 编辑笔记本的完整技能。五种 Markdown 格式一览在 src/jupytext/formats.py 中所有文本笔记本格式被统一登记为NotebookFormatDescription。其中与 Markdown 相关的格式如下格式名format_name扩展名实现方式版本号核心依赖markdown.md/.markdownJupytext 内置读写MarkdownCellReader/MarkdownCellExportermarkdown为 1.3.markdown为 1.2无rmarkdown.RmdJupytext 内置读写RMarkdownCellReader/RMarkdownCellExporter1.2无RStudio 可运行myst.md/.myst/.mystnb/.mnb调用 MyST 解析myst_to_notebook/notebook_to_myst0.13Python 3.6、markdown-it-pypandoc.md直接调用pandoc子进程随 Pandoc 版本Pandoc 2.7.2quarto.qmd直接调用quarto convert1.0Quarto 0.2.134从源码注释可以看到各格式的演进历史markdown格式自 2018 年 8 月的 v1.0 起经历了Markdown regions 与 cell metadatav1.1raw 区域改用 HTML 注释v1.2代码单元可用多于三个反引号v1.3等多次迭代当前版本号为 1.3、最低可读版本 1.0。这些版本号会自动写入每个文本笔记本的 YAML 头部的text_representation字段中作为往返转换时的兼容性依据。五种格式可以同时存在于一个笔记本的配对配置中。例如 demo/World population.md 的 YAML 头部就声明了jupyter: jupytext: formats: ipynb,.pct.py:percent,.lgt.py:light,.spx.py:sphinx,md,Rmd,.pandoc.md:pandoc这意味着同一个.ipynb笔记本可以同步维护.md、.Rmd、.pandoc.md等多个 Markdown 变体。MyST Markdown在 Markdown 中调用 Sphinx 指令MySTMarkedly Structured Text是一种实现了 reStructuredText 最佳特性的 Markdown 变体它通过 Markdown 的轻量扩展支持调用 Sphinx 指令与角色。MyST-NB 与 Jupyter Book 正是基于这一风味提供将 Jupyter 笔记本直接转换为 Sphinx 文档的能力。代码单元{code-cell}指令与 Jupytext Markdown 类似MyST Markdown 也用代码块承载代码单元但元数据不是放在反引号后面的keyvalue中而是放进代码块内部的 YAML 块里{code-cell} ipython3 --- other: more: true tags: [hide-output, show-input] --- print(Hallo!) 其中ipython3纯粹是可选的语法高亮提示。在往返转换中它取自notebook.metadata.language_info.pygments_lexer若该字段不存在则回退到default_lexer。这一点在 src/jupytext/myst.py 的notebook_to_myst中有明确实现写回文档时代码单元的分隔符由three_backticks_or_more按源码内容决定保证不会与代码体内的反引号冲突指令后附上 pygments lexer 名称。元数据的两种写法只要可能转换会优先采用 MyST 的短横线简写形式:前缀即 Sphinx 指令的参数化语法{code-cell} ipython3 :tags: [hide-output, show-input] print(Hallo!) 读取端由parse_directive_optionssrc/jupytext/myst.py处理以---包裹的块按 YAML 解析以:开头的行则逐行剥离冒号后同样交给 YAML 解析。写回端由dump_yaml_blocks决定采用哪种风格——当所有元数据行都以字母开头即不含嵌套字典时输出:key: value紧凑形式否则退回到---包裹的完整 YAML 块。Raw 单元{raw-cell}指令Raw 单元使用同样的指令风格raw 的 MIME 类型通过:raw_mimetype:参数指定{raw-cell} :raw_mimetype: text/html bBold textb Markdown 单元与 block breakMarkdown 单元不被包裹。当某个 Markdown 单元带有元数据或者紧跟在另一个 Markdown 单元之后时上方会插入一个 block break后面可以跟一行可选的JSON 形式的元数据 {slide: true} This is a markdown cell with metadata This is a new markdown cell with no metadata解析端通过myst_block_breaktoken 处理read_cell_metadata将后的内容按 JSON 解析为 dictsrc/jupytext/myst.py非 dict 或非法 JSON 会抛出MystMetadataParsingError。写回端则在单元有元数据或上一个单元也是 Markdown两种情况下输出标记。完整的 MyST 表示可以直接对照仓库中的 demo/World population.myst.md 示例阅读。此外myst格式要求 Python 3.6raise_if_myst_is_not_available会在缺少markdown-it-py时抛出ImportError并建议安装 VS Code 的 myst-highlight 扩展以获得更好的语法高亮。Quarto.qmd文档即笔记本Quarto 是构建在 Pandoc 之上的科学出版与文档系统。只要安装了quartoJupytext 就可以让你在 Jupyter 中像编辑笔记本一样编辑.qmd文档并把.ipynb与.qmd配对同步。关键事实与注意点.ipynb与.qmd之间的双向转换直接调用quarto convert命令因此要求 Quarto v0.2.134 或更高版本该版本号同时也记录在 src/jupytext/formats.py 的格式描述中作为quarto格式的当前版本号。.ipynb → .qmd → .ipynb的往返会产生两个副作用连续的 Markdown 单元会被拼接Raw 单元会被转成 Markdown 单元——因为.qmd文件把所有内容都表示为 Markdown 或代码单元两种形态无法保留 raw 与连续 Markdown 单元的分隔信息。R Markdown.Rmd双栖于 Jupyter 与 RStudioR Markdown 是 RStudio 的笔记本格式支持 R、Python 及众多其他语言。Jupytext 的 R Markdown 实现与 Markdown 格式非常相似主要差异在代码单元语言与选项用花括号包裹遵循 R Markdown 惯例单元元数据编码为 R 对象。例如带parameters标签的单元表示为{python tagsc(parameters)} param 5因此用 R Markdown 表示的 Python 与 R 笔记本可以同时在 Jupyter 和 RStudio 中运行。若需在 RStudio 中修改默认的 Python 环境可以在 .Renviron 文件中设置 RETICULATE_PYTHON 环境变量。 仓库中的 [demo/World population.Rmd](https://link.gitcode.com/i/b1368d778debd2fbbae747148af07454) 给出了完整示例——从头部来看它与 .md 版本共用同一套 YAML 元数据formats 列表中同时包含 md 和 Rmd正文中的代码单元则全部改用 {python} 花括号写法。值得注意的是两个文件的内容主体完全一致说明同一笔记本在不同 Markdown 变体间可以保持逻辑等价。 ## Jupytext Markdown面向教程与书籍的原生格式 Jupytext 可以把笔记本保存为纯 Markdown 文档。这种格式非常适合教程、书籍以及任何文字多于代码的笔记本——用 GitHub 或绝大多数 Markdown 编辑器/渲染器都能良好渲染。 ### YAML 头部存放笔记本级元数据 与所有 Jupytext 格式一样Jupytext Markdown 笔记本以一个可选的YAML 头部开始用于存放选定的笔记本元数据如内核信息以及 Jupytext 自身的格式与版本信息 yaml --- jupyter: jupytext: text_representation: extension: .md format_name: markdown format_version: 1.1 jupytext_version: 1.1.0 kernelspec: display_name: Python 3 language: python name: python3 ---你可以在jupyter:段下追加自定义笔记本元数据如author、title它们会与笔记本元数据双向同步。如果希望导出更多笔记本元数据可以参考 advanced-options 文档中的 metadata filtering默认notebook_metadata_filterkernelspec,jupytext只保留内核与 Jupytext 元数据可通过jupytext --opt notebook_metadata_filterall,-widgets,-varInspector或配置文件中修改。Markdown 单元的切分规则在 Markdown 格式中Markdown 单元按原文逐字保留单元之间用两个空行分隔。如果你希望 Markdown 标题#也触发单元切分可以在 YAML 头部的jupytext段加入split_at_heading: truejupytext: split_at_heading: true若希望该选项成为 Jupyter 中所有 Markdown 文档的默认行为则在 jupytext.toml 配置文件 中全局开启split_at_heading true该选项在 src/jupytext/cell_reader.py 的MarkdownCellReader.__init__中被读取并保存为实例属性作为 Markdown 单元结束判定两个连续空行之外的额外切分依据。代码单元三重反引号 语言 元数据代码单元使用经典的三重反引号后跟笔记本语言。单元元数据以keyvalue语法追加在语言信息之后value按 JSON 编码。例如 Python 笔记本中一个带parameters标签的代码单元python tags[parameters] param 5解析由 MarkdownCellReader 的正则完成[src/jupytext/cell_reader.py](https://link.gitcode.com/i/a8781ee150f1450c548080a96787291e)start_code_re 匹配 加 Jupyter 支持的语言名options_to_metadata 再从行尾解析出元数据单元结束符则依据开头的反引号数量动态生成end_code_re因此代码单元也可以用四个或更多反引号开头以规避代码体内的反引号冲突。 ### 让代码片段不被当作可执行单元 只要代码片段带有显式语言、且该语言在 Jupyter 中受支持Jupytext 就会把它当作代码单元。如果你有一段不想在 Jupyter 中执行的代码片段有以下四种做法 1. **去掉语言信息**如直接写 2. 用**三个波浪号**代替反引号开头例如 ~~~python 而非 python 3. 添加 activemd 单元元数据或在语言信息后加 .noeval 属性例如 python .noeval 源码中检测到 .noeval 后单元类型会被强制置为 markdown 并清空元数据见 [src/jupytext/cell_reader.py](https://link.gitcode.com/i/a6ea0af8388cdba95da1a56b3b980e6c) 4. 用显式的 Markdown 单元标记把代码片段包围起来见下文。 ### Raw 单元HTML 注释定界 Raw 单元用 HTML 注释定界并接受同样的 keyvalue 元数据格式 md !-- #raw -- raw text !-- #endraw -- !-- #raw keyvalue-- raw cell with metadata !-- #endraw --start_region_re正则^!--\s*#(region|markdown|md|raw)(.*)--\s*$负责识别这些注释标记src/jupytext/cell_reader.pyraw对应的单元类型为 raw其余为 markdown。显式 Markdown 单元标记与折叠Markdown 单元也可以使用显式标记!-- #md --、!-- #markdown --或!-- #region --以及对应的!-- #end... --收尾标记。其中!-- #region --/!-- #endregion --在 VS Code 中可折叠还可以在标记中插入标题例如!-- #region This is a title for my protected cell --。这类标记同样接受keyvalueJSON 编码格式的单元元数据。从源码看#region标记的名称会被捕获并用于生成对应的结束正则^!--\s*#end{region_name}\s*--\s*$若区域名为markdown/md还会在元数据中记录region_name以便写回时保留标记风格。完整的 Markdown 表示可对照 demo/World population.md 阅读——该文件还展示了cell_markers: region,endregion配置与formats配对列表的实际写法。Pandoc Markdownpandoc div 包裹的通用转换格式Pandoc 作为万能文档转换器本身就支持读写 Jupyter 笔记本。在 Pandoc Markdown 中所有单元都用 pandoc div:::标记因此格式比 Jupytext Markdown 略显冗长::: {.cell .markdown} # A quick insight at world population ## Collecting population data ... ::: ::: {.cell .code} {.python} import pandas as pd ...:::完整示例见 [demo/World population.pandoc.md](https://link.gitcode.com/i/67884c761eefbc362628f2c10e7a0972)其头部中 format_name: pandoc、format_version: 2.7.2 直接记录了所用 Pandoc 的版本。 底层实现位于 [src/jupytext/pandoc.py](https://link.gitcode.com/i/b25aade98a51d23349e2170f5105ed2a)md_to_notebook 与 notebook_to_md 通过临时文件调用 pandoc 子进程完成双向转换。转换参数会随版本调整——Pandoc 2.11.2 使用 --markdown-headingsatx更早版本使用 --atx-headers同时以 --wrappreserve --preserve-tabs 保留原文换行与制表符。若未安装 Pandoc 或版本过低raise_if_pandoc_is_not_available 会抛出包含版本要求的明确错误。 使用该格式前请安装 **Pandoc 2.7.2 或以上版本**例如 bash conda install pandoc -c conda-forge实战在同一仓库中对比五种表示demo/目录恰好提供了同一本World population.ipynb的五种 Markdown 变体是理解各格式差异的最佳对照材料demo/World population.mdJupytext 原生 Markdown代码单元为pythondemo/World population.myst.mdMyST 格式代码单元为{code-cell} ipython3demo/World population.RmdR Markdown 格式代码单元为{python}demo/World population.pandoc.mdPandoc 格式全部单元被::: {.cell ...}div 包裹demo/World population.ipynb原始的 JSON 笔记本。选择哪种格式取决于你的目标场景面向 Sphinx/Jupyter Book 文档站选择 MyST面向 RStudio 双栖工作流选择 R Markdown面向出版级转换链选择 Pandoc 或 Quarto而 Jupytext Markdown 则是最通用、最轻量的选择——任何 Markdown 渲染器都能直接呈现适合教程与书籍写作。常见问题速查如何阻止某段代码在 Jupyter 中被当作可执行单元去掉语言、改用~~~、添加activemd或.noeval属性、或用 Markdown 单元标记包围四种方式任选其一。.qmd往返后单元变了这是预期行为Quarto 往返会拼接连续 Markdown 单元并把 Raw 单元转为 Markdown 单元。myst格式报错确认 Python 3.6 且已安装markdown-it-py该格式的可用扩展名为.md、.myst、.mystnb、.mnb见 src/jupytext/myst.py。pandoc格式报错确认pandoc --version 2.7.2可用conda install pandoc -c conda-forge安装。想把更多元数据写进 Markdown通过notebook_metadata_filter/cell_metadata_filter控制导出范围详见 metadata filtering 说明。赞分享开发工具【免费下载链接】jupytextJupyter Notebooks as Markdown Documents, Julia, Python or R scripts项目地址https://gitcode.com/gh_mirrors/ju/jupytext点击查看免费下载相关推荐Jupytext 的 Pandoc Markdown 格式Notebook 与 Pandoc Markdown 的双向转换实战Jupytext 的 Pandoc Markdown 格式Notebook 与 Pandoc Markdown 的双向转换实战 导读 本文以 Jupytext开发工具Jupytext 的 Pandoc Markdown 格式实战Raw Cell 与 .cell 语法完全解析Jupytext 的 Pandoc Markdown 格式实战Raw Cell 与 .cell 语法完全解析 Jupytext 提供了一种特殊的 Pandoc开发工具Jupytext 的 Pandoc Markdown 格式md:pandoc从 ipynb 到 Pandoc 兼容 Markdown 的完整转换指南Jupytext 的 Pandoc Markdown 格式md:pandoc从 ipynb 到 Pandoc 兼容 Markdown 的完整转换指南 导读开发工具上一篇Smanga终极指南3分钟打造你的私人漫画流媒体帝国下一篇aeneas性能优化技巧C扩展加速与内存管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
