如何在 Hexo 中使用助记媒介 Orbit

本博客本分内容翻译、改写自 Orbit 官方文档和 Github 项目主页

Orbit 可让您在写作中插入基于间隔重复的助记卡片。如果使用得当，这些助记卡片可以帮助人们可靠地记住他们所阅读的内容，更轻松地理解复杂的主题，并随着时间的推移与想法保持联系。本文是基于 Hexo 和 Mkdocs 两个静态博客和 wiki 平台来使用 Orbit 的。Orbit 是笔者的新形态网络教材的主要实践基础，可见后续文章。

入门

开始使用 Orbit

Orbit 被设计用于在网络上的任何位置工作。可以使用可在任何 HTML 页面中使用的 Web 组件嵌入 Orbit 。设置很简单：添加一个 <script>标签，就能在页面上的任何位置使用特殊标签<orbit-reviewarea>和 标签来插入助记卡片。但这里笔者不使用这个方法插入 Hexo 博文，而是直接在.md文件中直接写入 html 片段以降低发生意外的风险，这也使其更利于维护。下面的代码片段例子分别演示了普通的卡片、带图片的卡片和使用 LaTeX 跨行与行内公式的卡片：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<html>
  <head>
    <script type="module" src="https://js.withorbit.com/orbit-web-component.js"></script>
  </head>
  <body>
    <orbit-reviewarea color="cyan">
      <orbit-prompt
        question="安迪的实验性记忆媒介平台的名称是什么？"
        answer="Orbit"
      ></orbit-prompt>
      <orbit-prompt
        question="这是哪种量子门？"
        question-attachments="https://docs.withorbit.com/toffoli.png"
        answer="A Toffoli gate."
      ></orbit-prompt>
      <orbit-prompt
        question="给定一个直角三角形，其两直角边长分别为 $a$ 和 $b$，那么如何计算斜边 $c$ 的长度是多少？"
        answer="$$c = \sqrt{a^2 + b^2}$$"
      ></orbit-prompt>
    </orbit-reviewarea>
  </body>
</html>

这是代码将生成的复习区的实时演示：

如果博客或电子教材的读者尚未登录 Orbit，系统将提示登录。他们回答的助记卡片将保存到他们的帐户中。下次有重新复习助记卡片时，他们将收到电子邮件通知，并提供指向 Orbit 卡片界面的链接，该界面显示从他们访问过的所有网站汇总的助记卡片。

助记卡片部分支持简单格式化

question和answer属性支持 Markdown 格式。可以使用内联样式和多个段落。并可以通过将内联数学包含在 $ 符号中并将显示块包含在 $$ 符号中来使用 LaTeX，如上面的示例所示。保留的 HTML 字符（如 >、& 和 <）需要使用实体编码[1]进行转义：例如，> 写为>。

question-attachments您可以通过使用 or 属性 指定 URL，将图像（PNG、GIF）附加到问题或答案answer-attachments，如上例所示。如果存在附件，您可以省略question或属性。answer请注意，您必须提供绝对 URL，而不是像/toffoli.png. 您的图像将缓存在 Orbit 的服务器上，对其内容的更改可能无法可靠地传播。如果需要更新图像，还应该更改其 URL。

卡片颜色

复习卡片有一个color属性。每个站点都可以选择其 Orbit 助记卡片的颜色。然后，当读者查看来自多个站点的助记卡片时，他们会看到以您选择的颜色呈现的助记卡片，从而提供一些上下文。支持的颜色值有： red、 orange、 brown、 yellow、 lime、 green、 turquoise、 cyan、 blue、 violet、 purple和 pink。

Orbit 依赖于页面元数据

当读者在后续复习中查看助记卡片之一时，Orbit 通过显示包含这些助记卡片的页面链接来提供上下文。该界面还可以显示按源页面分组的进度。确保元数据正确非常重要。以下是 Orbit 从您的页面提取的信息以及如何对其进行自定义：

  • 页面标题： Orbit 将使用og:title OpenGraph元标记（如果页面上存在）。如果不存在，它将使用标签的值 <title>。
  • 规范 URL：如果可以从多个 URL 查看您的内容，则务必将规范 URL 告知 Orbit，以便它可以正确对助记卡片进行分组。Orbit 将使用 规范链接元素 （如果可用）；否则，它将使用页面 URL。
  • 站点标题： Orbit 的界面可能会对站点不同页面的助记卡片进行分组。为了标记该组，它将使用 og:site_name OpenGraph元标记（如果存在）。

下面是一个<head>演示这些值的示例：

1
2
3
4
5
6
<head>
    <title>肥胖——ourworldindata</title>
    <link rel="canonical" href="https://ourworldindata.org/obesity">
    <meta property="og:title" content="肥胖">
    <meta property="og:site_name" content="ourworldindata">
</head>

在单个页面上包含多个复习卡片集合

<orbit-reviewarea>在同一页面上 使用多个标签是很常见的，每隔几百个词就交错使用它们。Orbit 目前假设网页上出现的所有复习卡片集合都应被视为同一内容的一部分。这对于长格式内容来说效果很好，但会在例如在一个大页面上显示许多帖子内容的博客布局中产生令人困惑的结果：Orbit 最终将允许在这里进行更细粒度的配置。

如果一个页面中有多个orbit-reviewareas，则可以color通过在页面<head>标记中指定颜色来避免在每个页面上重复该属性，如下所示：

1
2
3
<head>
  <meta property="orbit:color" content="violet" />
</head>

测试您的助记卡片

当编写和修改助记卡片时，您可能需要启用 “测试模式”，该模式不会将您的操作保存到您的帐户中。为此，请附加?orbitDebug到您的 URL。例如，如果您正在查看http://you.com/test，请将浏览器指向 http://you.com/test?orbitDebug。?如果 URL 中已有 a ，请添加&orbitDebug，例如 http://you.com/test?id=4变为 http://you.com/test?id=4&orbitDebug。如果您的网络服务器重定向http://you.com/test到 http://you.com/test/，您将想要访问 http://you.com/test/?orbitDebug。

用 Orbit 写出好卡片

通过将 Orbit 引入博客或教材写作中，不仅仅是 “添加” 一组抽认卡：您正在学习用一种集成了散文和轻量级练习的新媒介进行写作。该系统只能按照您编写的助记卡片运行，而且要写好它们似乎很困难。本质上，你试图将你在句子中描述的所有重要想法编码成问题，当读者思考它们时，这些问题将强化预期的材料。

Andy 首先为个人学习实践创建了一个编写良好助记卡片的指南： 如何编写良好的助记卡片。为其他人编写好的助记卡片更具挑战性。一旦 Andy 更好地理解了这些注意事项， Andy 将编写有关该主题的后续指南。与此同时，以下是一些可能有用的资源：

在 Hexo 和 Mkdocs 中使用 Orbit

Hexo 是可以部署在 GithubPages 上的快速、简洁且高效的静态博客框架，是本博客正在使用的框架。在 Hexo 中使用 Orbit 非常简单，在博客博文源文件.md中写入上文的 html 片段即可实现。但请注意使用<html></html>包裹以避免出错。

MkDocs 是一个快速、简单且华丽的静态站点生成器，适用于构建项目文档。笔者用它来发布工具书和参考材料的翻译和新形态教科书。与 Hexo 中的方法相同，在源文件.md中写入上文的 html 片段即可实现。Orbit 将是网络知识切实传递的最重要工具，它提供了新的手段使被教育者完成“学习 - 记忆 - 应用”的中间一环。[2]

注释和参考资料

  1. Wikipedia - Character encodings in HTML ↩
  2. Andy Matuschak and Michael Nielsen, How can we develop transformative tools for thought? October 2019 ↩
独立教程 间隔重复和知识管理
#写作 #博客 #文档翻译 #教材写作 #认知方法
如何在 Hexo 中使用助记媒介 Orbit
http://sutangar.github.io/2024/01/25/如何在 Hexo 中使用助记媒介 Orbit/
作者
Sutang
发布于
2024年1月25日
许可协议