Start Guide

博客迷你指南

Hi~ 我是定制版的 Jekyll 博客迷你指南。嗯哼~

希望透过一篇文章，可以将一些基本概念，以及使用博客的基本技能都掌握，而后就能开始自己动手尝试啦。

博客搭建

博客搭建的方法与过程，既然现在博客已搭建完成，就不用管啦。只要知道，这个博客是基于 GitHub 平台，由 Jekyll 博客引擎生成，用 Git 工具管理和发布，使用 Markdown 语法书写，并运用到很多的插件（包括代码高亮、分享、评论、分页等插件）来完善就好。

感兴趣可以看瞧瞧这里，看一下生鸡蛋的母鸡是怎么个样子：

• Jekyll 博客主题精选 - Microdust
• 打造你的 GitHub Pages 专属博客（小白教程） - Microdust

博文发布途径

在 Jekyll 博客（也就是这样的博客）发布一篇文章，简单说，通常可以通过 3 个途径：

1. GitHub 网页版 ## 通过浏览器直接访问，在博客仓库添加新的博文文件即可。没什么学习成本，但网页版有时修改会繁琐一点。；
2. GitHub Desktop + Markdown 编辑器 ## 在本地写作然后添加文件，直接用图形客户端发布到网站（这个过程不开浏览器也没关系，当然咯，网络还是得有）。优点是修改各种方便；
3. Git + Markdown ## 命令行模式，熟悉了会用起来很顺手，不懂暂时关系也不大。

这一次，主要介绍 1 & 2 两个方式具体是怎么做的。

GitHub

GitHub 知名代码托管平台。博客的所有文档都存放在 GitHub 的个人项目里。博客是用了其中的一个服务：GitHub Pages

我们需要注册并登陆 GitHub 账号，并建立好自己的博客仓库。具体可以是下载模板来修改后自己上传也可以是通过 GitHub 特有的 Fork 机制，完成复制后再 Git Clone 到本地来修改，再进行同步（上传）。

对于博客，或者说 GitHub 的仓库除了使用网页版，还可以利用 GitHub for Desktop 和 Git 命令行工具来管理。

GitHub 图形客户端

打开 GitHub 的菜单（如果是 Mac，先切换到 GitHub 界面，左上角的应用菜单，选择 Preference 偏好选项），点选 Account 登录个人 GitHub 账户。

登录后，将已经 Fork 或已经存在的 GitHub Pages 项目从 GitHub （云端）中， Clone（相当于下载，不过是通过图形客户端或 Git 命令） 到本地来，以便于修改。

一般情况下，博客项目命名都是「个人 ID + GitHub.io」形式。不然无法正常使用博客服务。

提交和同步博客的修改

下载完项目后，可以在任务管理器（Mac 为 Finder）里打开，做进一步的查看、修改文档、添加博文之类的操作。

在修改文件（修改文件和添加博文的方法，将在后边说明。）完成后，GitHub 客户端会将文件的修改细节（包括位置和次数）显示出来。由于文件是在本地修改的，因而还需要提交到 GitHub 的服务器上，修改才会最终生效。

提交的流程：

0. 选择相应的项目（这是是博客项目）；
1. 如有修改，在 Description 填写说明（可以非常简要，但不能省略）；
2. 点击「Commit to master」，提交修改；
3. 点击右上角的「Sync」；
4. 文件同步完成，片刻后更新生效。

图形客户端也支持查看历史记录并对特定操作进行恢复。

了解 GitHub 图形客户端的使用后，后续在本地修改博客设定或添加博文时，我们就可以方便地将任何与博客相关的更改同步到远程的仓库。而同步也就意味着，在网页端查看博客时的更新，比如，在同步添加一篇新博文的操作后，几秒钟后刷新网页，新博文就会出现在我们的博客里了。

博客构成

嗯，接下来我们要了解一下 关于 Jekyll 博客的相关知识，以及具体可以做哪些自定义修改。

基础目录结构：

|-- _config.yml
|-- index.html
|-- _includes
|-- _layouts
|   |-- default.html
|   `-- post.html
|-- assets
|-- _posts
|   `-- 2010-10-04-TVB.md
|-- images
|   `-- Yvonne.png 
|-- CNAME
|-- _404.html
|-- About.md
|—— feed.xml
`-- README.md

目录文档详细说明：

• _config.yml 博客配置文档（包括博客标题、favicon、博主 ID、头像、描述、联系方式等基本信息都在这个文档修改）；
• index.html 博客架构文档；
• _includes 存放博客调用的模块文件（比如导航栏、底栏、博文内容显示、评论模块等）的文件夹，一般不需要管；
• _layouts 存放博客调用的页面模板文件（比如博客主页、具体博文页）的文件夹；
• assets 博客系统的相关程序文档；
• _posts 博客正文存放的文件夹。命名有规定，必须为「日期 + 标题」的模式，即「2010-10-04-TVB.md」，才能发布到博客里；
• images 图片文件夹，存放博客相关素材，包括博客 favicon、博主头像等图片及博文贴图素材；
• CNAME 绑定个人域名配置文档；
• 404.html 「404 Not Found.」，站点链接无法访问时的展示页。
• About.md 博客中的个人说明文档（About Me）；
• feed.xml 博客的 RSS 订阅工具；
• README.md 项目说明文档。用于 GitHub 个人项目主页的说明（描述）。

常用文档

自定义修改中，需要自己修改的文档包括：_config.yml、About.me、CNAME，以及 images 文件夹下的存放的 Logo、头像一类。一些博客还需要（看具体需求）修改_includes 下的 sidebar 文件，当然这个博客可以不管。

编辑器(用于打开及修改上述的文档)：

• TextMate Mac 平台
• Sublime Text Win/Mac 平台
• Notepad+ Windows 平台

Markdown 编辑器（写博文时用到的写作应用）：

• MacDown Mac 平台
• Mou Mac 平台
• Cmd Markdown 编辑阅读器 Win 平台
• MarkdownPad Win 平台

常用博文模板

博文存放在主目录下的 _posts 文件夹中。格式必须为 「日期 + 英文标题」，不然无法识别和发布。

博文的文件格式一般为 md(Markdown )格式。

每一篇 Markdown 文档的开头（第一行都为「 —」）都必须添加一段代码，

YAML 语法

每一篇博文的开头都有用「—」包裹的几段编码，这在 Jekyll 博客中被称为 YAML 编码。方便博客引擎将相关文档收录到博客以及标签系统中，转化为我们日常在浏览器里看到的博客网页的形态。没有编码，博客显示就会出问题。不同的博客模板，编码也会有些区别。

以下为一个具体栗子：

---
layout: post
title: 小猫杜威
excerpt: "一只猫咪和一座图书馆的故事。"
tags: [reading, life, ]
comments: true
image:
  feature: street.jpg
  credit: Azeril
  creditlink: http://azeril.me
---

• --- 第一行及编码格式的最后都必须为「—」。不然无法识别文档
• layout 用于定义页面的样式，默认
• title 标题，每一篇文章都有各自的标题
• excerpt 摘要，显示在主页，概述一篇文章的内容
• tags 标签。用于对文章归类。内容都在 Tags – 维港的烟火 归档，也可以通过左侧标签栏查看。每个标签都用英文的逗号隔开。我们现在主要用的就这么几个标签，也可以自己想啦，极少用到的就不用添加了：
• read
• life
• travel
• think
• view
• comments 评论。如果不想用评论功能可以设置为 false。不然也可以不添加。
• image 网页横版大图选项。图片都保存在主目录下的 images 文件夹下。添加对应的标题就可以使用，有时这样会比较好玩（好看）一点。如果不用，则使用默认的设置（默认为首页大图）咯。

所以，偷懒一下，简化的方式开头编码填写可以是这样的：

---
layout: post
title: 走夜路请放声歌唱
excerpt: "清亮的歌声"
tags: [read, life, ]
---

Tips

这样是不是就很简单了？

几个小 tips：

1. 这些编码模式不需要记，平时存一个模板就好，用的时候直接在模板基础上修改，或者也可以直接打开 _posts 下「template」开头的文件开始编辑。

2. 还是记得，先把文件修改为 date+title.md 的格式。标题注意使用英文，并且不要重复用同样的标题（以前用的不要再次出现），不然页面会导致冲突。

3. 首行开头必须为「—」，不能空格，不然会导致无法转化。

4. Markdown 语法还是用起来咯。

5. 如果想要每篇换不同的大图，那还是记得添加 images 的编码。

网页端在线发布博文

除了利用 GitHub 客户端以外，我们还可以通过 GitHub 网站发布博文。（如果博文使用图片，得借助图床，因为网页端无法上传图片。）

登录 GitHub 网站。

找到自己的博客项目主页（对，就是 ID.gitHub.io 命名的那只）。

点击主目录中的 _posts 文件夹。然后点击「+」，创建新博文。

博文结构还是一样：

• 标题
• 博文代码
• 正文

写完后，为本次创建文档的操作输入一段描述，确认提交（commit）就发布啦。

博客设定番外

与博客相关的一些其它设定

图片添加 Post Images

在 GitHub Blog 中添加图片主要有两种途径：

1. 存放图片于 GitHub 博客仓库中并调用；
2. 将图片托管于专门的图床服务并生成直链（Direct Link）进行调用；

利用 GitHub 作为图床。进入仓库主目录，把图片存放在 lemon 文件夹下，撰写 markdown 博文时用 ![ImageName](ImageLink) 的语法插入图片。

当一张文件名为 Cookie.png 的图片存放于 lemon 目录下，那么使用语法插入图片时就是 http://paw.cat/lemon/

只要存放的位置不变（依旧在「柠檬」文件夹中），那么域名＋目录的前缀路径也是不变的，唯一变化的是这个路径后接的图片文件的具体文件名。刚才的图片可以这样来调用：

![](http://paw.cat/lemon/C ookie.png)

图片文件管理的注意点：

1. 为了便于查看，文件名应当是主动自定义好的，不要是乱码或胡乱重命名的；
2. 重命名时要注意文件名的大小写；
3. 存放于 GitHub 特定目录下的图片文件名唯一，才能保证在调用时不起冲突，所以对图片一般不要命名太简单。尽量是三个相关标签的单词组成为佳；
4. 注意图片命名的美观和易于检索，可采取 驼峰命名法。例如，对于《风之影》这本书，可以命名为：TheShadowOfTheWind.png。更多栗子：
   • ImageOfTheUniversity.jpg
   • GithubWebCommitNewFile.png
   • WorkflowyCardsMakingGuide.png

为博客添加图片的另一种方案是使用 七牛云/Imgur/Photobucket 等图床服务。

使用流程为：

1. 上传图片；
2. 获取到该图片的直链；
3. 添加到 Markdown 文件中；
4. 完成。

具体的使用此处省略两百字。

如果日常写博客，图片使用的量和频率都不大，目前来说，可只考虑用 GitHub 仓库进行存放和管理。

文章链接 link posts

没什么特别的，在显示时直接在标题边上添加一个链接的图标。点击后可直接跳转相应的网页（方便收录博客之外的网页）。

This theme supports link posts, made famous by John Gruber. To use, just add link: http://url-you-want-linked to the post’s YAML front matter and you’re done.

And this is how a quote looks.

Some link can also be shown.

文章目录概览 Overview

显示在网页右侧的导航条，会将文章的一二三级目录合成到一列，便于点击和跳转。适用于长文。

用法很简单，在博文正文开头（YAML 编码后，正文）添加以下代码片段，文章转化时会自动附加目录导航条：

`<section id="table-of-contents" class="toc">

</section> `

多作者模式 Author Override

These owner variables were defined in config.yml

Start by modifying or creating a new authors.yml file in the _data folder and add your authors using the following format.

```
# Authors

billy_rick:
  name: Billy Rick
  web: http://thewhip.com
  email: billy@rick.com
  bio: "What do you want, jewels? I am a very extravagant man."
  avatar: bio-photo-2.jpg
  twitter: extravagantman
  google:
    plus: BillyRick

cornelius_fiddlebone:
  name: Cornelius Fiddlebone
  email: cornelius@thewhip.com
  bio: "I ordered what?"
  avatar: bio-photo.jpg
  twitter: rhymeswithsackit
  google:
    plus: CorneliusFiddlebone

To assign Billy Rick as an author for our post. You'd add the following YAML front matter to a post:

author: billy_rick

```

写作风格

日常行文的注意点。包括空格、标点符号、段落以及拼写和中文语法的一些注意点。

扩展阅读：中文书写风格清单 - Microdust

推荐一读。未来写作，完成后，也记得尽量参照清单进行相应的修改。

摘录笔记模式

做笔记也要认真一点。笔记是给自己看的，不是记下后就扔一边的东西。而作为回顾，作为未来利用的一个来源，出处还是有必要注意保留的。一句话来自哪本书哪一部分哪一章节乃至哪一页，如果比较清晰，也便能比较笃定地查看和引用。

不是凡事都求那么精准，但大体的位置和出处是必要的。所以，归属的章节至少要注意在每一段引文的后边保留着。

此外，或多或少要有一些自己的感想，留下一点自己的启发和思考。

扩展阅读： 豆瓣笔记使用体验及技巧

关于做读书笔记，更多实例参考：

以章节作为区分：

• 《设计，无处不在》的笔记-全书概要
• 《满满的书页》的笔记-全书

以页码作为区分：

• 《小猫杜威》的笔记-全书
• 《那些年，我们一起追的女孩》的笔记-全书

更细致的，以篇目和页码作为区分：

• 《这些人，那些事》的笔记-全书
• 《记得》的笔记-全书


嗯。希望，玩得快心啦~