如何写文档

在您添加或修改文档前请安装以下工具：

  1. 首先，确保 Ruby 和 Gem 能在您的机器上工作
    • 对于 Mac 用户，请参考这个来搭建 ruby 环境。
    • 对于 Windows 用户，使用 。
    • 对于 China 用户，考虑使用一个本地 gem 仓库以防止网络问题。
  2. 然后，安装 ，以及需要的插件
    • 注意：一些特定的 jekyll 和 jekyll-multiple-languages 版本不能一起使用（使用 jekyll 3.0.1 和 jekyll-multiple-languages 2.0.3 时我遇到一个 “undefined method” 错误)。这种情况下，jekyll 2.5.3 和 jekyll-multiple-languages 1.0.8 是已知可运行的版本。
      • 例如. 使用 gem install jekyll --version "=2.5.3" 来安装具体的版本。
    • 注意：对于 Mac 用户，如果 gem 安装时遇到类似这样的错误 ‘ERROR: While executing gem … (Gem::FilePermissionError)’。您可以使用 ‘brew install ruby’ 的方式解决这个问题，然后重启您的终端。

下面是一个可以工作的 gem 列表。如果 jekyll 安装成为问题，请坚持使用这些版本。

最新版的 kylin 发布提供了 dockerfile，来减少构建复杂性使用 docker 和 Makefile 能调用 docker 命令。

  1. $ pwd
  2. /Users/<username>/kylin/website
  3. $ make docker.build
  4. docker build -f Dockerfile -t kylin-document:latest .
  5. Sending build context to Docker daemon  82.44MB
  6. Step 1/3 : FROM jekyll/jekyll:2.5.3
  7.  ---> e81842c29599
  8. Step 2/3 : RUN gem install jekyll-multiple-languages -v 1.0.11
  9.  ---> Using cache
  10.  ---> e9e8b0f1d388
  11. Step 3/3 : RUN gem install rouge -v 3.0.0
  13.  ---> 1bd42c6b93c0
  14. Successfully built 1bd42c6b93c0
  15. Successfully tagged kylin-document:latest
  16. $ make runserver
  17. docker run --volume="/Users/<username>/kylin/website:/srv/jekyll" -p 4000:4000 --rm -it kylin-document:latest jekyll server --watch
  18. Configuration file: /srv/jekyll/_config.yml
  19.             Source: /srv/jekyll
  20.        Destination: /srv/jekyll/_site
  21.       Generating...
  22. ...

Jekyll 是一个用于从源文本和主题生成静态 HTML 网站的 Ruby 脚本，HTML 在部署到 Web 服务器之前生成。Jekyll 恰好也是 GitHub 页面背后的引擎。

Apache Kylin 的网站和文档使用 Jekyll 来管理和生成，可在 http://kylin.apache.org 上看到最终内容。

Kylin 文档结构以及导航菜单

作为 Jekyll 源的 Kylin 网站是在 doucment 分支下维护的。

  1. Home Page：“index.md” 文档的主页
  2. Installation：“install” Apache Kylin 安装指南
  3. Tutorial：“tutorial” 关于用户如何使用 Apache Kylin 的教程
  4. How To：“howto” 更细节的帮助指南
  5. Development：“development” 为了开发者贡献，集成其它应用和扩展 Apache Kylin
  6. Others：其它文档。

菜单由 Jekyll 集合管理：

  • _data/docs.yml：英文版本菜单结构
  • _data/docs-cn.yml：中文版本菜单结构
  • add new menu item：添加新的条目：在相关文件夹下创建新文档，例如 howto_example.md。添加如下的前标记：

将链接更改为完全链接
然后将条目添加到 docs.yml，如：

  1. - title: How To
  2.   docs:
  3.   - howto/howto_contribute
  5.   - howto/howto_example

如何编写文档

使用任何 markdown 编辑器打开文档，草拟内容并在本地预览。

样例文档：

如何添加图片

  1. ![](/images/Kylin-Web-Tutorial/2 tables.png)

如何添加连接

使用站点链接的相对路径，例如

如何添加代码高亮

我们使用 突出显示代码语法。
查看此 doc 的源代码以获取更多详细信息示例。

如何在本地预览

您可以在 markdown 编辑器中预览，要检查网站上的确切内容，请从 website 文件夹中运行 Jekyll：

  1. jekyll server

然后在浏览器中访问

  1. cd website
  2. svn co https://svn.apache.org/repos/asf/kylin/site _site

_site 文件夹是工作目录，将由 maven 或 git 随时删除，请确保只有当你想要发布到网站时从 svn 检出。

  1. cd website
  2. jekyll s
  3. 在您的浏览器打开 http://127.0.0.1:4000
  1. 拷贝 jekyll 生成的 _site 到 svn 的 website/_site
  2. cd website/_site
  3. svn status
  4. svn commit -m 'UPDATE MESSAGE'

在几分钟内，svnpubsub 应该开始且您将能够在 看到结果。