mirror of
https://github.com/ClickHouse/ClickHouse.git
synced 2024-12-11 08:52:06 +00:00
98 lines
4.6 KiB
Markdown
98 lines
4.6 KiB
Markdown
## Generating ClickHouse documentation {#how-clickhouse-documentation-is-generated}
|
||
|
||
ClickHouse documentation is built using [Docusaurus](https://docusaurus.io).
|
||
|
||
## Check the look of your documentation changes {#how-to-check-if-the-documentation-will-look-fine}
|
||
|
||
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 {#install-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 {#use-build-py}
|
||
|
||
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](https://github.com/ClickHouse/ClickHouse)
|
||
- [ClickHouse/ClickHouse-docs](https://github.com/ClickHouse/clickhouse-docs)
|
||
|
||
### Install Node.js
|
||
|
||
The documentation is built with Docusaurus, which requires Node.js. We recommend version 16. Install [Node.js](https://nodejs.org/en/download/).
|
||
|
||
### 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:
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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? {#how-to-change-code-hl}
|
||
|
||
Code highlighting is based on the language chosen for your code blocks. Specify the language when you start the code block:
|
||
|
||
<pre lang="no-highlight"><code>```sql
|
||
SELECT firstname from imdb.actors;
|
||
```
|
||
</code></pre>
|
||
|
||
```sql
|
||
SELECT firstname from imdb.actors;
|
||
```
|
||
|
||
If you need a language supported then open an issue in [ClickHouse-docs](https://github.com/ClickHouse/clickhouse-docs/issues).
|
||
## How to subscribe on documentation changes? {#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](https://join.slack.com/t/clickhousedb/shared_invite/zt-qfort0u8-TWqK4wIP0YSdoDE0btKa1w).
|
||
- Some search engines allow to subscribe on specific website changes via email and you can opt-in for that for https://clickhouse.com.
|