We write documents in MD format and convert to HTML using Jekyll. The Jekyll generated HTML gets uploaded to apache SVN and becomes Kylin website. All MD source files are managed in git so all changes and contributors are clearly tracked.

Before your work

Install following tools before you add or edit documentation:

  1. First, make sure Ruby and Gem work on your machine
  2. Then, install Jekyll, and required plugins
    • gem install jekyll jekyll-multiple-languages kramdown rouge
    • Note: Some specific version of jekyll and jekyll-multiple-languages does not work together (I got a “undefined method” error with jekyll 3.0.1 and jekyll-multiple-languages 2.0.3). In that case, jekyll 2.5.3 and jekyll-multiple-languages 1.0.8 is the known working version.
      • eg. Use gem install jekyll --version "=2.5.3" to install a specific version.
  3. And optionally any markdown editor you prefer

About Jekyll

Jekyll is a Ruby script to generate a static HTML website from source text and themes, the HTML is generated before being deployed to the web server. Jekyll also happens to be the engine behind GitHub Pages.

Here are good reference about basic usage of Jekyll: Learning Jekyll By Example

Apache Kylin’s website and documentation is using Jekyll to manage and generate final content which avaliable at http://kylin.apache.org.

Multi-Language

To draft Chinese version document or translate existing one, just add or copy that doc and name with .cn.md as sufffix. It will generate under /cn folder with same name as html file.
To add other language, please update _config.yml and follow the same pattern as Chinese version.

Kylin document structure and navigation menu

The Kylin website as the Jekyll source is maintained under the doucment branch.

  1. Home Page: “index.md” Home page of Docs
  2. Getting Started: “gettingstarted” General docs about Apache Kylin, including FAQ, Terminology
  3. Installation: “install” Apache Kylin installation guide
  4. Tutorial: “tutorial” User tutorial about how to use Apache Kylin
  5. How To: “howto” Guide for more detail help
  6. Development: “development” For developer to contribute, integration with other application and extend Apache Kylin
  7. Others: Other docs.

The menu is managed by Jekyll collection:

  • _data/docs.yml: English version menu structure
  • _data/docs-cn.yml: Chinese version menu structure
  • add new menu item: To add new item: create new docs under relative folder, e.g howto_example.md. add following Front Mark:
---
layout: docs
title:  How to expamle
categories: howto
permalink: /docs/howto/howto_example.html
version: v0.7.2
since: v0.7.2
---

change the permalink to exactly link
Then add item to docs.yml like:

- title: How To
  docs:
  - howto/howto_contribute
  - howto/howto_jdbc
  - howto/howto_example

How to edit document

Open doc with any markdown editor, draft content and preview in local.

Sample Doc:

---
layout: docs
title:  How to example
categories: howto
permalink: /docs/howto/howto_example.html
version: v0.7.2
since: v0.7.2
---

## This is example doc
The quick brown fox jump over the lazy dog.

How to add image

All impage please put under images folder, in your document, please using below sample to include image:

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

How to add link

Using relative path for site links, for example:

[REST API](docs/development/rest_api.html). 

How to add code highlight

We are using Rouge to highlight code syntax.
check this doc’s source code for more detail sample.

How to preview in your local

You can preview in your markdown editor, to check exactly what it will looks like on website, please run Jekyll from website folder:

jekyll server

Then access http://127.0.0.1:4000 in your browser.

How to publish to website (for committer only)

Setup

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

_site folder is working dir which will be removed anytime by maven or git, please make sure only check out from svn when you want to publish to website.

Running locally

Before opening a pull request or push to git repo, you can preview changes from your local box with following:

  1. cd website
  2. jekyll s
  3. Open http://127.0.0.1:4000 in your browser

Pushing to site

  1. Copy jekyll generated _site to svn website/_site
  2. cd website/_site
  3. svn status
  4. You will need to svn add any new files
  5. svn commit -m 'UPDATE MESSAGE'

Within a few minutes, svnpubsub should kick in and you’ll be able to
see the results at
http://kylin.apache.org.