Skip to content

Latest commit

 

History

History
252 lines (183 loc) · 9.15 KB

style-guide.md

File metadata and controls

252 lines (183 loc) · 9.15 KB

ClickHouse docs style guide

In this document, you will find a number of style guidelines for writing ClickHouse documentation. As documentation is a collective effort, these guidelines are intended to help all of us ensure quality and consistency across our documentation.

YAML front matter

Begin every new Markdown document with YAML front-matter:

---
title: 'Using a clickhouse-local database'
sidebar_label: 'Using clickhouse-local database'
slug: /chdb/guides/clickhouse-local
description: 'Learn how to use a clickhouse-local database with chDB'
keywords: ['chdb', 'clickhouse-local']
---

Associated markdown rule or CI check

front-matter validation

There is a custom Docusaurus plugin which runs on build that makes the following checks on front-matter:

  • title, description and slug are specified.
  • keywords use flow style arrays with single quoted items e.g. keywords: ['integrations']
  • single quotes are used for title, description, slug, sidebar_label
  • there is an empty line after the YAML frontmatter block

For implementation details see plugins/frontmatter-validation

Explicit header tags

Due to the way our translation system works, it is necessary to add an explicit anchor tag next to every header, such as {#explicit-anchor-tag}.

For example:

## My header {#my-header}

Associated markdown rule or CI check

Images

In all cases images get added to the static/images directory of the repository. Under the images directory you should place the images according to the folder structure of the docs.

For example, if you wanted to add images to clickhouse-local.md which is located at /docs/chdb/guides/clickhouse-local.md. You should add the images at /static/images/chdb/guides/.

Try to use descriptive names in lower case. For example:

  • clickhouse-local-1.png
  • clickhouse-local-2.png
  • clickhouse-local-3.png etc.

In the markdown document import the images under the YAML frontmatter:

---
title: Using a clickhouse-local database
sidebar_label: Using clickhouse-local database
slug: /chdb/guides/clickhouse-local
description: Learn how to use a clickhouse-local database with chDB
keywords: [chdb, clickhouse-local]
---

import clickhouse-local-1 from '@site/static/images/chdb/guides/clickhouse-local-1.png'
import clickhouse-local-2 from '@site/static/images/chdb/guides/clickhouse-local-2.png'
import clickhouse-local-3 from '@site/static/images/chdb/guides/clickhouse-local-3.png'
import Image from '@theme/IdealImage';

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.

Ensure you import the Image component as shown above.

Use the <Image/> tag to place your image in the appropriate place:

Here is some example text which refers to the image below:

<Image img={clickhouse-local-1} alt='DESCRIPTION OF THE IMAGE' size="md" border background="black"/>

Here is another paragraph...

This component takes a number of props:

  1. img - the imported image
  2. alt - mandatory alternate text specified
  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.
  4. border - Applies a border. Use for screenshots only.
  5. background - either white or black. Applicable if your image is transparent. All new images must use black.

Codeblocks

Codeblocks are defined using backticks. For example:

\```sql title='Query'
SELECT * FROM system.contributors;
\```

Code blocks:

  • Should always have a language defined immediately next to the opening 3 backticks, without any space.
  • Have a title (optional) such as 'Query' or 'Response'
  • Use language response if it is for the result of a query.

Highlighting

You can highlight lines in a code block using the following keywords:

  • highlight-next-line
  • highlight-start
  • highlight-end

These keywords should be added as comments in the codeblock with the appropriate escape symbol for the codeblock language.

For example, if the codeblock is SQL:

SELECT UserID, count(UserID) AS Count
-- highlight-next-line
FROM mv_hits_URL_UserID
WHERE URL = 'http://public_search'
GROUP BY UserID
ORDER BY Count DESC
LIMIT 10;

If the codeblock is a response:

10 rows in set. Elapsed: 0.026 sec.
# highlight-next-line
Processed 335.87 thousand rows,
13.54 MB (12.91 million rows/s., 520.38 MB/s.)

Associated markdown rule or CI check

Broken links

Making a change to a page slug or moving a file can result in broken links in numerous places across the docs. To mitigate this we use the built in link checker provided by Docusaurus. If broken links are found then docs check will fail with an error message something like this:

Exhaustive list of all broken links found:

- Broken link on source page path = /docs/observability/integrating-opentelemetry:
   -> linking to /docs/observability/schema-design#using-maps
- Broken link on source page path = /docs/operations/server-configuration-parameters/settings:
   -> linking to ../../../engines/table-engines/mergetree-family/mergetree#mergetree-table-ttl (resolved as: /engines/table-engines/mergetree-family/mergetree#mergetree-table-ttl)
- Broken link on source page path = /docs/partitions:
   -> linking to /docs/optimize/sparse-primary-indexes#data-is-organized-into-granules-for-parallel-data-processing

To fix the links, find the source page, given after source page path = and search within it for the link given after linking to. As slugs are resolved relative to /docs you can exclude this from your search. E.g don't search /docs/observability/schema-design#using-maps but /observability/schema-design#using-maps

note if you can't find the link on the page but you're sure that you are looking in the file reported by the failing broken link checker, the link is most likely found in a snippet which is imported by that page. Find the snippet location from the import statement at the top of the page.

Broken anchors

Docusaurus also has a built-in broken anchor checker. Unfortunately it sometimes can give false positives.

linking to spans

Sometimes you want to link to something other than a header. It is logical to use a span for this purpose. For instance if you want to link to an image.

<span id="page-2-0"></span><img src={image_02}/>

As shown by [Figure 2,](#page-2-0)...

Unfortunately, docusaurus' anchor checker will throw an error on this link:

- Broken anchor on source page path = /docs/academic_overview:
   -> linking to #page-1-0 (resolved as: /docs/academic_overview#page-1-0)

Follow the steps below for the workaround:

  • change the file from .md to .mdx
  • import useBrokenLinks hook with import useBrokenLinks from "@docusaurus/useBrokenLinks";
  • add the following component to the page:
export function Anchor(props) {
    useBrokenLinks().collectAnchor(props.id);
    return <span style={{scrollMarginTop: "var(--ifm-navbar-height)"}} {...props}/>;
}
  • Replace <span id="some-id"></span> with Anchor id="some-id"/>

Floating pages

In order to prevent pages from becoming 'floating' or 'orphaned' it is necessary that you add a newly created page to sidebars.js. We have a custom docusaurus plugin to catch dangling pages.

If there is some specific reason that you need to bypass this check, you can add an exception to floating-pages-exceptions.txt in the plugins directory.

When adding a new page from the ClickHouse/ClickHouse repo this check will fail unless the file is in a folder which sidebars.js uses with type: autogenerated to generate the navigation items from the markdown files in the folder.

If you've added a new page on ClickHouse/ClickHouse and this check is failing.

For example:

✅ All markdown files passed frontmatter validation.
Loaded 3 exceptions from /opt/clickhouse-docs/plugins/floating-pages-exceptions.txt
Skipping excepted page: index
Skipping excepted page: integrations/language-clients/java/client-v1
Skipping excepted page: integrations/language-clients/java/jdbc-v1
�[31m1 floating pages found:�[0m
  - /opt/clickhouse-docs/docs/operations/query-condition-cache.md

You will need to open a PR on docs repo to add this page to floating-pages-exceptions.txt. Once it is merged you can then rerun the docs check on the ClickHouse/ClickHouse repo which should pass. Finally open another PR on the docs repo again to remove the file from the exception list and add it to sidebars.js in the appropriate sidebar.