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:
- First, make sure Ruby and Gem work on your machine
- 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-multiple-languages 1.0.8is the known working version.
- eg. Use
gem install jekyll --version "=2.5.3"to install a specific version.
- eg. Use
- And optionally any markdown editor you prefer
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.
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
- Home Page: “index.md” Home page of Docs
- Getting Started: “gettingstarted” General docs about Apache Kylin, including FAQ, Terminology
- Installation: “install” Apache Kylin installation guide
- Tutorial: “tutorial” User tutorial about how to use Apache Kylin
- How To: “howto” Guide for more detail help
- Development: “development” For developer to contribute, integration with other application and extend Apache Kylin
- 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.
--- 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:
How to add link
Using relative path for site links, for example:
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
Then access http://127.0.0.1:4000 in your browser.
How to publish to website (for committer only)
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.
Before opening a pull request or push to git repo, you can preview changes from your local box with following:
- Open http://127.0.0.1:4000 in your browser
Pushing to site
- Copy jekyll generated
- You will need to
svn addany new files
svn commit -m 'UPDATE MESSAGE'
Within a few minutes, svnpubsub should kick in and you’ll be able to
see the results at