Blog搭建经验
Blog搭建经验
目前使用Jekyll搭建博客。
之前用过Hexo，但语法和标准Markdown差太多了，用起来很麻烦，一些踩坑经验放在下文，但不推荐使用Hexo。
Jekyll
依赖Ruby，本地调试需要安装Ruby环境，具体参考Jekyll官方文档。
网站主题大部分都功能单一，特别缺乏Table of Contents功能。有的有也只能在文章头部，跳转很不方便。我现在使用Chirpy主题，TOC功能满足我的要求。而且使用它的Chirpy Starter作为起点，基础配置就都有了，github workflow也配置好了，很方便。
本地调试只需要：
1
2
bundle install
bundle exec jekyll serve
Post Url
Jekyll 默认的 post 文章间链接方式是使用 [link name here]({% post_url YEAR-MONTH-DAY-title %})，这种写法在 Markdown 里不直观，且只能在 Jekyll 构建后网页端生效，VSCode 本地无法跳转。
直接用Markdown的相对路径写法，网站链接就会变成当前网页再加相对路径，导致无法访问。使用插件jekyll-relative-links可以解决这个问题，直接用Markdown相对路径写法即可。但注意一定要带文件后缀名，不然转换会失败。
Hexo（不推荐）
Hexo的创建使用不多赘述。注意，先搞清楚hexo是否满足书写要求，可能你需要的是sphinx。
Hexo通过hexo d手动发布到github，本质是把编译好的文件推送到github，deploy的目的地分支就是网站目录。也就是deploy后在本地可以看到的.deloy_git。
我个人使用了另一个branch来保存hexo项目的原始文件，也就是_config.yml，md文档等等。
Q&A
名字解释： <root>: 指的网页根目录，或者说是hexo deploy到的repo分支根目录。
Q: 遇到网站repo中路径是存在的，比如<root>/categories/index.html确实存在，但是浏览器点击却是404？ A: 可以自行访问尝试下<root>/categories/或者全路径，看看index.html是不是有问题。如果这样就能访问到正常页面，那么问题大概就是缓存了。你可以换个浏览器快速检查下，或清除该页面缓存重试下。
附赠-chrome清除单个页面缓存
chrome的开发者工具-setting中Network-Disable cache(while DevTools is open)，此选项打开后，在你想要调试的页面，打开开发者工具，就不会出现一些奇怪的缓存现象了。
Hexo cmds
1
2
3
4
5
6
7
8
9
10
apt install -y npm # if error, check below. ubuntu20.04 npm is too old, need to upgrade.
npm install -g hexo-cli
cd <blog-source>
npm install
# if ERROR Package xxx is not installed
npm install xxx
hexo new draft <draft_name> # just the name, no .md
# writing, writing, ...
hexo publish <draft_name>
1
hexo clean && hexo d
If you want to delete a post, just delete it in the source folder.
Localhost debug way:
1
hexo s --debug
Hexo writing
link to another post
Ref Include Posts.
在 Hexo 中可以这样写（注意：下方为 Hexo 语法，Jekyll 不支持，仅作示例）：
1
{% post_link 要跳转文章md文件名(不要后缀) %}
pics
hexo默认的图片格式不是markdown的语法，想要写md时预览，可能需要vscode安装插件Hexo Utils。 但有个方法可以继续用md的image格式（https://hexo.io/docs/asset-folders#Embedding-an-image-using-markdown）：
1
2
npm i --save hexo-renderer-marked
npm i --save hexo-asset-link
然后确保_config.yml中有（一般都有）：
1
2
3
4
post_asset_folder: true
marked:
prependRoot: true
postAsset: true
NPM install
npm用nvm来装，方便切换node版本。hexo需要12及以上的。
hexo version可以查到相关依赖的version。
然后又可能遇到npm rebuild node-sass很慢的问题，卡在github上下载node-sass了。可以换下源试试，npm i node-sass --sass_binary_site=https://npm.taobao.org/mirrors/node-sass/。
hexo-renderer-sass有点旧，node版本高了就不兼容了，升高sass版本就没有问题了。
我想要个block admonition，但没有插件能做到解析’{note}‘这种。只能改用现有语法，缺陷是vscode没法preview，只能deploy/server后看效果。最终还是决定使用hexo next主题自带的。preview的问题不大，用的频率不会太多。切换sphinx有点麻烦，hexo配reStructuredText插件，例如hexo-renderer-pandoc，没成功，据说这个插件也比较大，deploy会慢。
Next Dark主题
@media (prefers-color-scheme: dark) {}删了，只保留内层。否则，会考察OS或浏览器的主题，可能不能dark。强制弄黑，保护眼睛。