建立11ty过程的备忘录

• 02 March 2025
• Axe

模版

网站的基底采用官方的11ty-base-blog。
网站建立在codeberg上，使用codeberg pages功能。
主题的主要灵感来自hugo的theme：cactus. （但它已经缺乏维护了。）和good enough.
blog的写作形式采用markdown，准确来说是markdownIt的default配置。
原始文件的仓库和pages仓库是分开的。两者互为父子关系，因为pages只需要上传一些导出页面。

11ty

11ty是一个（可以）零配置的静态博客生成器。
选择它的原因是因为对文件的掌控欲。这里对比的产品有：tiddlywiki, feather wiki, hugo(cactus), pika, quartz, jekyll(just the doc).

11ty给人一种充足的掌控感，你能充分了解文件之间的流动，博客的架构，每个字符出现的原因，深入骨髓。

11ty的文件主要由以下几方面构成：

• 配置脚本
  • eleventy.config.js：整个项目的配置。包括诸多插件的引入，对文件夹目录的定义。
  • .editorconfig：不知道，但看着很厉害。
  • bun.lock：bun的module的版本指定。是的我在用bun而非node.js。
  • package.json：似乎也是bun需要的，其中还定义了一些命令。
  • gitignore：git的忽略列表。
  • _data/metadata.js: 定义网站的一些信息。
  • _data/eleventyDataSchema.js：不知道，似乎很关键。
• 布局脚本
  • 由 nunjcks 文件（.njk）定义。这种格式非常方便，可以在一个文件里随意的嵌套html，引用变量，定义css，引入js脚本等等。
  • 以 _includes 文件夹为主。其中定义了每个页面展示时，导航栏和页脚。
  • 而content中的一些页面则定义了导航栏中四个页面的布局。文件开头的 eleventyNavigation 属性，则标记了该文件在导航栏中。
• 内容
  • 在 content/blog 里。
  • 每篇文章都可以是单文件，也可以是独立的文件夹，用来存放图片。
  • 文章开头的属性是必须的：title, description, date, tags, draft. 其中 tags 不能是中文。同时，文章的文件名、文件夹名也不能是中文。
• 装饰
  • 一些css文件，以 public/index.css 为主。其余的分散在各个njk文件里。
• 导出
  • _site 文件夹。会同步到 codeberg pages 的仓库里。
  • 值得注意的是，11ty 的导出是所有文件都会更新——更新build时间——因此上传列表会有些奇怪。

Codeberg Pages

codeberg pages的逻辑和github pages略有不同。
github pages是每个库对应一个 username.github.io/repository.
codeberg pages则是所有pages在一个库里，不同的分支代表不同页面，即 username.github.io/brunch.
感觉codeberg的更合理一点，因为page就是page，不需要太多库。（当然，在设置domain的时候，发现似乎可以有不同的repository。）

codeberg是一个自由开源的在线git服务。要求里面所有项目都是开源的（当然也可以有私有项目，似乎和理念有些冲突。待进一步确定）。国内服务较为稳定，功能全面（讨论，请求，标签，分支）。对应github action的功能似乎是有的，不过还没细看。

其中 domain 功能，也就是将自定义域名解析到 codeberg pages 上，请参考官方指南：https://docs.codeberg.org/codeberg-pages/using-custom-domain/

• 腾讯云的域名后台，需要转到dnspod上才能添加dns记录。
• .domains文件内需要填写自定义域名和codeberg pages域名。具体内容取决于dns记录的方式。
• build命令：bunx @11ty/eleventy
• 测试命令：bunx @11ty/eleventy --serve

Markdown

在配置文件里，手动引入了 markdownIt 来解析 markdown 文件。
采用默认规则（和gfm类似），同时开启了默认规则的所有可选规则。其中的break选项为单回车换行。

markdownIt的优势在于，有大量的扩展可以使用，已经安装有 markdown it emoji。具体可参考 https://www.11ty.dev/docs/languages/markdown/#add-your-own-plugins

• 有些插件只能使用 CommonJS 导入。需要改变导入的写法，具体可参考 markdownItEmoji 插件，或查找ai。

待办

-[] 目前文章内的css文件还未得到修正，需要在使用中逐步增加。
-[] 希望引入mdx，在文章中加入可交互的表格。
-[] 将blog、project、对外内容分开。需要每一项做单独的postlist
-[] 替换markdown为asciidoc

• ← Previous
  客厅