• Why Github?
  • Team
  • Enterprise
  • Explore
  • Marketplace
  • Pricing
Sign inSign up
Watch996
Star102.4k
Fork61.8k
Branch: working.beex.help
Switch branches/tags
Branches
Tags
  •  
K / Beex 的设计哲学(Best Practices).md
Go to Mobile Clone
加载中...
到移动设备上浏览
67 lines 6.61 KB
First commit on 11 Jun 2020

    设计主旨

    1. Beex 是我在笔记实践中的产物,所以在设计上它并不是以实现通用接口优先,而是以方便人类使用优先。在下面的每一条里,你都将看到这一思路的体现。

    2. Beex 将保持“尽量小巧”、“可增量构建”、“支持多个源目录”三个特性。

    3. 写论文或者写书应当使用 LaTeXPandoc。Beex 着重解决源目录的分散化和基本预览两个问题。

    我的最佳实践

    翻页

    Beex 的列表页没有分页,当某分类文章过多的时候,你应当考虑增加分类或标签。分类的作用类似文件夹,Windows 的资源管理器有翻页功能吗?如果有,你真的愿意点很多次翻页按钮去找资料吗?

    增量构建

    有时候可能有一些内容在发布后又需要隐藏,为了达到完全同步全部链接和附件的目的,通用型引擎会重置整个目标目录,这有三个连锁缺点:

    1. 放弃了增量构建的能力。(理论上可以通过为全部文件建立索引实现,但通用型引擎索引全部文件会过于复杂,我看了社区讨论,甚至都没有开发团队准备实现它。我也因此开始开发 Beex。)
    2. 随着文章越来越多,每次的构建时间会越来越慢。
    3. 如果使用网盘同步生成的文件,不支持增量同步的网盘每次都要重传整个目录,这更慢......

    所以我在增量构建和私人文档保护之间找了一个平衡:

    • BeexMeta 内有一个 hidden 字段,当其值被设置为 1 时,这篇文章会在 target 目录中被删除。
    • 对于已经渲染过的文档,转为私人文档时,附件不做处理。如果你需要删除 target 目录中的附件,请手动删除。
    • 对于从未渲染过的私人文档(也就是从新建就被设置为 hidden: 1 的文档),附件也不会输出到 target 目录中,所以不用管它们。

    其实 Beex 是可以做到同步删除已发布的附件的,只是这样生成速度会变慢,不划算。

    多站点

    几种需求:

    • 你关注的领域可能有多个,文件的位置散落在硬盘不同位置,这时就需要能将多个目录设置为源目录,而不是把它们复制到同一个目录里。
    • 将私人文档和公开文档分成不同的目录,公开目录的内容发布到网上,私人文档渲染成网页格式在本地浏览。同样也是需要能够设置多个目录为源目录。
    • 有多个网站需要分别生成。

    如果不支持多站点,就要在每一个源目录中复制一份生成器的可执行文件,或者在命令行中来回切换目录。Beex 从一开始就为支持多站点而设计。

    路径

    解耦了 .md 文件的路径、文件名、标题和 target(目标路径)。当你的源文件越来越多需要重新整理文件夹时,你可以放心地移动源文件,而不用担心影响输出的位置。

    附件

    只要一个文件夹内只有一个 .md 文件,本文件夹的其他文件就可以保持与 .md 的相对位置,随时可查看、编辑附件。如果将所有附件放在一个特定的文件夹里统一发布,素材多了以后完全无法维护。

    另外,一个目录内有多个 .md 文件时,也可以将所有附件复制到每一个 .mdtarget 目录中,但这个策略很浪费空间,所以不采纳

    BeexMeta

    我不希望在写笔记时,为了输入一些元信息而敲击很多引号、换行、缩进等等,所以 BeexMeta 不仅没有使用 YMAL 或 TOML 等语法,甚至是不区分数据类型的,全部是以 : 分隔的字符串键值对。

    categoriestags 以中英文两种逗号切割列表。作为一个主要使用中文输入法的人,为了输入一个标签列表而频繁切换输入法也是麻烦的,尤其是这两个是元信息里被手工编辑得最多的字段。

    逻辑值的 TrueFalse10 代替,同样是为了减少要输入的字符。

    为了让任意 Markdown 引擎都能直接渲染源文件,采用了 HTML 注释语法(<!-- -->)包裹 BeexMeta

    Short

    short 类似常见的 ID,是一个自增整数,不过全局只有一个序列。这样设计的理由是 Beex 支持多站点,但实际上我们的文档并不是像网站系统一样保存在相互隔离的数据库中,有时我们需要将一些文件从一个文件夹移动到另一个文件夹。

    如果在 BeexMeta.target 中使用 short 作为唯一性标识,那么在多个站点的源目录之间迁移文档时,就不用担心构建时 target 冲突。比如我使用 short 来生成文章、分类、标签的 target

    如果你对这种不连续的 ID 感到不舒服,只要不在各个 format 里使用,你就可以当它不存在。

    已知问题

    • 如果将多站点输出至同一个 target 目录中,它们会互相覆盖列表页和首页:#9015
      • 我不确定会不会在未来增加对这一功能的支持,这是一个极少见的需求。

    标签的 slug

    有时候可能会修改标签,或在新文章用新的写法,这时候我不希望影响以前的固定链接,比如 sql 变为 SQL 时,比如 collections 改为中文 收集 时。

    这需要对标签的名称和 slug(生成 URL 时使用的名字)进行某种映射。(在本站我使用的是 short。)

    设置方式参考 Beex 配置