ClickHouse/docs/tools/README.md

Generating ClickHouse documentation

ClickHouse documentation is built using Docusaurus.

Check the look of your documentation changes

There are a few options that are all useful depending on how large or complex your edits are.

Use the GitHub web interface to edit

Every page in the docs has an Edit this page link that opens the page in the GitHub editor. GitHub has Markdown support with a preview feature. The details of GitHub Markdown and the documentation Markdown are a bit different but generally this is close enough, and the person merging your PR will build the docs and check them.

Install a Markdown editor or plugin for your IDE

Usually, these plugins provide a preview of how the markdown will render, and they catch basic errors like unclosed tags very early.

Build the docs locally

You can build the docs locally. It takes a few minutes to set up, but once you have done it the first time, the process is very simple.

Clone the repos

The documentation is in two repos, clone both of them:

• ClickHouse/ClickHouse
• ClickHouse/ClickHouse-docs

Install Node.js

The documentation is built with Docusaurus, which requires Node.js. We recommend version 16. Install Node.js.

Copy files into place

Docusaurus expects all of the markdown files to be located in the directory tree clickhouse-docs/docs/. This is not the way our repos are set up, so some copying of files is needed to build the docs:

# from the parent directory of both the ClickHouse/ClickHouse and ClickHouse-clickhouse-docs repos:
cp -r ClickHouse/docs/en/development     clickhouse-docs/docs/en/
cp -r ClickHouse/docs/en/engines         clickhouse-docs/docs/en/
cp -r ClickHouse/docs/en/getting-started clickhouse-docs/docs/en/
cp -r ClickHouse/docs/en/interfaces      clickhouse-docs/docs/en/
cp -r ClickHouse/docs/en/operations      clickhouse-docs/docs/en/
cp -r ClickHouse/docs/en/sql-reference   clickhouse-docs/docs/en/

cp -r ClickHouse/docs/ru/*               clickhouse-docs/docs/ru/
cp -r ClickHouse/docs/zh                 clickhouse-docs/docs/

Note: Symlinks will not work.

Setup Docusaurus

There are two commands that you may need to use with Docusaurus:

• yarn install
• yarn start

Install Docusaurus and its dependencies:

cd clickhouse-docs
yarn install

Start a development Docusaurus environment

This command will start Docusaurus in development mode, which means that as you edit source (for example, .md files) files the changes will be rendered into HTML files and served by the Docusaurus development server.

yarn start

Make your changes to the markdown files

Edit your files. Remember that if you are editing files in the ClickHouse/ClickHouse repo then you should edit them in that repo and then copy the edited file into the ClickHouse/clickhouse-docs/ directory structure so that they are updated in your develoment environment.

yarn start probably opened a browser for you when you ran it; if not, open a browser to http://localhost:3000/docs/en/intro and navigate to the documentation that you are changing. If you have already made the changes, you can verify them here; if not, make them, and you will see the page update as you save the changes.

How to change code highlighting?

Code highlighting is based on the language chosen for your code blocks. Specify the language when you start the code block:

```sql
SELECT firstname from imdb.actors;
```

SELECT firstname from imdb.actors;

If you need a language supported then open an issue in ClickHouse-docs.

How to subscribe on documentation changes?

At the moment there’s no easy way to do just that, but you can consider:

• To hit the “Watch” button on top of GitHub web interface to know as early as possible, even during pull request. Alternative to this is #github-activity channel of public ClickHouse Slack.
• Some search engines allow to subscribe on specific website changes via email and you can opt-in for that for https://clickhouse.com.