Ruby 翻译一个 jekyll 主题的使用

symphonyh · August 12, 2018 · Last by Rei replied at August 12, 2018 · 3051 hits

示例地址:https://www.cloudhan.me

Github 上 Ed.主题及源文档:https://github.com/minicomp/ed/blob/master/documentation.md

相当简洁不错的一个主题,用了很长一段时间,也分享给大家看看,新手翻译和理解不准确的地方还请指正。

基础使用

这是一个Jekyll的主题,它很简洁、很漂亮,适合撰写文章。你可以撰写自己的短文、诗歌、甚至小说、自传来发布,我一直有个写作的梦想,之所以喜欢这个主题,大致源于此吧!这里还是得感谢下Ed主题的发布者 Alex Gil 及其团队给了我们很好的体验。
要想很好的使用Ed,除了熟悉基础的markdown语法,还需要会使用git,rvm, bundle, jekyll 3.7.3的基础指令和Liquid 的语法知识。
Ed的运行环境是ubuntu,相比windows环境运行更加稳定;所以手册里看到的终端命令和相关工具都是在ubuntu 16.04 LTS的环境中运行的。

如果你迫不及待已经想撰写文章了,打开blog文件夹,右键选择在终端打开,或者Ctrl+Alt+T 打开终端(确保在 blog 目录下):

$ cd blog
$ rvm use 2.4.1@jekyll
$ subl .

发布写好的文章前,最好先在本地启动Jekyll服务预览内容和格式,确保没有错误发生,本地Firefox浏览器地址为127.0.0.1:4000

$ jekyll serve

发布到Github的服务器,需要注意的是:blog 使用了cloudhan.me的域名,没有使用账户名(事实上账户名网站是我的技术 blog),这是个项目网站,所以这里不是 master 分支:

$ git status
$ git add .
$ git commit -m "first commit"
$ git push origin gh-pages

文章格式及命名规范

对于Jekyll的文档可以参考 Jekyll 中文网 或者安道的教程。我使用的纯文本编辑工具是sublime-text3,我确保它是个神奇的工具,非常方便好用。

撰写的 blog 文章在_texts 文件夹里,记住每篇文章命名规则是 your-title.md 。每篇文章的YAML顶部信息确保遵守如下规则:

---
layout: poem
title: "Cahier d'un retour au pays natal"
author: Cloudhan
---

kramdown 语法

除了使用markdown原生的语法,主题使用kramdown拓展语法,主要就是对表格的支持,还包括脚注,词汇定义,缩写,图片和视频等。可以参考简书:让你的 Markdown 用起来得心应手一文。


文章版式

Ed主题提供了三种不同的版式:诗歌:poem故事:narrative戏剧:drama。文章顶部的YAML信息layout: page定义了该布局。布局模板文件在_layouts文件夹中可以找到。使用这些布局将允许您根据您不同的写作需求调整样式,一些特殊指令是需要了解的。

诗歌中常用的行开始标记语法:

- Hold fast to dreams
- For if dreams die
- Life is a broken-winged bird
- That cannot fly.
- Hold fast to dreams
- For when dreams go
- Life is a barren field
- Frozen with snow.

行缩进的语法:

- {:.indent-3} But O heart! heart! heart!
- {:.indent-4} O the bleeding drops of red,
- {:.indent-5} Where on the deck my Captain lies,
- {:.indent-6} Fallen cold and dead.

这里 - 表示一行的开始;{:.indent-3} 表示缩进值,值得范围可以从 1-10;* 包围则是使用斜体字,如:

这里是斜体字


脚注的使用

脚注的语法很简洁:行文中插入[^fn2]即可,注解处使用 [^fn2]:XXX 即可,可以实现相互跳转。

- O Captain! my Captain! rise up and hear the bells; 
- Rise up—for you the flag is flung—for you the bugle[^fn2] trills,

...

[^fn2]: The bugle is a small trumpet implicated in the military industrial complex.

多行脚注需要同样保持缩进:

[^fn3]:
    Ugh pinterest fixie cronut pitchfork beard. Literally deep 
    cold-pressed distillery pabst austin. 

    这是第二行注解:Typewriter 90's roof party poutine, kickstarter raw 
    denim pabst readymade biodiesel umami chicharrones XOXO. 

文章中某些标记并不一定使用数字,例如只使用一个* 符号,脚注尾部使用↩︎返回标记处, HTML可以提供方法:

... At this time, Anna,<sup><a href="#fn2" id="ref2">\*</a></sup> my intended wife, came on;

...

<sup id="fn2">*</sup> She was free. [&#x21a9;&#xfe0e;](#ref2)

块级引用

引用在kramdown的实现非常简单,其中的文字是引用内容。

> This is to certify that I, the undersigned, have given the bearer, my servant, full liberty to go to Baltimore, and spend the Easter holidays.
>
> Written with mine own hand, &c., 1835.  
> WILLIAM HAMILTON,

设想在一个故事:narrative的版式中,块引用诗歌:poem,语法是怎样的呢?

...
> - Two others oped their iron jaws,
> - And waved their children-stealing paws;
> - There sat their children in gewgaws;
> - By stinting negroes' backs and maws,
> - They kept up heavenly union.
> ^
> - All good from Jack another takes,
> - And entertains their flirts and rakes,
> - Who dress as sleek as glossy snakes,
> - And cram their mouths with sweetened cakes;
> - And this goes down for union.
{:.poetry}

这个{:.poetry}标记是告诉程序把上面的-行标记作为诗歌:poem版式处理,之所以需要声明是因为这段文字本身的版式是故事:narrative版式,以便程序正确调用。


页面模板

你已经知道,blog 文章都是放在_text文件夹,其他的页面模板(例如:about, index, documentation)则是在根目录下的。 你会注意到,模板文件有些是以.html而不是.md结尾。Jekyll中的所有模板文件都是HTML。虽然这些文件大多是用HTML编写的,但它们仍然包含YAML顶部信息和Liquid标签。 不同的地方是:.html文件更方便于定制网页的布局及样式,也可以使用Liquid语句,但不能使用markdown语法和扩展;.md文件要更加丰富和灵活些,除了允许使用markdown及扩展外可以同时运用HTML标签和Liquid语句更适于书写文档。


目录表

Ed主题里可以建立三种目录表,第一个示例是主页中用Liquid 模板语言编写的文章目录, {%raw%}{% %}{%endraw%} 是逻辑表达式的写法, {%raw%}{{ }}{%endraw%} 只是输出内容,示例中是文章的标题。

<div class="toc">
  <h2>Sample texts</h2>
  <ul class="post">

  {%raw%}{% for item in site.posts do %}{%endraw%}
      <li class="post-title">
      <a href="{%raw%}{{ site.baseurl }}{{ item.url }}{%endraw%}">
        {%raw%}{{ item.title }}{%endraw%}
      </a>
    </li>
  {%raw%}{% endfor %}{%endraw%}
  </ul>  
</div>

第二个示例恰好就是本文件顶部应用的目录语法。这是kramdown的方式,{:.no_toc}的作用是告诉程序不要把Contents作为目录内容,下面的语句是把文中markdown标题自动生成目录内容放在{:toc}的位置。

## Contents
{:.no_toc}

* ToC
{:toc}

对于多章节的长篇文章,第三种方式更为适合,在YAML的顶部信息中写入目录,这种方式的好处是在阅读文章时可以通过侧边栏看到目录大纲,实现方便的章节跳转和返回。

toc:
- Title Page
- Preface
- Letter From Wendell Phillips
- Chapter I
- Chapter II

改变主题颜色和布局

如果你不喜欢Ed默认的颜色,可以在default.html版式中方便的调整和修改。只需要改变bord标签的 class 属性即可。详细参见:Lanyon documentation.

  • 侧边栏在右侧:<body class="layout-reverse sidebar-overlay">
  • 改变基本主题颜色:<body class="theme-base-08">

另一和方式是:Ed在配置文件中提供了color-scheme:主题基本颜色的变量,可以在这里定义颜色,其实就是改变bord标签的属性值,和上面意思一样相对应的,bord的属性设置为:

<body class="theme-base-{%raw%}{{site.color-scheme}}{%endraw%}">

配置技巧:class属性可以设置多项,

color-scheme: 0d layout-reverse sidebar-overlay
color-scheme: 0b

主题颜色代码:

Available theme classes


引用参考文献

为了帮助我们的自动生成书目和引文,Ed可以使用 Sylvester Keil 的jekyll-scholar 插件。这需要了解更多关于 gem 的基本指令,请务必阅读jekyll-scholar Github 使用文档。

jekyll-scholar很棒,可以为你的书目编撰工作节省大量的时间,实现也并不复杂:

第一步,必须将jekyll-scholar starter kit中的_bibliography文件夹、bibliography.md文件移到blog根目录文件夹中。 不同于脚注,Ed需要一个单独的页面来引用您的书目或文献。这就是 bibliography.md 文件的作用,确保这个文件末尾使用以下行来引用书目文件_bibliography文件夹中references.bib提供的参考文献。

{% bibliography %}

第二步,在_config.yml文件中追加以下内容:

 # plugins
plugins: ['jekyll/scholar']

# Scholar
scholar:
  style: modern-language-association
  locale: en

  sort_by: none
  order: ascending

  group_by: none
  group_order: ascending

  source: ./_bibliography
  bibliography: references.bib
  bibliography_template: "{{reference}}"
  relative: "/ed/bibliography.html"

  replace_strings: true
  join_strings:    true

  use_raw_bibtex_entry: false

  details_dir:    bibliography
  details_layout: bibtex.html
  details_link:   Details

  query: "@*"

第三步,Gemfile文件中追加一行:

gem 'jekyll-scholar', '~>5.7.1'

最后要启用jekyll-scholar,必须重新运行bundle install

$ rvm use 2.4.1@jekyll

$ bundle install

对于一些稍复杂的引用jekyll-scholar中引用书目文献提供了丰富的过滤函数:

{%raw%}
{% cite cesaire_discourse_2001 %}
{%endraw%}

请注意,jekyll-scholar starter kit已经准备好了mla风格。若要使用 Chicago风格或更高级的文献格式,请参阅jekyll-scholar的文档以进行适当的更改。


安全发布站点

如果你在jekyll中安装了jekyll-scholar或者其他插件,你需要在 Github 上发布你的站点,将jekyll-scholar starter kit的 Rakefile 文件复制到blog根目录下,使用一行命令便可以轻松完成这项任务。确保切换到 gh-pages 分支并运行以下命令:

$ rake ed:publish

jekyll 常用指令

$ jekyll build --watch
$ jekyll clean
$ jekyll serve --watch

by Cloudhan
July 2018

看得不明所以:

  1. 原文是什么?
  2. 主题是什么?
You need to Sign in before reply, if you don't have an account, please Sign up first.