docs: add Docker

jasonephraim · May 3, 2019 · d9e5e08 · d9e5e08
1 parent 66d4a02
commit d9e5e08
Show file tree

Hide file tree

Showing 7 changed files with 130 additions and 28 deletions.
diff --git a/docs/_docs/en/1.1-quick-start.md b/docs/_docs/en/1.1-quick-start.md
@@ -10,6 +10,31 @@ In this document, you will learn how to **install the theme**, **setup your site
 
 <!--more-->
 
+```mermaid
+graph LR;
+    A0[Installing TeXt]
+    B0[Common Method]
+    B1[Ruby Gem Method]
+    C0[Fork this repo]
+    C1[Clone from GitHub]
+    C2[Download]
+    D0[Setup Your Site]
+    E0[Installing Development Environment]
+    F0[Installing Directly]
+    F1[Docker]
+    A0-->B0;
+    A0-->B1;
+    B0-->C0;
+    B0-->C1;
+    B0-->C2;
+    B1-->D0;
+    C1-->E0
+    C2-->E0
+    D0-->E0
+    E0-->F0
+    E0-->F1
+```
+
 ## Installing the Theme
 
 ### Common Method
@@ -30,11 +55,11 @@ To install it with common method, all you need to do is copying all the theme fi
    git clone git@github.com:kitian616/jekyll-TeXt-theme.git
    ```
 
-1. Download and unzip the file to your Jekyll site directory.
+2. Download and unzip the file to your Jekyll site directory.
 
    <a class="button button--success button--rounded" href="https://github.com/kitian616/jekyll-TeXt-theme/archive/master.zip"><i class="fas fa-download"></i> Download TeXt Theme</a>
 
-1. If you host your site on GitHub Pages, you can just fork [jekyll-TeXt-theme](https://github.com/kitian616/jekyll-TeXt-theme), then rename the repository to **USERNAME.github.io** — replacing **USERNAME** with your GitHub username.
+3. If you host your site on GitHub Pages, you can just fork [jekyll-TeXt-theme](https://github.com/kitian616/jekyll-TeXt-theme), then rename the repository to **USERNAME.github.io** — replacing **USERNAME** with your GitHub username.
 
    ![Fork](https://raw.githubusercontent.com/kitian616/jekyll-TeXt-theme/master/docs/assets/images/github-fork.jpg)
 
@@ -54,12 +79,6 @@ To install it with common method, all you need to do is copying all the theme fi
    theme: jekyll-text-theme
    ```
 
-3. Then run Bundler to install the theme gem and dependencies:
-
-   ```bash
-   bundle install --path vendor/bundle
-   ```
-
 ## Setup Your Site
 
 If you install the theme with common method, you can go straight to the next step. But **if you install the theme with ruby gem method, you have to do some extra jobs**.
@@ -81,10 +100,42 @@ With gem-based themes, some of the site’s directories (such as the *assets*, *
 
 You can refer to the [/test folder](https://github.com/kitian616/jekyll-TeXt-theme/tree/master/test), this is a example with gem-based themes.
 
+## Installing Development Environment
+
+If you want to run them them locally, you need first install Ruby and Jekyll, see [Installation](https://jekyllrb.com/docs/installation/) for details.
+
+After that, run bundler to install the dependencies:
+
+```bash
+bundle install --path vendor/bundle
+```
+
+And also, TeXt offer [Docker](https://www.docker.com/) support for development and public, this make it easier to setup environment.
+
+![Docker](https://raw.githubusercontent.com/kitian616/jekyll-TeXt-theme/master/docs/assets/images/docker.jpg){:width="400px"}
+
+All you need todo is these 3 steps:
+
+1. [Install Docker](https://docs.docker.com/install/).
+
+2. Generate *Gemfile.lock*:
+
+   ```bash
+   docker run --rm -v "$PWD":/usr/src/app -w /usr/src/app ruby:2.6 bundle install
+   ```
+
+3. Build Docker image:
+
+   ```bash
+   docker-compose -f ./docker/docker-compose.build-image.yml build
+   ```
+
 ## Local Preview
 
 Run `bundle exec jekyll serve` to start the development server, then you can visit [http://localhost:4000/](http://localhost:4000/) to preview your site.
 
+For Docker, run `docker-compose -f ./docker/docker-compose.default.yml up` to start the development server.
+
 ## Build and Publish
 
 If you host your site on GitHub Pages, just push the source to the master branch of your USERNAME.github.io repository, GitHub would build automatically. You can visit your site on **https://USERNAME.github.io** several minutes later.

diff --git a/docs/_docs/zh/1.1-quick-start.md b/docs/_docs/zh/1.1-quick-start.md
@@ -10,6 +10,31 @@ TeXt 是一款 100% 兼容 GitHub Pages 的 Jekyll 主题，你可以通过 Fork
 
 <!--more-->
 
+```mermaid
+graph LR;
+    A0[安装 TeXt]
+    B0[普通方式]
+    B1[主题方式]
+    C0[从 GitHub 克隆]
+    C1[Fork 该仓库]
+    C2[下载]
+    D0[设置]
+    E0[安装开发环境]
+    F0[直接安装]
+    F1[使用 Docker]
+    A0-->B0;
+    A0-->B1;
+    B0-->C0;
+    B0-->C1;
+    B0-->C2;
+    B1-->D0;
+    C1-->E0
+    C2-->E0
+    D0-->E0
+    E0-->F0
+    E0-->F1
+```
+
 ## 安装
 
 ### 普通方式
@@ -30,11 +55,11 @@ TeXt 是一款 100% 兼容 GitHub Pages 的 Jekyll 主题，你可以通过 Fork
    git clone git@github.com:kitian616/jekyll-TeXt-theme.git
    ```
 
-1. 下载主题压缩包并解压到你的项目目录中：
+2. 下载主题压缩包并解压到你的项目目录中：
 
    <a class="button button--success button--rounded" href="https://github.com/kitian616/jekyll-TeXt-theme/archive/master.zip"><i class="fas fa-download"></i> 下载 TeXt 主题</a>
 
-1. 如果你打算在 GitHub Pages 上搭建你的网站，你可以直接 fork [jekyll-TeXt-theme](https://github.com/kitian616/jekyll-TeXt-theme) 到你的仓库，然后将其重命名为 **USERNAME.github.io** — 这里的 **USERNAME** 是你的 GitHub 用户名。
+3. 如果你打算在 GitHub Pages 上搭建你的网站，你可以直接 fork [jekyll-TeXt-theme](https://github.com/kitian616/jekyll-TeXt-theme) 到你的仓库，然后将其重命名为 **USERNAME.github.io** — 这里的 **USERNAME** 是你的 GitHub 用户名。
 
    ![Fork](https://raw.githubusercontent.com/kitian616/jekyll-TeXt-theme/master/docs/assets/images/github-fork.jpg)
 
@@ -48,18 +73,12 @@ TeXt 是一款 100% 兼容 GitHub Pages 的 Jekyll 主题，你可以通过 Fork
    gem "jekyll-text-theme"
    ```
 
-1. 向站点的 *_config.yml* 中加入下列代码来启用主题：
+2. 向站点的 *_config.yml* 中加入下列代码来启用主题：
 
    ```yaml
    theme: jekyll-text-theme
    ```
 
-1. 最后，执行命令行 `bundle install` 来安装主题和其他的相关依赖。
-
-   ```bash
-   bundle install --path vendor/bundle
-   ```
-
 ## 设置
 
 **这里仅针对主题方式的安装，普通方式安装请跳过。**
@@ -81,12 +100,44 @@ Jekyll 主题含有主题默认的布局文件、包含文件和样式表， 但
 
 你可以参考主题源码的 [/test 目录](https://github.com/kitian616/jekyll-TeXt-theme/tree/master/test), 这是一个使用主题的示例。
 
+## 安装开发环境
+
+如果你想本地运行主题，你需要安装 Ruby 以及 Jekyll，详情请戳 [这里](https://jekyllrb.com/docs/installation/)。
+
+上述步骤完成后，安装 Ruby 依赖包：
+
+```bash
+bundle install --path vendor/bundle
+```
+
+当然，TeXt 还提供了 [Docker](https://www.docker.com/) 支持，使用 Docker 能让你更方便的完成环境的安装，并且环境统一，不会出错。
+
+![Docker](https://raw.githubusercontent.com/kitian616/jekyll-TeXt-theme/master/docs/assets/images/docker.jpg){:width="400px"}
+
+你只需要以下 3 步即可通过 Docker 完成环境的搭建：
+
+1. [安装 Docker](https://docs.docker.com/install/)。
+
+2. 生成 *Gemfile.lock* 文件：
+
+   ```bash
+   docker run --rm -v "$PWD":/usr/src/app -w /usr/src/app ruby:2.6 bundle install
+   ```
+
+3. 创建 Docker 镜像 (Image)：
+
+   ```bash
+   docker-compose -f ./docker/docker-compose.build-image.yml build
+   ```
+
 ## 本地预览
 
 Jekyll 集成了一个开发用的服务器，可以让你使用浏览器在本地进行预览。
 
 通过 `bundle exec jekyll serve` 命令启动开发服务器，然后你就可以访问 [http://localhost:4000/](http://localhost:4000/) 预览你的网站了。
 
+如果是通过 Docker 搭建的环境，请运行 `docker-compose -f ./docker/docker-compose.default.yml up` 命令以启动开发服务器。
+
 ## 编译和发布
 
 如果你打算把网站搭建在 GitHub Pages 上，那你所需要做的就是将项目的源码上传到 USERNAME.github.io 源码仓库的 master 分支，GitHub 会自动的编译，几分钟后你就可以通过 **https://USERNAME.github.io** 访问到你的网站了。

diff --git a/docs/_docs/zh/2.1-configuration.md b/docs/_docs/zh/2.1-configuration.md
@@ -101,7 +101,7 @@ lang: en
 
 ### 时区
 
-设置时区，这个设置作用于 TZ 变量， Ruby 用它来处理日期和时间。使用 IANA Time Zone Database 标准，比如 America/New_York 。其默认值为操作系统的时区。可以在 [这里](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 找到可取的值。[^jekyll_global_configuration]
+设置时区，这个设置作用于 TZ 变量， Ruby 用它来处理日期和时间。使用 IANA Time Zone Database 标准，比如 America/New_York 。其默认值为操作系统的时区。详情请戳 [这里](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)。[^jekyll_global_configuration]
 
 [^jekyll_global_configuration]: [Configuration#Global Configuration](https://jekyllrb.com/docs/configuration/#global-configuration)
 
@@ -139,7 +139,7 @@ timezone: Asia/Shanghai
 
 ## GitHub 源码仓库
 
-[GitHub Metadata](https://github.com/jekyll/github-metadata) 插件的设置, 你可以在[这里](https://github.com/jekyll/github-metadata/blob/master/docs/configuration.md#configuration)找到更多信息。
+[GitHub Metadata](https://github.com/jekyll/github-metadata) 插件的设置, 详情请戳 [这里](https://github.com/jekyll/github-metadata/blob/master/docs/configuration.md#configuration)。
 
 这个设置告诉 jekyll-github-metadata 插件应该从哪个项目中获取元数据，其格式为 `项目所有者 ID/项目名称`，例如：kitian616/jekyll-TeXt-theme。
 
@@ -156,14 +156,14 @@ repository: user_name/repo_name
 | 模式名称 | 描述 |
 | --- | --- |
 | **text** | 此时摘要为纯文本，会过滤掉一切非文本元素（标题，链接，列表，表格，图片等等），且截取前 350 个字符。 |
-| **html** | 此时摘要为 HTML 文档，与文章内容一致，并且 **默认展示整篇文章的内容**。若想控制摘要内容，需要在文章中想要显示到的地方加上 `<!--more-->`，详情请戳[这里](https://jekyllrb.com/docs/posts/#post-excerpts)。 |
+| **html** | 此时摘要为 HTML 文档，与文章内容一致，并且 **默认展示整篇文章的内容**。若想控制摘要内容，需要在文章中想要显示到的地方加上 `<!--more-->`，详情请戳 [这里](https://jekyllrb.com/docs/posts/#post-excerpts)。 |
 
 ```yaml
 excerpt_separator: <!--more-->
 excerpt_type: text # text (default), html
 ```
 
-该设置在 2.2.0 版中移到了 Articles 和 Home 布局的头信息中，你可以在[这里](https://tianqi.name/jekyll-TeXt-theme/docs/cn/layouts#articles-layout)找到更多信息.
+该设置在 2.2.0 版中移到了 Articles 和 Home 布局的头信息中，详情请戳 [这里](https://tianqi.name/jekyll-TeXt-theme/docs/cn/layouts#articles-layout)。
 {:.error}
 
 ### 许可协议
@@ -262,7 +262,7 @@ comments:
     id: "your-addthis-pubid"
 ```
 
-你需要在页面的头信息里设置 `sharing` 属性为 `true` 来开启该页的评论，详情请戳[这里](https://tianqi.name/jekyll-TeXt-theme/docs/zh/layouts#article-%E5%B8%83%E5%B1%80)。
+你需要在页面的头信息里设置 `sharing` 属性为 `true` 来开启该页的评论，详情请戳 [这里](https://tianqi.name/jekyll-TeXt-theme/docs/zh/layouts#article-%E5%B8%83%E5%B1%80)。
 {:.warning}
 
 ## 评论
@@ -316,7 +316,7 @@ comments:
     app_key : "your-leanCloud-app-key"
 ```
 
-对于上面所有的评论系统, 你都需要在页面的头信息里设置 `key` 属性来开启该页的评论，详情请戳[这里](https://tianqi.name/jekyll-TeXt-theme/docs/zh/layouts#page-%E5%B8%83%E5%B1%80)。
+对于上面所有的评论系统, 你都需要在页面的头信息里设置 `key` 属性来开启该页的评论，详情请戳 [这里](https://tianqi.name/jekyll-TeXt-theme/docs/zh/layouts#page-%E5%B8%83%E5%B1%80)。
 {:.warning}
 
 ## 文章点击量
@@ -359,7 +359,7 @@ pageview:
     app_class : "your-leanCloud-app-class"
 ```
 
-对于上面所有的点击量统计, 你都需要在页面的头信息里设置 `key` 属性来开启该页的统计功能，详情请戳[这里](https://tianqi.name/jekyll-TeXt-theme/docs/zh/layouts#page-%E5%B8%83%E5%B1%80)。
+对于上面所有的点击量统计, 你都需要在页面的头信息里设置 `key` 属性来开启该页的统计功能，详情请戳 [这里](https://tianqi.name/jekyll-TeXt-theme/docs/zh/layouts#page-%E5%B8%83%E5%B1%80)。
 {:.warning}
 
 ## 站点统计

diff --git a/docs/_docs/zh/2.3-layouts.md b/docs/_docs/zh/2.3-layouts.md
@@ -128,7 +128,7 @@ graph TB;
 | 配置项             | 可选值                 | 描述        |
 | ---               | ---                   | ---         |
 | **data_source**   | `!!str`               | 如果你将将集合名设置为该项的值，该页面将会展示这个集合下的文章列表。你可以在 [Collections](https://jekyllrb.com/docs/collections/) 找到更多关于集合的信息。 |
-| **type**          | item, brief, grid | TeXt 支持三种文章列表类型，每种类型都对应着一些配置，你可以在[这里](https://tianqi.name/jekyll-TeXt-theme/samples.html#articles-layout)看到相关的示例。 |
+| **type**          | item, brief, grid | TeXt 支持三种文章列表类型，每种类型都对应着一些配置，你可以在 [这里](https://tianqi.name/jekyll-TeXt-theme/samples.html#articles-layout) 看到相关的示例。 |
 | **size**          | md, sm        | 当 type 为 `grid` 时有效。 |
 | **article_type**  | BlogPosting       | 当 type 为 `normal` 时有效。 |
 | **show_cover**    | true (default), false | 当 type 为 `normal` 时有效。 在设置改参数为 `true` 前，你需要给集合里的每篇文章设置封面, 参考 [Page 布局](#page-layout)的 `cover` 配置项。 |
@@ -145,7 +145,7 @@ graph TB;
 | 模式名称 | 描述 |
 | --- | --- |
 | **text** | 此时摘要为纯文本，会过滤掉一切非文本元素（标题，链接，列表，表格，图片等等），且截取前 350 个字符。 |
-| **html** | 此时摘要为 HTML 文档，与文章内容一致，并且 **默认展示整篇文章的内容**。若想控制摘要内容，需要在文章中想要显示到的地方加上 `<!--more-->`，详情请戳[这里](https://jekyllrb.com/docs/posts/#post-excerpts)。  |
+| **html** | 此时摘要为 HTML 文档，与文章内容一致，并且 **默认展示整篇文章的内容**。若想控制摘要内容，需要在文章中想要显示到的地方加上 `<!--more-->`，详情请戳 [这里](https://jekyllrb.com/docs/posts/#post-excerpts)。  |
 
 对于 Home 页，你可以像这样把 `excerpt_type` 设置为 `HTML`：
 

diff --git a/docs/_docs/zh/2.7-i18n.md b/docs/_docs/zh/2.7-i18n.md
@@ -19,4 +19,4 @@ TeXt 把 UI 元素的文字整理成一系列的翻译标识统一的放置在 *
 | **繁体中文**  | zh-Hant, zh-TW, zh-HK |
 | **韩语** | ko, ko-KR |
 
-你可以在[这里](https://tianqi.name/jekyll-TeXt-theme/samples.html#languages)找到不同语言的示例。
+你可以在 [这里](https://tianqi.name/jekyll-TeXt-theme/samples.html#languages) 找到不同语言的示例。
diff --git a/docs/_docs/zh/3.3-additional-styles.md b/docs/_docs/zh/3.3-additional-styles.md
@@ -6,7 +6,7 @@ key: docs-additional-styles-zh
 
 Jekyll 使用 kramdown 作为默认 Markdown 解释器。kramdown 可以通过 ALDs[^ALDs] 来设置块级元素或行内元素的属性。例如，可以通过 `{:.class-name1.class-name-2}` 来给元素定义样式类。
 
-TeXt 定义了一些样式类，你可以在文章和页面的方便的使用，可以在[这里](https://tianqi.name/jekyll-TeXt-theme/post/2017/08/08/additional-styles.html)看到示例和详细的说明.
+TeXt 定义了一些样式类，你可以在文章和页面的方便的使用，可以在 [这里](https://tianqi.name/jekyll-TeXt-theme/post/2017/08/08/additional-styles.html) 看到示例和详细的说明.
 
 [^ALDs]: [Attribute List Definitions](https://kramdown.gettalong.org/syntax.html#attribute-list-definitions)
 

diff --git a/docs/assets/images/docker.jpg b/docs/assets/images/docker.jpg