{ “title”: “Docs Format Specification”, “language”: “en” }
This document primarily introduces:
Formatting specifications for the document, including the file name, URL, and layout.
Recommending the use of markdown features for the content.
Whether it is a historical version or the latest version of the docs, all modifications should submit pull requests to the apache/doris-website repository.
If you need to submit docs change, please refer to the Docs Contribution Guide.
The file name should provide a brief summary of the content and should not be too long
If the file name consists of multiple English words, they should be separated by hyphens “-”, and the use of underscores “_” is not recommended.
When a specific SQL function requires an underscore, please follow the naming convention.
When referring to company brands, product names, technical terms, etc. it is recommended to directly use the proprietary name and must use the correct capitalization.
| Proprietary Name |
|---|
| GitHub |
| SQL |
| CPU |
| FE |
| BE |
| HTTP |
| MySQL |
| MongoDB |
| Elasticsearch |
| Azure |
| AWS |
| S3 |
| Doris Manager |
| WebUI |
| Flink Doris Connector |
SQL function and SQL manual should follow the syntax conventions, it is recommended the names be written in all uppercase letters, such as “ARRAY_MAX”
:::tip For details about the layout of SQL function documentation, please refer to the Docs Contribution - How to write SQL Manual :::
It is recommended to provide the full meaning of an abbreviation when it first appears in the body of the document.
It is not recommended use abbreviation in Titles
The title of Documentation uses { "title": "", "language": ""} instead of #
The body starts with the level 2 title, and ends with the level 3 title. If there is a need to differentiate content even after using a third-level heading, you can use numbered list, bullet points, details tag, tabs components to indicate the further levels of hierarchy. (Please refer to relevant guidelines below)
{ "title": "Here is level 1 title", "language": "en" } ## Level 2 title ### Level 3 title
Introduction should provide a highly summarized overview of the content. It is recommended to keep the introduction within 150 words or less. For Examples:
:::tip In this tutorial, you will learn:
What is XXX or What XXX, XXX, XXX are
How to XXX
When to use XXX :::
The Tab key and the Space key are commonly used for alignment. Therefore, the following recommendations are suggested:
Use the Tab key for alignment and avoid mixing the usage of tabs and spaces.
Set the tab size to be equivalent to four half-width spaces in Markdown editors, such as Visual Studio Code.
Indentation may affect document rendering results, which is subject to correct rendering by rich text editors such as vscode (e.g., code blocks within a multi-level indentation structure sometimes still require 0-level indentation to render correctly).
Numbered lists typically emphasize the priority order between items. When using numbered lists and bullet points, the following guidelines should be followed:
For numbered lists, it is recommended to use Bold text to align the text with the higher-level hierarchy without indentation.
When a numbered list contains bullet points, the numbered list is recommended be bolded, while the bullet points do not need to be bolded.
When using link, it is recommended to follow the following guidelines:
1. Link Description
Link descriptions are not advisable to repeatedly use phrases such as “see details,” “refer to,” or “see specific information” within the same document.
2. Link Format
Link to other headings within the same document, such as Inverted Index
Link to adjacent documents: BITMAP Index
Link to external websites: Wikipedia - Inverted Index
3. Link Paths
It is recommended to use either relative paths or paths consistently within the same document, avoiding mixing them.
It is advisable to minimize redirects to external sites to prevent broken links from affecting the user experience. If linking to an external site is necessary, it is recommended to inform users that they will be redirected to an external website, such as “Click to visit XXX.”
You can create fenced code blocks by placing triple backticks(```) before and after the code block. We recommend placing a blank line before and after code blocks to make the raw formatting easier to read.
You can add an optional language identifier to enable syntax highlighting in your fenced code block:
| Language | Syntax Higlighting |
|---|---|
| Shell | ```shell``` |
| Python | ```python``` |
| JSON | ```json``` |
| XML | ```xml``` |
| SQL | ```sql``` |
| YAML | ```yaml``` or ```yml``` |
| Markdown | ```markdown``` or```md``` |
| JavaScript | ```js``` or ```javascript``` |
| Java | ```java``` |
| C++ | ```cpp``` |
| C | ```c``` |
| Ruby | ```ruby``` |
| HTML | ```html``` |
| CSS | ```css``` |
| PHP | ```php``` |
When using the ```shell` code block, it is recommended to separate the command and the output results. Here is an example:
kubectl get pod --namespace doris
NAME READY STATUS RESTARTS AGE doriscluster-helm-fe-0 1/1 Running 0 1m39s doriscluster-helm-fe-1 1/1 Running 0 1m39s doriscluster-helm-fe-2 1/1 Running 0 1m39s doriscluster-helm-be-0 1/1 Running 0 16s doriscluster-helm-be-1 1/1 Running 0 16s doriscluster-helm-be-2 1/1 Running 0 16s
We have special admonitions syntax by wrapping text with a set of 3 colons, followed by a label denoting its type. When you want to emphasize the content, it is recommended to use admonitions.
In use, the following specifications need to be followed:
Tip: mainly used for operational tips and tricks.
Note: used for more details and explanations.
Caution: used for warnings and precautions.
You may also specify an optional title. Here are the examples of admonitions syntax:
:::tip Tip Some content with tips ::: :::info Note Some content with explanations ::: :::caution Warning Some content with precuations and warnings :::
When you want to display images, it is convenient to co-locate the asset next to the Markdown file using it. For image directory structure, please refer to Docs Contribution.
You can display images in two different ways:
Simple syntax: 
If you want the image to be centered, you can use HTML as following:
<div style={{textAlign:'center'}}> <img src="co-locate file structure or link" alt="images descrition" style={{display: 'inline-block'}}/> </div >
To wrap lines within a table, you can use the HTML: <p>XXXX</p>
The details tag can be used to differentiate content if there is a need to differentiate content even after using a third-level heading.
Here is an example of the details tag in Markdown:
<details> <summary>Title</summary> Here is the details <p>If you need to wrap your line, you can use HTML controls</p> <p>XXXXXXXX</p> </details>
TabsComponentUsing Tabs components please refer to the following syntax:
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; <Tabs> <TabItem value="Title 1" label="Title 1" default> <p>XXXXX</p> <p>XXXXX</p> </TabItem> <TabItem value="Title 2" label="Title 2" default> <p>XXXXX</p> <p>XXXXX</p> </TabItem> </Tabs>
It is not recommended to use version tags to distinguish between different versions.
If features need to be version-specific, it is suggested to use admonitions (refer to point six) with the :::tip :::
It is not recommended to use the > to quotation for content descriptions.
If there is a need for more details or explanations, it is suggested to use admonitions (refer to point six) with the :::info ::: annotation.