You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In this document, you will find a number of style guidelines for writing documentation.
4
-
The rules in this guide are intended to assist in helping us to create a high
5
-
quality documentation offering on par with the quality of ClickHouse itself.
3
+
In this document, you will find a number of style guidelines for writing ClickHouse
4
+
documentation. As documentation is a collective effort, these guidelines are
5
+
intended to help all of us ensure quality and consistency across our documentation.
6
6
7
7
## YAML front matter
8
8
9
-
Begin every new markdown document with YAML front-matter:
9
+
Begin every new Markdown document with YAML front-matter:
10
10
11
11
```markdown
12
12
---
13
-
title: Using a clickhouse-local database
14
-
sidebar_label: Using clickhouse-local database
13
+
title: 'Using a clickhouse-local database'
14
+
sidebar_label: 'Using clickhouse-local database'
15
15
slug: /chdb/guides/clickhouse-local
16
-
description: Learn how to use a clickhouse-local database with chDB
17
-
keywords: [chdb, clickhouse-local]
16
+
description: 'Learn how to use a clickhouse-local database with chDB'
17
+
keywords: ['chdb', 'clickhouse-local']
18
18
---
19
19
```
20
20
21
+
### Associated markdown rule or CI check
22
+
23
+
#### front-matter validation
24
+
25
+
There is a custom Docusaurus plugin which runs on build that makes the following
26
+
checks on front-matter:
27
+
28
+
- title, description and slug are specified.
29
+
- keywords use flow style arrays with single quoted items e.g.
30
+
`keywords: ['integrations']`
31
+
- single quotes are used for title, description, slug, sidebar_label
32
+
- there is an empty line after the YAML frontmatter block
33
+
34
+
For implementation details see [plugins/frontmatter-validation](https://github.com/ClickHouse/clickhouse-docs/tree/main/plugins/frontmatter-validation)
35
+
21
36
## Explicit header tags
22
37
23
38
Due to the way our translation system works, it is necessary to add an explicit
import clickhouse-local-1 from '@site/static/images/chdb/guides/clickhouse-local-1.png'
62
77
import clickhouse-local-2 from '@site/static/images/chdb/guides/clickhouse-local-2.png'
63
78
import clickhouse-local-3 from '@site/static/images/chdb/guides/clickhouse-local-3.png'
79
+
import Image from '@theme/IdealImage';
64
80
```
65
81
66
-
Use the `<img/>` tag to place your image in the appropriate place:
82
+
To render images we use a fork of the IdealImage plugin. This generates multiple variants of an image, [asynchronously loading them as well as selecting the most appropriate based on the network connection](https://github.com/stereobooster/react-ideal-image/blob/master/introduction.md).
83
+
84
+
Ensure you import the `Image` component as shown above.
85
+
86
+
Use the `<Image/>` tag to place your image in the appropriate place:
67
87
68
88
```markdown
69
89
Here is some example text which refers to the image below:
70
90
71
-
<img src={clickhouse-local-1}
72
-
alt='DESCRIPTION OF THE IMAGE'
73
-
style={{width: '800px'}} // optional
74
-
/>
91
+
<Image img={clickhouse-local-1} alt='DESCRIPTION OF THE IMAGE' size="md" border background="black"/>
75
92
76
93
Here is another paragraph...
77
94
```
78
95
96
+
This component takes a number of props:
97
+
98
+
1.`img` - the imported image
99
+
2.`alt` - mandatory alternate text specified
100
+
3.`size` - either `lg` (width 1024px), `md` (width 600px), `sm` (width 300px) or `logo` (48x). This sets the maximum image size. Lower resolutions maybe used on smaller screens or slower connections.
101
+
4.`border` - Applies a border. **Use for screenshots only.**
102
+
5.`background` - either `white` or `black`. Applicable if your image is transparent. All new images must use `black`.
103
+
79
104
## Codeblocks
80
105
81
106
Codeblocks are defined using backticks. For example:
@@ -92,6 +117,38 @@ Code blocks:
92
117
- Have a title (optional) such as 'Query' or 'Response'
93
118
- Use language `response` if it is for the result of a query.
94
119
120
+
### Highlighting
121
+
122
+
You can highlight lines in a code block using the following keywords:
123
+
124
+
-`highlight-next-line`
125
+
-`highlight-start`
126
+
-`highlight-end`
127
+
128
+
These keywords should be added as comments in the codeblock with the appropriate
129
+
escape symbol for the codeblock language.
130
+
131
+
For example, if the codeblock is SQL:
132
+
133
+
```text
134
+
SELECT UserID, count(UserID) AS Count
135
+
-- highlight-next-line
136
+
FROM mv_hits_URL_UserID
137
+
WHERE URL = 'http://public_search'
138
+
GROUP BY UserID
139
+
ORDER BY Count DESC
140
+
LIMIT 10;
141
+
```
142
+
143
+
If the codeblock is a response:
144
+
145
+
```text
146
+
10 rows in set. Elapsed: 0.026 sec.
147
+
# highlight-next-line
148
+
Processed 335.87 thousand rows,
149
+
13.54 MB (12.91 million rows/s., 520.38 MB/s.)
150
+
```
151
+
95
152
### Associated markdown rule or CI check
96
153
97
154
-[`MD040` enforces that codeblocks have a language specified](/scripts/.markdownlint-cli2.yaml)
@@ -159,4 +216,37 @@ export function Anchor(props) {
159
216
```
160
217
- Replace `<span id="some-id"></span>` with `Anchor id="some-id"/>`
161
218
219
+
### Floating pages
220
+
221
+
In order to prevent pages from becoming 'floating' or 'orphaned' it is
222
+
necessary that you add a newly created page to `sidebars.js`. We have a [custom
223
+
docusaurus plugin](plugins/checkFloatingPages.js) to catch dangling pages.
224
+
225
+
If there is some specific reason that you need to bypass this check, you can
226
+
add an exception to `floating-pages-exceptions.txt` in the plugins directory.
227
+
228
+
When adding a new page from the ClickHouse/ClickHouse repo this check will fail
229
+
unless the file is in a folder which [`sidebars.js`](https://github.com/ClickHouse/clickhouse-docs/blob/main/sidebars.js)
230
+
uses with `type: autogenerated` to generate the navigation items from the markdown
231
+
files in the folder.
232
+
233
+
If you've added a new page on ClickHouse/ClickHouse and this check is failing.
234
+
235
+
For example:
236
+
237
+
```text
238
+
✅ All markdown files passed frontmatter validation.
239
+
Loaded 3 exceptions from /opt/clickhouse-docs/plugins/floating-pages-exceptions.txt
You will need to open a PR on docs repo to add this page to [`floating-pages-exceptions.txt`](https://github.com/ClickHouse/clickhouse-docs/blob/main/plugins/floating-pages-exceptions.txt). Once it is merged
248
+
you can then rerun the docs check on the ClickHouse/ClickHouse repo which
249
+
should pass. Finally open another PR on the docs repo again to remove the
250
+
file from the exception list and add it to `sidebars.js` in the appropriate
import GCS_bucket_1 from '@site/static/images/integrations/data-ingestion/s3/GCS-bucket-1.png';
3
2
import GCS_bucket_2 from '@site/static/images/integrations/data-ingestion/s3/GCS-bucket-2.png';
4
3
import GCS_create_service_account_key from '@site/static/images/integrations/data-ingestion/s3/GCS-create-a-service-account-key.png';
@@ -7,46 +6,47 @@ import GCS_create_service_account_a from '@site/static/images/integrations/data-
7
6
import GCS_create_service_account_2 from '@site/static/images/integrations/data-ingestion/s3/GCS-create-service-account-2.png';
8
7
import GCS_create_service_account_3 from '@site/static/images/integrations/data-ingestion/s3/GCS-create-service-account-3.png';
9
8
import GCS_guide_key from '@site/static/images/integrations/data-ingestion/s3/GCS-guide-key.png';
9
+
import Image from '@theme/IdealImage';
10
10
11
11
<details>
12
12
<summary>Create GCS buckets and an HMAC key</summary>
13
13
14
14
### ch_bucket_us_east1 {#ch_bucket_us_east1}
15
15
16
-
<imgsrc={GCS_bucket_1}alt="Creating a GCS bucket in US East 1" />
16
+
<Imagesize="md"img={GCS_bucket_1}alt="Creating a GCS bucket in US East 1"border />
17
17
18
18
### ch_bucket_us_east4 {#ch_bucket_us_east4}
19
19
20
-
<imgsrc={GCS_bucket_2}alt="Creating a GCS bucket in US East 4" />
20
+
<Imagesize="md"img={GCS_bucket_2}alt="Creating a GCS bucket in US East 4"border />
21
21
22
22
### Generate an Access key {#generate-an-access-key}
23
23
24
24
### Create a service account HMAC key and secret {#create-a-service-account-hmac-key-and-secret}
25
25
26
26
Open **Cloud Storage > Settings > Interoperability** and either choose an existing **Access key**, or **CREATE A KEY FOR A SERVICE ACCOUNT**. This guide covers the path for creating a new key for a new service account.
27
27
28
-
<imgsrc={GCS_create_service_account_key}alt="Generating a service account HMAC key in GCS" />
28
+
<Imagesize="md"img={GCS_create_service_account_key}alt="Generating a service account HMAC key in GCS"border />
29
29
30
30
### Add a new service account {#add-a-new-service-account}
31
31
32
32
If this is a project with no existing service account, **CREATE NEW ACCOUNT**.
33
33
34
-
<imgsrc={GCS_create_service_account_0}alt="Adding a new service account in GCS" />
34
+
<Imagesize="md"img={GCS_create_service_account_0}alt="Adding a new service account in GCS"border />
35
35
36
36
There are three steps to creating the service account, in the first step give the account a meaningful name, ID, and description.
37
37
38
-
<imgsrc={GCS_create_service_account_a}alt="Defining a new service account name and ID in GCS" />
38
+
<Imagesize="md"img={GCS_create_service_account_a}alt="Defining a new service account name and ID in GCS"border />
39
39
40
40
In the Interoperability settings dialog the IAM role **Storage Object Admin** role is recommended; select that role in step two.
41
41
42
-
<imgsrc={GCS_create_service_account_2}alt="Selecting IAM role Storage Object Admin in GCS" />
42
+
<Imagesize="md"img={GCS_create_service_account_2}alt="Selecting IAM role Storage Object Admin in GCS"border />
43
43
44
44
Step three is optional and not used in this guide. You may allow users to have these privileges based on your policies.
45
45
46
-
<imgsrc={GCS_create_service_account_3}alt="Configuring additional settings for the new service account in GCS" />
46
+
<Imagesize="md"img={GCS_create_service_account_3}alt="Configuring additional settings for the new service account in GCS"border />
47
47
48
48
The service account HMAC key will be displayed. Save this information, as it will be used in the ClickHouse configuration.
49
49
50
-
<imgsrc={GCS_guide_key}alt="Retrieving the generated HMAC key for GCS" />
50
+
<Imagesize="md"img={GCS_guide_key}alt="Retrieving the generated HMAC key for GCS"border />
0 commit comments