Hexo

Hexo - A fast, simple & powerful blog framework

hexojs/hexo stars forks updated release release date

Hexo is a fast, simple and powerful blog framework. You write posts in Markdown (or other markup languages) and Hexo generates static files with a beautiful theme in seconds.

Themes

Stellar

Stellar：开始您全新的博客之旅 - XAOXUU

xaoxuu/hexo-theme-stellar stars forks updated release release date

Stellar 是一个内置文档系统的简约商务风 Hexo 主题，支持丰富的标签和动态数据组件，帮助您简单从容地应对各种表达需求，十分推荐内容创作者使用 Stellar 开始您全新的博客之旅。

Issues / Notices

关于 Notes

Hexo 还是以（博客）文章（posts）为核心的，虽然 Stellar 独创了文档（wiki）系统，也可以基于其实现笔记（notes）的功能，但还是有很多地方对非文章（posts）不是那么友好。

  • （博客）文章（posts）：一般是持续增加新页面，以时间排序。虽然也可以再更新，但一般后续更新只是小修小补。这个天生带着很强的创建时间属性。
  • 专栏（posts + topic）：本质还是文章（强调时间顺序性），但增强了同专栏下文章的前后关联关系。
  • 文档（wiki）：更像是项目级别的 wiki，强调目录树（手动指定顺序、分组）。
  • 笔记（notes）：虽然目前是基于 wiki 实现，但还是有极大区别的，应该更像以前的 MediaWiki，或者常见的桌面或在线笔记软件那样。文章之间的引用关系会更丰富，不像文章那样强调创建时间，而且内容一般是持续不断更新的。

License in Wiki

Stellar：如何使用文档系统 # 显示许可协议 - XAOXUU 中提到可以给 wiki 开启 license 显示，或者指定协议内容。但实际没有显示出来。

  • 2024-05-08: 提了 PR 进行修复。

引用图片等 assets

Asset Folders | Hexo 中提到可以开启 post_asset_folder 以便让每篇文章的资源文件存放在其旁边的同名目录中，但这个对非文章（posts）类型的页面不起作用，包括 Stellar 中的 wiki。

理想状态：不管是文章（posts）还是普通页面（pages），都可以优雅地引用与其相伴的资源文件，对于图片资源，最好还能直接在 Visual Studio Code 的 Markdown 预览中也能显示出来。

调整 hexo 配置 _config.yml:

引用图片可以有两种语法，一种是 Markdown 语法 ![alt](src)，另一种是 Hexo 提供的标签插件 {% asset_img slug [title] %}。

1
2
3
4
post_asset_folder: true # https://hexo.io/docs/asset-folders#Post-Asset-Folder
marked: # https://github.com/hexojs/hexo-renderer-marked
  prependRoot: true
  postAsset: true

Visual Studio Code 中安装扩展 Hexo Utils - Visual Studio Marketplace。

文章（Post）中引用图片

Syntax Slug / Src Hexo VS Code
Markdown filename ✓ ✗
Markdown post-slug/filename ✗ 变成绝对路径了 ✓
Tag Plugin filename ✓ ✓

笔记（Note）中引用图片

Syntax Slug / Src Hexo VS Code
Markdown notes/note-slug/filename ✓ ✗
Markdown ../notes/note-slug/filename ✓ /../ 没影响 ✓
Tag Plugin filename ✗ 连 <img> 都没有 ✓
Tag Plugin notes/note-slug/filename ✗ 连 <img> 都没有 ✗
Tag Plugin ../notes/note-slug/filename ✗ 连 <img> 都没有 ✓

其他页面可能类似，待确认。

Mermaid

当 Mermaid 图比较宽的时候，在手机上展示不全，且无法缩放、滑动。比如 这里。

明暗主题色

目前可以通过配置文件指定 prefers_theme 是自动、亮色、还是暗色。还需要能够通过页面上的按钮手动切换的功能。

  • 2024-04-28: 提了 PR 以支持运行时切换明暗。

Stellar 主题增加 Notebook（笔记本）支持

概念和预期效果

  • Notebooks: 指笔记本的列表。默认可以支持任意多个笔记本。
  • Notebook: 笔记本。
  • Note: （一篇）笔记，对应于 Hexo 中的一个 page，具体来说是一个在 front-matter 中指定了归属的 notebook 的 page。一篇笔记只能归属于一个笔记本。
  • Tag: 笔记标签。在一个笔记本内，所有的笔记可以通过 tag 来组织。一篇笔记可以对应任意多个 tag（也可以没有）。tag 支持层级结果，通过 / 分割，如 it/web 表示在 it 标签下有个 web 子标签。

整体类似于 Bear 中的结构。Bear 中的数据相当于一个笔记本，笔记、tag 都是对应的。因为本身就是以网站形式呈现，暂时也就不支持归档、回收站等功能。

会有以下一些路由：

  • /notebooks: 笔记本列表页。具体的地址可以通过配置修改。leftbar 中可以放所有笔记本中最近更新的内容。主体部分是笔记本列表，类似 wiki 列表。
  • /notebooks/xxx: ID 为 xxx 的笔记本的页面。具体地址可以通过该笔记本的配置文件修改。leftbar 可以放该笔记本的标签树、最近更新的内容（需要么？）。主体部分是笔记列表，类似博客列表页。无限加载最好，但可能不适合于静态站点，那就分页或者想博客的归档页那样列出所有。
  • /notebooks/xxx/tags/ttt: xxx 笔记本的 ttt 标签页面。跟笔记本页面类似，但标签树会高亮当前标签，最近更新（需要么？）和笔记列表都限定在该标签内。
    • 父标签包含所有子标签里的笔记。比如一篇笔记的标签是 t1/t2/t3，那么在 t1 和 t1/t2 中都可以看到该笔记。
  • /notebooks/xxx/yyy: xxx 笔记本的 yyy 笔记页面。主体部分是该笔记本身。

笔记本页或笔记本标签页，笔记的排序，至少支持按更新时间倒序排列。可以考虑允许配置按照更新时间、创建时间、标题的正序或倒序排列。可以支持笔记置顶，置顶的笔记始终排在最前面。

代码结构和处理流程

scripts/generators 目录中增加 notebooks.js 以定义 notebooks 相关的路由，如 /notebooks、/notebooks/xxx、/notebooks/xxx/tags/ttt 等。

需要在这之前，对 notebooks 相关信息做预处理，在 scripts/events/lib 中增加 notebooks.js，并在 scripts/events/index.js 中引用（添加到 generateBefore 事件上）。这个文件要遍历 pages，把 notebooks 信息整理出来，并计算出每个 notebooks 中标签树的信息（标签本身、标签的层级关系、标签和页面的关联关系等）。

页面主体部分的渲染，在 layout 目录中增加 notebooks.ejs 渲染笔记本列表页，增加 notes.ejs 渲染笔记列表页（笔记本页和选中的标签页）。

笔记的渲染跟普通 page 类似，在内容底部增加该笔记的 tags 列表（增加 layout/_partial/main/notebook/note_tags.ejs 文件）。点击某个标签可以跳转到对应的标签页（归属于该标签的笔记列表页）。

侧边栏最近更新能支持限定在所有笔记本（在笔记本列表页）或当前笔记本 或当前标签（待定）。

搜索框能支持限定在 所有笔记本、 当前笔记本 、或当前标签。

标签树组件，在 layout/_partial/widgets 中增加 tagtree.ejs 用来渲染标签树，还需要修改 layout/_partial/sidebar 中相应文件来应用在配置文件中定义的不同 layout 下的 sidebar 配置。

  • 2024-05-13: 提了 PR，基本完成初版笔记系统。

快来参与讨论吧~