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.
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
Tiles/subtitles should have one empty line from its content.
# <File Title> <--empty line--> ...content... <--empty line--> ## Header 1 <--empty line--> ...content... <--empty line--> ### Header 1.1 <--empty line--> ...content... <--empty line--> ### Header 1.2 <--empty line--> ...content... <--empty line--> ## Head 2 <--empty line--> ...content...
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/concepts.md should be placed in directory
Markdown doesn’t support tables natively. To author tables like:
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
E.g. say we have two files in
/doc/source/dir2/doc2.md. To reference
// doc2.md Please reference more info [here](/dir1/doc1.md).
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
#: ../../source/xxx/mytranslation.md: msgid "Thanks." msgstr "谢谢。" <- note the '。' here