翻译一个 jekyll 主题的使用

symphonyh — Sun, 12 Aug 2018 18:05:42 +0800

示例地址：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

主题颜色代码：

引用参考文献

为了帮助我们的自动生成书目和引文，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

rails view 模版引擎 (erb halm slim liquid markdown) 语法详解及示例

symphonyh — Tue, 07 Mar 2017 18:39:42 +0800

学习rails过程中，经常看github上的代码示例，看到不同偏好的开发者使用halm,erb,slim,liquid写的 view，确实很美观，也简洁，但是不便于初学者学习，又没个所见即所得的转换工具。在很多前辈文章和官方资料基础上，索性花了点时间整理了下几种常见模版的语法规则，配以多种代码示例，如果对别人有点用就再好不过了。

水平有限，整理中不免有不准确的描述或者错误，还请前辈多指正，我会持续补充修改，以免误导别人，这里先谢啦！

先预览下

再来一张

详情请看链接：
笔记主页:https://symphonyh.github.io/
slim:https://symphonyh.github.io/cloudblog/2017/03/06/slim/
halm:https://symphonyh.github.io/cloudblog/2017/01/17/howusinghaml/
liquid:https://symphonyh.github.io/cloudblog/2017/03/04/liquid/
erb:https://symphonyh.github.io/cloudblog/2017/03/06/erb/
markdown:https://symphonyh.github.io/cloudblog/2017/01/27/used-markdown/

symphonyh (韩兴宇)

翻译一个 jekyll 主题的使用

基础使用

文章格式及命名规范

kramdown 语法

文章版式

脚注的使用

块级引用

页面模板

目录表

改变主题颜色和布局

引用参考文献

安全发布站点

jekyll 常用指令

谁知道如何把 ember-cli 3.1 的 webapp 部署到 Heroku 的方法？

rails 已经 5.2 了 ember.js 也 3.X 还有必要用 rails 做后端，前端用 ember.js 吗？

看`rails4`的时候，看到一些应用采用前后端不同框架，前端`ember 1.x`后端`rails 3/4`很牛的样子，像那个`Discourserails` ...

现在`rails`已经 5.2 了 `ember.js`也 3.X 还有必要用`rails`做后端，前端用 ember.js 吗？

rails view 模版引擎 (erb halm slim liquid markdown) 语法详解及示例

symphonyh (韩兴宇)

翻译一个 jekyll 主题的使用

基础使用

文章格式及命名规范

kramdown 语法

文章版式

脚注的使用

块级引用

页面模板

目录表

改变主题颜色和布局

引用参考文献

安全发布站点

jekyll 常用指令

谁知道如何把 ember-cli 3.1 的 webapp 部署到 Heroku 的方法？

rails 已经 5.2 了 ember.js 也 3.X 还有必要用 rails 做后端，前端用 ember.js 吗？

看rails4的时候，看到一些应用采用前后端不同框架，前端ember 1.x后端rails 3/4很牛的样子，像那个Discourserails ...

现在rails已经 5.2 了 ember.js也 3.X 还有必要用rails做后端，前端用 ember.js 吗？

rails view 模版引擎 (erb halm slim liquid markdown) 语法详解及示例

看`rails4`的时候，看到一些应用采用前后端不同框架，前端`ember 1.x`后端`rails 3/4`很牛的样子，像那个`Discourserails` ...

现在`rails`已经 5.2 了 `ember.js`也 3.X 还有必要用`rails`做后端，前端用 ember.js 吗？