Skip to main content

How to write document

From Kylin 5.0, Kylin documents are written using Docusaurus. Please note multi-version and i18n (multi-language) is not supported right now, but is in the plan. Contributions are very much appreciated.

Shortcut: Edit a single existing page

Shortcut editing a single page
  1. This shortcut is extreme useful if you found some minor typos or mistakes on a single page, you can edit the document in browser right away in a few minutes without preparation.
  2. But if the change is more complex, like add/edit several pages, upload images, or change global config files, please jump to next paragraph: Before your work.
  1. Just scroll down the page to the bottom and click the Edit this page.

  2. Edit this file in browser.

  3. Propose your changes by raising a pull request.

  4. And you are done! The changes proposed will get reviewed by a reviewer, and if OK, will be merged and be seen by the community.

Before your work

Before adding new documentation, it is best to setup the preview environment first.

  1. Install Node.js

    Make sure Node.js version is 16.14 or above by checking node -v. You can use nvm for managing multiple Node versions on a single machine installed.

    node -v
    Tips

    When installing Node.js via Windows/macOS Installer, recommend to check all checkboxes related to dependencies.

  2. Clone the kylin doc branch

    cd /path/you/prefer/
    git clone --branch doc5.0 https://github.com/apache/kylin.git # Or git clone -b doc5.0 https://github.com/apache/kylin.git
  3. Install the website dependencies

    cd /path/you/prefer/
    cd website
    npm install
    Slow NPM in China?

    Add following lines to ~/.npmrc and npm shall become much faster in China.

    sass_binary_site=https://npm.taobao.org/mirrors/node-sass/
    phantomjs_cdnurl=https://npm.taobao.org/mirrors/phantomjs/
    electron_mirror=https://npm.taobao.org/mirrors/electron/
    registry=https://registry.npm.taobao.org
    Troubleshooting

    Depending on your OS environment, npm install can hit various issues at this stage and most of them are due to missing a certain library. Below are a few examples from a Ubuntu user.

    • If hit error ../src/common.cc:24:10: fatal error: vips/vips8: No such file or directory
      • Try install glib2.0-dev, like sudo apt-get install glib2.0-dev
    • If hit error Error: Command failed: /bin/sh -c autoreconf -ivf
      • Try install autoconf, like sudo apt-get install autoconf

    For more information about Docusaurus, please refer to Docusaurus Installation.

  4. Launch the doc website and preview it locally

    npm run start

    The homepage of this doc site http://localhost:3000 shall automatically open in your default browser if no error occurs. Modify any MD or resource file in your local repository, the changes shall reflect immediately in the browser. Very convenient for doc development.

How to create new document

Step 1: Create a new markdown file with metadata

Create a new markdown file with any text editor, copy and paste following Head Metadata Template to the top your file. After that, replace the variables like ${TITLE OF NEW DOC} with actual values.

---
title: ${TITLE OF NEW DOC}
language: en
sidebar_label: ${TITLE OF NEW DOC}
pagination_label: ${TITLE OF NEW DOC}
toc_min_heading_level: 2
toc_max_heading_level: 6
pagination_prev: null
pagination_next: null
keywords:
- ${KEYWORD OF NEW DOC}
draft: false
last_update:
date: ${DATE of YOUR COMMIT}
author: ${YOUR FULL NAME}
---
Head metadata?

Head metadata is REQUIRED for all doc files. For more information, please refer to docusaurus head metadata.

Step 2: Add content for your new doc

Add text in the markdown format.

Pictures usually go into a subfolder called images.

Step 3: Add new page to the sidebar

Sidebar contains the menu and the navigation tree of the doc site structure. It is maintained in a JS file located at website/sidebars.js.

For example, if you want to add a new doc how_to_write_doc.md to be the child of the development menu. Open the sidebars.js and modify the DevelopmentSideBar block. Add a new block at the tail of items of DevelopmentSideBar.

DevelopmentSideBar: [
{
...
items: [
{...},
...,
{
type: 'doc',
id: 'development/how_to_write_doc'
},
],
},
],

Step 4: Preview the result locally

Saving all the changes, you can preview the result immediately in your browser. Please run following commands in the website directory, and a local version of the doc site shall show up in your browser http://localhost:3000.

cd website
npm run start
Check your doc
  • Whether the look and feel meet expectation?
  • Whether the link/pictures work fine?
  • Whether the important info is properly highlighted? How to highlight?
  • Whether the title levels follow the heading guide?

Step 5: Create a pull request

When everything looks fine, create a pull request to the kylin doc5.0 branch.

What, Pull Request?

For those who are new to pull requests, here it is explained.


Documentation Specification

About Docusaurus

Docusaurus is a static-site generator. It builds a single-page application with fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features but can be used to create any kind of site (personal website, product, blog, marketing landing pages, etc).

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

Kylin document structure and navigation menu

The Kylin website material is maintained under the doc5.0 branch.

  1. Home Page: Home page of Docs
  2. Document: General docs about Apache Kylin, including Installation, Tutorial, etc.
  3. Development: "development" For developer to contribute, to develop, integration with other application and extend Apache Kylin
  4. Download: "Download" Apache Kylin packages
  5. Community: Apache kylin Community information
  6. Blog: Engineering blogs about Apache Kylin

Full doc structure

The full doc structure about the newest Apache Kylin:

doc5.0
.
├── README.md
├── babel.config.js
├── blog
│ ├── ...
├── docs
│ ├── community.md
│ ├── configuration
│ │ ├── ...
│ ├── datasource
│ │ ├── ...
│ ├── deployment
│ │ ├── ...
│ ├── development
│ │ ├── ...
│ ├── download.md
│ ├── integration
│ │ └── intro.md
│ ├── intro.md
│ ├── modeling
│ │ ├── ...
│ ├── monitor
│ │ ├── ...
│ ├── operations
│ │ ├── ...
│ ├── powerBy.md
│ ├── query
│ │ ├── ...
│ ├── quickstart
│ │ ├── ...
│ ├── restapi
│ │ ├── ...
│ ├── snapshot
│ │ ├── ...
│ └── tutorial
│ ├── ...
├── docusaurus.config.js
├── package.json
├── sidebars.js
├── src
│ ├── components
│ │ └── ...
│ ├── css
│ │ └── ...
│ └── pages
│ ├── ...
├── static
│ └── img
│ ├── ...

More details about structure which managed by Docusaurus, please refer to Project structure rundown.

Title/Heading Level

Here is official guide about heading. Please use level 3 title("###") and level 4 title("####") in most of the article.

Following is a general guide:

  • Use level 2 heading(aka "##") as top level title. The number of top level title should not more than two.
  • Use level 3 heading(aka "###") as middle level title.
  • Use level 4 heading(aka "####") as the lowest level title.

We recommend you to check for this article for example. Following is toc of it.

## Guide for Contributor
### Detailed Description
#### Step 1: Fork Apache Kylin Repo
#### Step 2: Clone the fork repo
#### Step 3: xxx
#### Step 4: xxx
...

## Guide for Reviewer
### Code Review Guideline
### Patch +1 Policy
...

The Sidebar is managed by sidebars.js , please refer to Sidebar.

How to add image in doc

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

![](images/how-to-write-doc-01.png)

Using relative path for site links, check this Markdown links

How to add source code in doc

We are using Code Block to highlight code syntax, check this doc for more detail sample.

How to highlight a sentence/paragraph

We recommend you to use admonitions feature to highlight a sentence/paragraph, following is a example:

:::caution
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::