About Github Pages

Published On October 12, 2015

category tool | tags github markdown


一、用Jekyll写博客的规则

参见jekyll的文档

  1. 所有博客位于_posts文件夹下;
  2. jekyll支持markdown和textile两种编辑语言,下面以markdown为例;
    1. markdown文件名格式:年-月-日-标题.md,年是4位数字,月和日都是2位数字。标题中的空格用-代替,比如2011-12-31-new-years-eve-is-awesome.md ;这里的时间和标题指明了md文件解析后生成的html文件所在的路径;
  3. 所有博客文章顶部必须有一段YAML头信息,在两行三条虚线之间可以设置预定义变量,即使没有预定义变量,这两条虚线也不能省;预定义变量可以是如下几种(注意:所有变量名后面的:后面必须至少有一个空格分隔,否则无法解析):
    • title:文章的标题,显示在博客列表和博客正文中;
    • date:日期,格式和文件名中的一样,显示的地方如上所述;
    • tag:文章所属的标签,一篇博客可以属于多个标签,多个标签用空格分开或用yaml列表的形式表示;
    • category:文章所属的类别,一篇文章可以指定多级类别;比如指定programming c那么生成的博客将位于文件夹prgramming的子文件夹c中;
    • description:用于生成网页的meta标签,我将之用于当文章显示在首页时作为摘要,因为ruby不能对中文进行字数统计(能统计英文单词数);
  4. 用<!-—more-->表示excerpt_separator,此标记之前的部分作为摘要,如果不加此标记那么整篇文章的内容都将显示在博客列表中,另外上或者下至少有一个空行,否则会显示在页面上;
  5. 首行缩进的表示
    • 把输入法由半角改为全角。 两次空格之后就能够有两个汉字的缩进。
    • 在开头的时候,先输入这个,然后紧跟着输入文本即可。分号也不要掉。
      • &#160; &#160; &#160; &#160;
  6. 表示标题的特殊字符#和标题内容之间需要用空格分开;
  7. 可以在markdown文件的正文使用预定义变量,比如{{ site.author }},但是不能在yaml头信息中使用;

二、github pages的几点困惑以及理解

  1. markdown是一种替代html进行写作的轻量级标记语言,它使普通的文本具有一定的格式。标准的markdown语法很简单,在此基础上又有了一些扩展的markdown。
  2. githubpages提供了jekyll server,用户可以在上面建立自己的博客或者产品展示。
  3. jekyll是一个建立静态网站的框架,使用markdown、liquid、html、css搭建。liquid是写在html里的具有某些后简单台语言功能的标记语言。jekyll具有一套默认的配置,如果我们想增加或覆盖某项配置可以在_config.yml中自定义。
  4. jekyll解析markdown需要使用markdown渲染器,默认的是kramdown,除此之外建博客最常用的应该是redcarpet,这些都是扩展的markdown,它们在标准的markdown基础上增加了一些便利的功能,比如autolink、表格等。
  5. 关于高亮:markdown只是一种结构上的格式,不提供高亮。githubpage默认用pytments语法高亮格式。如果想自定义只有用引入外部的js,比如highlighter.js。
  6. githubpage上的jekyll具有某些与原生jekyll不同的全局配置,其中之一就是highlighter,其他的是一些为了安全起见不能修改的配置。
  7. GitHub Flavored Markdown:即GFM,是一种github自己的markdown风格,包含了Linguist语法高亮。repository中的readme.md显示就是这种风格。可以在markdownpad2 pro中使用github的这种风格,不过需要联网。
  8. 个人觉得GFM使用的linguist语法高亮比pytments更漂亮,那么如何使自己的博客支持GFM呢?配置方式:在Kramdown中增加input:GFM选项。

三、16年4月10日补充

  1. YAML头信息中title和date值会覆盖文件名的相应部分,html保存的位置为第一个category+date+文件名中的title
  2. 现在GithubPages升级到Jekyll3,只支持kramdown+rough

qq email facebook github
© 2018 - Xurui Yan. All rights reserved
Built using pelican