stidio.github.io

stidio.github.io

采用Jekyll+GitHub Pages搭建的个人博客站点; Jekyll Theme; 基于kramdown+Rouge+Monokai修改的代码高亮着色方案;

Demo Download

使用GitHub Pages+Jekyll搭建个人博客

概述

GitHub Pages 免费无限容量的站点数据托管工具(国内访问速度较慢)，内置Jekyll服务，能将特定名称的代码仓库动态编译为静态网页

Jekyll 基于Ruby的静态网页生成系统，采用模板将Markdown(或Textile)文件转换为统一的网页

统计 统计工具主要是为了方便查看站点的访问情况，目前支持百度统计和Google Analytics(可同时使用)

评论 评论工具可以为静态页面增加评论和分享功能，目前支持国内的多说和国外的Disqus

本文将重点介绍标注 　　　 的必选项目，未标注的可选项目请按照给定地址自行注册即可

建立GitHub Pages站点

  1. 在GitHub上建立一个以 .github.io 为后缀的和你帐号名一样的代码仓库，如我的帐号是:stidio，则建立的仓库名为:stidio.github.io, 同时在底部Add .gitigore选择Jekyll模板，这样Jekyll产生的临时文件，例如_site目录就不会添加到源代码管理中，当然你也可以以后手动配置:

  2. 将该代码仓库克隆到地:

    $ git clone https://github.com/stidio/stidio.github.io

  3. 创建一个测试页面并推送:

    $ cd stidio.github.io
$ echo "Hello World" > index.html
$ git add --all
$ git commit -m "Initial commit"
$ git push -u origin master

  4. 浏览器中输入stidio.github.io，如果一切正常，你应该能看到一个显示Hello World的页面.

请将以上的 stidio 替换为你申请的帐号名

安装配置Jekyll

  1. 安装Jekyll:

    $ gem install jekyll

  2. 创建或使用模板, 创建模板使用 jekyll new name 命令，但创建出来的测试模板极其简陋，在这里我主要介绍使用第三方主题，在 这里 你可以找到各种主题，当然你也可以直接使用我的博客模板:点击下载，下载后解压到本地代码仓库目录，并运行 bundle install 命令安装项目依赖包.

  3. 运行 jekyll serve 启动本地测试服务器，Jekyll默认使用4000端口，如果被占用，可以使用 jekyll serve -P $PORT 指定其他端口，如果本机从没配置过Jekyll，可能会给出 cannot load such file -- bundler 的错误，运行 gem install bundler 即可解决，如果还是出现包缺失的错误，可以从以下两点排查：

    • Gemfile文件未添加指定包
    • 运行环境冲突，可以运行 bundle exe jekyll serve 执行，或者运行 sudo bundle clean --force(该命令会对全局环境造成影响，小心使用) 强制清理无关包后重新运行

  4. 在浏览器中输入 127.0.0.1:4000 进行本地预览

Ruby包管理工具介绍

  • gem 全局包管理工具，类似于Python的pip, Node.js的npm -g

    • gem install 安装组件
    • gem install -v 安装特定版本
    • gem list 列出已经安装组件
    • gem sources -a 添加源
    • gem sources --remove 删除源

  • bundle 项目包管理工具，可以理解为一个独立的运行环境

    • bundle update 更新项目依赖包
    • bundle install 安装项目依赖包
    • sudo bundle clean --force 强制删除不相关的包
    • bundle exe 在指定环境中运行

使用我的博客模板

  1. 按照注释说明修改 _config.yml 配置文件
  2. 删除文章目录 _post/ 和文章图片目录 images/posts/ 下面的所有内容
  3. Enjoy!

我的模板在 leopardpan 基础上进行了修改，主要改进了以下内容:

  • 统一风格，给关于，标签页面添加了标题栏
  • 添加分割改进文章列表的多标签显示
  • 修正了一些翻译不全的文字
  • 代码颜色高亮支持，综合了Pygments monokai方案和Rouge monokai.sublime方案，点此查看
  • 底部统计和版权排版对齐
  • 更新Jekyll及其依赖包到最新版本
  • 修正jekyll-sitemap加载失败的问题
  • 支持GFM形式的Markdown Codeblock解析

如果喜欢请Star!，谢谢!

编写文章

文章为Markdown格式，请使用.md作为后缀名，有以下两个文章目录：

  • _posts 文件名格式为：YEAR-MONTH-DAY-title.md
  • _drafts 草稿目录，文件名格式为：title.md，即不加日期前缀，如果需要预览草稿，使用 --drafts 选项运行 jekyll serve 或 jekyll build

* 尽量避免使用中文文件名, 具体目录结构请参考: 官方文档

每篇文章都必须以参数：

---
layout: post
title: 使用GitHub+Jekyll搭建个人博客
date: 2016-11-21 11:29:08 +0800
tags: [Jekyll, GitHub, 教程]
---

作为头部信息，layout为布局格式；title为显示的文章名；date为显示的发布日期；tags为文章分类标签

文章正文采用Markdown编写，如果不熟悉可以查看: Markdown 快速入门；强烈建议遵循Markdown Lint，规范有一些对书写文章不友好的地方，我做了调整，以下是我的Visual Studio Code的配置文件:

"markdownlint.config": {
        "MD002": false,                                 // 禁用文章开头必须为H1标题栏
        "MD001": false,                                 // 禁用严格的标题层级关系(H1->H2->H3...)
        "MD003": { "style": "setext_with_atx_closed"},  // 允许#和===形式的标题风格混用
        "MD009": { "br_spaces": 2 },                    // 允许末尾两个空格为<BR/>自动换行模式
        "MD013": false,                                 // 禁用单行长度限制
        "MD014": false,                                 // 禁用sh命令以 $ 作为开始
        "MD038": false,                                 // 禁用代码不以空格作为开始或结束
        "MD041": false,                                 // 禁用代码段必须有标题栏
        "MD029": { "style": "ordered" }                 // 有序列表格式为顺序方式
    }

Jekyll的Markdown解释器从3.0开始，默认从 redcarpet+Pygments 换为 kramdown+Rouge, 现在已知的问题为：列表下不支持GFM形式的代码块(神奇的是Github下的README.md文件支持)，折中的办法是使用区块引用(Blockquote)，在其下再使用代码块(我的博客模板已针对这种情况在呈现上做了优化)

参考资料

Github 简明教程
Git 简明指南
Jekyll 英文文档
Jekyll 中文文档
Jekyll 代码高亮的几种选择
Markdown 语法说明
Markdown Lint
kramdown Quick Reference

minimalacademicresumeportfoliodocumentationwikitailwindbootstrapdarkecommercegithub-pagesblog