博客
背景
使用 notebook 写博客相比使用 Markdown 可以显著提高效率，特别是对于包含代码的博文。以前，没有静态站点生成器将 Jupyter Notebook 作为一流的创作媒介来支持。这导致我们创建了 fastpages（现已弃用），它扩展了 Jekyll，可以直接使用 Jupyter 进行博客写作。
认识 Quarto
然而，现在有了 Quarto，这是一个出色的发布系统，对通过 Jupyter Notebook 进行创作提供了丰富的支持。
Quarto 入门的一些有用资源
- Quarto 主页
- 使用 Quarto 创建博客：此页面可帮助您开始创建博客。
- Quarto 站点图库：使用 Quarto 的良好参考示例。
- Quarto 网站：Quarto 网站是使用 Quarto 构建的，他们使用了一些高级功能。查看此项目有助于理解 Quarto 的工作原理。
您不需要使用 nbdev 来创建基于 notebook 的博客。但是，您可能希望：
- 在您的 nbdev 项目网站中包含博客
- 在您的博客中使用一些 nbdev 功能（测试、导出等）
我们将在本文中讨论这些主题。
从 fastpages 迁移
如果您之前有一个 fastpages 站点，我们提供了一些实用程序来帮助您迁移到 Quarto。 迁移不是完全自动化的：您可能需要手动纠正一些我们无法自动化的事情。
说明
创建一个新的仓库或目录来迁移您的博客
在这个新仓库中，使用以下终端命令创建一个 quarto 博客并安装所需的扩展。这将为您创建一个最小的项目结构：
quarto create-project --type website:blog .
quarto install extension quarto-ext/video- 您的新仓库将有一个
posts/目录。您将把 fastpages 中的所有 notebook 和 markdown 文章复制到这里。例如，假设您的 fastpages 博客仓库位于同级目录../blog/中，您可以这样复制所有相关文章：
执行以下命令之前，请确保您位于 quarto 目录的根目录。此外，根据您的 fastpages 仓库相对于当前目录的位置，适当修改命令。
cp -r ../blog/_notebooks/* posts
cp -r ../blog/_posts/* posts- 将所有与您的文章相关的图片复制到
posts/目录中。您需要从几个地方获取图片（由于 Jekyll 和 fastpages 的工作方式）。
cp ../blog/images/* posts
cp -r ../blog/images/copied_from_nb/* posts/- 使用以下命令使您的文章兼容 Quarto：
nbdev_migrate --path postsnbdev_migrate 的作用是什么？nbdev_migrate 执行以下操作：
对于 notebook
对于 markdown 和 notebook
- 自动创建链接别名，以便旧链接不会中断。Jekyll 自动生成 URL 的方式与 Quarto 不同，因此这可以确保 Jekyll 的方式被设置为别名。
- 自动更正图片路径
- 通过在必要时更改字段名称和值，使 front matter 与 Quarto 兼容
- 更新以下文件：
./.gitignore：我们建议添加_site/以及点文件.*./about.qmd：添加关于您自己的一些信息。./profile.jpg：可选地更改个人资料图片。
- 使用命令
quarto preview预览您的站点，并进行任何必要的调整，修复断开的链接或需要转换为 Quarto 的 Jekyll shortcodes（带有{% ... %}的内容）。如果需要帮助查找特定的 Quarto 功能，请查阅 Quarto 文档。
配置选项：fastpages vs. Quarto
fastpages（基于 Jekyll）和 Quarto 为单个文章和站点级别提供了不同的选项和配置。下表列出了 fastpages 的一些最重要的功能以及它们如何映射到 Quarto。最后一列中的每个链接都指向相关功能的详细信息。
文章级别选项
| Jekyll Front Matter | Quarto | 注意 |
|---|---|---|
| toc: false | 相同 | Quarto 文档中有更多选项 |
| badges: true | 不适用 | 尚未支持 |
| comments: true | 参见注释 | Quarto 文档 |
| categories: [fastpages, jupyter] | 相同 | Quarto 文档 |
| image: images/some_folder/your_image.png | 相同 | Quarto 文档 |
| hide: false | draft: true | Quarto 文档 |
| search_exclude: true | 参见注释 | Quarto 文档 |
| title | 相同 | |
| description | 相同 | |
| sticky_rank | 不支持 | Quarto 文档 |
站点级别选项
| Jekyll 站点配置 | Quarto | 注意 |
|---|---|---|
| title | 参见注释 | Quarto 文档 |
| description | 参见注释 | Quarto 文档 |
| github_repo | 参见注释 | Quarto 文档 |
| url | 不适用 | 不需要此项 |
| baseurl | 不适用 | 不需要此项 |
| twitter_username | 在注释页面搜索“twitter” | Quarto 文档 |
| use_math | 参见注释 | Quarto 文档 |
| google_analytics | website: google-analytics: “UA-XXXXXXXX” | Quarto 文档 |
| show_image | 不适用 | Quarto 文档 |
| show_tags | 参见注释中页面的 title-block-categories | Quarto 文档 |
| pagination | website: page-navigation: true | Quarto 文档 |
| annotations | comments: hypothesis: … | Quarto 文档 |
发布您的博客
本节适用于不属于 nbdev 文档站点的独立博客。如果您想在 nbdev 文档站点中创建博客，请参阅本节。
您可以使用 quarto publish 命令发布您的站点。更多详细信息请参阅文档。
如果使用 GitHub Pages，请在发布站点之前将文件提交到 GitHub。不需要 GitHub Actions，您可以改用 quarto publish。如果您想使用 GitHub Actions 自动化工作流程，可以按照这些说明操作。
在 nbdev 项目中创建博客
除了可以使用 Quarto 构建独立博客之外，您可能还希望在您的 nbdev 项目中包含一个博客站点。本网站也拥有一个博客！实现博客最简单的方法是模仿此文件夹的目录结构。一般步骤如下：
- 在您的 notebook 文件夹中创建一个
blog/目录。 - 在
blog/目录的根目录创建一个index.qmd文件。 这里有一个示例。
index.qmd 文件中的 frontmatter 向 Quarto 发出信号，表示您打算创建一个博客。例如，这是我们的 front matter
---
title: nbdev Blog
subtitle: News, tips, and commentary about all things nbdev
listing:
sort: "date desc"
contents: "posts"
sort-ui: false
filter-ui: false
categories: true
feed: true
page-layout: full
---listing: 字段指定您希望如何构建博客。您可以直接复制我们的配置，但我们鼓励您查阅文档以了解更多选项。
- 在您站点的导航栏中创建指向博客的链接，以便人们可以找到它：要在站点导航栏中添加指向博客的链接，您必须编辑
_quarto.yml文件中的 navbar 部分，以包含指向您博客列表页面的链接，在我们的示例中是blog/index.qmd。对于 nbdev，我们_quarto.yml文件中的相关部分如下所示：
_quarto.yml 文件的一个缩写版本。website:
navbar:
left:
- text: "Blog"
href: blog/index.qmd您可以在Quarto 文档中阅读有关导航栏的更多信息。
为每篇博文创建一个文件夹：这不是强制要求，但我们建议这样做可以保持您的博文和相关资产（图片、视频等）井井有条。
创建您的第一篇博文：您可以模仿我们的示例或创建您自己的博文。在每个文件夹中，创建一个
index.qmd或index.ipynb文件。您还可以将图片和相关资产放在同一文件夹中。
文件夹结构
下面是 nbdev 站点中博客的一般文件夹结构概述：
nbs/blog
├── index.qmd
└── posts
├── 2022-07-28-nbdev2
│ ├── cover.png
│ ├── index.qmd
│ ├── ...
└── 2022-08-25-jupyter-git
├── friendly-conflict.png
├── index.qmd
└── ...
...nbs/blog：这是您 notebook 文件夹中包含博客的文件夹。index.qmd：这位于您博客文件夹的根目录，是您博客的列表页。posts/：这是每篇博文的子目录。YYYY-MM-DD-.../index.{qmd,ipynb}：这是您撰写每篇博文内容的地方。
nbdev 博客的特殊注意事项
与独立的 Quarto 博客相比，当您将博客嵌入到 nbdev 网站中时，存在以下差异：
- 除了 Quarto 指令外，您还可以使用所有nbdev 指令。所有 nbdev 功能都将在您的 nbdev 博客中可用，其工作方式与其他页面相同。
- 您的站点将自动使用 GitHub Actions 或您为 nbdev 站点配置的任何部署机制进行部署，因此您无需使用
quarto publish。
在 nbdev 项目之外的博客中使用 nbdev 功能
本节适用于不属于 nbdev 文档站点的独立博客。如果您在 nbdev 文档站点中创建博客，所有 nbdev 功能将自动生效。
如果您使用 Quarto 创建独立博客，有限数量的 nbdev 功能仍可以为您提供帮助。例如，我们建议安装Jupyter git hooks。您可用的 nbdev 功能列表列在本文中。
从零开始创建一个新的博客站点
您可以使用quarto CLI 使用以下命令设置一个新的博客项目，名为 myblog：
quarto create-project myblog --type website:blog然后您可以使用 quarto preview 预览您的博客项目。您还可以使用quarto publish 命令发布您的博客。
要将 notebook 博文添加到使用上述命令创建的博客项目中，您可以在 posts/ 下添加一个额外的文件夹，并将 notebook 命名为 index.ipynb。您将看到同级文件夹中现有的示例博文（它们是 index.qmd 文件），您可以作为参考。您需要在 notebook 的第一个单元格中以原始单元格的形式添加yaml front matter。
有关使用 Quarto 创建博客的更多信息，请参阅本指南。
常见问题
我需要从 fastpages 迁移吗？
不需要。但是，我们今后将不再积极支持 fastpages。
从 fastpages 迁移到 Quarto 需要大量手动操作吗？
您需要进行一些手动工作，以确保所有内容看起来和工作方式相同，包括将 Jekyll shortcodes 转换为等效的 Quarto 命令。但是，我们已经为您自动化了大部分重要方面。请参阅从 fastpages 迁移以获取说明。
我在 Quarto 中找不到与 fastpages 中
#collapse_output功能相同的东西。正确，Quarto 尚未支持此功能。
为什么我的 Quarto 博文会看到
{% twitter ...%}、{% fn_detail ... %}和其他{%...%}命令？这些是 Jekyll shortcodes，您必须手动迁移到 Quarto。例如，对于 Twitter 嵌入，您可以按照Twitter 的建议插入相应的 HTML。对于脚注，您可以参阅这些文档。对于其他项目，您应该在Quarto 文档中搜索如何实现您想要的结果。
我创建了一篇新的博文并使用了
#| hide，但单元格仍然显示。这是怎么回事？您必须使用 Quarto 指令，而不是特定于 nbdev 的指令。请参阅这些文档了解两者之间的区别。这是因为您是使用 Quarto 写博客，而不是 nbdev。例外情况是，如果您的 nbdev 项目中有一个博客站点，那么特定于 nbdev 的指令将起作用。
如何在我的博文上启用评论？
通常，Quarto 提供了与 fastpages 相同的所有功能以及更多功能，包括评论。如果您在Quarto 文档中搜索评论，您将看到一个关于启用评论的页面。
如何排序和隐藏文章？发布日期不在文件名中怎么办？
如何自定义我的站点？
请参阅Quarto 文档
如何设置 RSS Feeds 并向我的站点添加特定功能？
请参阅Quarto 文档
nbdev 与 Quarto 有什么关系？.
如果只是为了写博客，没有任何关系！您可以直接使用 Quarto 写博客，无需担心 nbdev。过去，我们维护了一个与 nbdev 相关的项目称为 fastpages，现在推荐用户迁移到 Quarto。此外，nbdev 构建在 Quarto 之上，这意味着很多功能是相似的。最后，您可以将博客集成到 nbdev 项目站点中，这在本节中有所讨论。
对于独立博客，为什么推荐我们使用 Quarto，我可以直接使用 nbdev 吗？
nbdev 构建在 Quarto 之上。对于博客目的，如果您只想写博客，添加 nbdev 的额外好处很小。我们决定保持简单，让人们直接使用 Quarto，而不是尝试为博客抽象 Quarto 的各个方面。此外，了解一些 Quarto 知识对使用 nbdev 也非常有帮助！最后，您仍然可以在博客中使用一些 nbdev 功能，这些功能列在本文中。