github上的静态博客方法

如何使用minimal-mistakes框架方便地在github上部署静态博客。

选型

• 手工搭建
  参考github pages说明、教程, 写html
• 使用博客框架
  • github
    参考自动页面生成器
  • hexo
    支持Markdown，使用Nodejs速度快，缺点：本地将markdown转换为html
  • jekyll
    支持Markdown在线编辑，使用Ruby。bundle会监控文件修改自动更新。这个教程不错
• 开发好的pages框架
  jekyll系的minimal-mistakes,

使用步骤

安装

将minimal-mistakes fork到自己用户名zerodollar.github.io， git clone 到本地，进入本地目录

cd zerodollar.github.io
sudo gem install jekyll bundler
bundle install
bundle exec jekyll serve

公网访问https://zerodollar.github.io，本地访问http://127.0.0.1:4000
安装gem组件时，有错误查看对应组件帮助，比如nokogiri编译失败

brew install libxml2
bundle config build.nokogiri --use-system-libraries   --with-xml2-include=$(brew --prefix libxml2)/include/libxml2
bundle install

目录结构参考Structure

配置minimal-mistakes

参考配置

• 定制私有信息
  locale 语言、title 主题、name、description、repository、author信息等
• 打开搜索 （主页右上角)

  search: true
  

• 导航 修改navigation.yml， 注意url部分要在_config.yml的collections进行配置，否则访问时找不到url。
• 评论系统
  业界老大disqus被墙，翻墙有教程。Disqus去Disqus官方网站 注册账号，在setting中选择add disqus to site，填写 Site URL，Site Name，Site Shortname。在<名字>.disqus.com中setting/advanced的Trusted Domains添加域名。 样例使用了staticman_v2，这是一个支持github和jekyll的非常好用的静态博客评论，评论和博客在一个站点上。 参考[STATICMAN指导](https://staticman.net/docs/index.html)
  • github配置
    博客项目Settings/Collaborators添加staticmanapp，访问https://api.staticman.net/v2/connect/zerodollar/zerodollar.github.io/， 生效请求。
  • jekyll配置
    staticman.yml（staticman会读取该文件）中path修改成_data/comments目录下，并建立_data/comments目录。
    moderation: false 表示不需要审批自动提交
    comments: true 注意repository配置，否则可能返回错误GITHUB_READING_FILE
  • reCaptcha 防止机器攻击。
• RSS订阅 访问Burn a feed right this instant
• 分享
  百度分享 ？
• 自动生成分类目录
  参考Breadcrumb

  mv docs/_pages/  .
  rm _pages/about.md
  

• 删除多余文件

  rm -fr .editorconfig .gitattributes .github 
  rm -fr  ./docs ./test CHANGELOG.md 
  rm -fr  README.md screenshot*png
  

• 升级

  git remote add upstream https://github.com/mmistakes/minimal-mistakes.git
  git pull upstream master
  

Jekyll原理

参考Jekyll中国，是将纯文本转换为静态博客网站，核心就是一个Ruby实现的文本转换引擎：任何标记语言（比如Markdown），Jekyll套入布局中，最终生成静态页面。

文件/ 目录	描述
_config.yml	配置数据
_drafts	草稿，未发布的文章， –drafts选项支持预览
_includes	用于重用
_layouts	用于布局
_posts	文章YEAR-MONTH-DAY-title.md
_data	预置的网站数据
_site	转换好后的页面
.html .markdown .md .textile	含义yaml头信息，都会被转换
其他文件	拷贝到_site中 assets中文件引用:[下载 PDF](https://zerodollar.github.io/assets/xxx.pdf)

头信息：设置预定义、自定义的变量，在文档中用Liquid标签来访问这些变量

变量名称	描述
layout	使用_layouts下的对应模板文件
permalink	修改默认的URL：/year/month/day/title.html
published	不展示
xxx	自定义变量，模板通过引用
date	覆盖文件名中日期
category categories	除了文件夹分类，指定其他的1~n个分类属性
tags	类似categories

excerpt_separator，文章第一次匹配前部分为摘要 集合Collections，除了文章特性，还有特有的属性和命名空间