Documentation Formatting Rules

This page describes the enforced formatting rules when authoring Hologres documenations.


Each pull request of documentation must be written at least in English.

PR in both English and Chinese would be even better.

Documentation Format

Hologres documentation are written in .md markdown files.

Contributers should following standard markdown formatting with the following rules in mind.

File and Paragraph Tiles

Title of each markdown file should use # as heading.

Subtitles of sections inside should then use ##, ###, etc.

Tiles/subtitles should have one empty line from its content.


# <File Title>
	<--empty line-->
	<--empty line-->
## Header 1
	<--empty line-->
	<--empty line-->
### Header 1.1
	<--empty line-->
	<--empty line-->
### Header 1.2
	<--empty line-->
	<--empty line-->
## Head 2
	<--empty line-->


Images in markdown files should be placed in the directory of /image, and the directory should reflect the same document structure of the markdown files.

E.g. images of page /doc/source/introduction/ should be placed in directory /doc/source/images/introduction/.


Markdown doesn’t support tables natively. To author tables like:

1 3
2 4

you have to install the sphinx-makrdown-tables as mentioned in pre-requisites above, and author in the following format:

| A | B |
| 1 | 3 |
| 2 | 4 |

Cross-Reference Another File

You can cross reference another markdown file in the same repository by using the absolute path in the root directory of /source.

E.g. say we have two files in /doc/source/dir1/ and /doc/source/dir2/ To reference in, author:

Please reference more info [here](/dir1/


DO NOT forget to put the correct punctuations in your translations!

If the original sentense ends with a English period ., translators should end their translated sentense with a Chinese period . E.g.

#: ../../source/xxx/
msgid "Thanks."
msgstr "谢谢。"  <- note the '。' here