DJI SDK Markdown Document Update Guide
oliverou opened this issue · comments
Workflow
Official updates will be handled by DJI SDK staff. If an issue/bug is found in our documents, developers are welcome to correct the error and submit a pull request.
Developers must alert the DJI SDK staff of a pull request through a related discussion, such as on forum.dji.com, bbs.dji.com, github issues or email record. If the pull request is valid, the SDK staff will acknowledge the issue being fixed and accept the pull request.
Pull requests that do not follow this guide will not be accepted.
Formatting Markdown Documents
This section covers document formatting and syntax. You can refer to Github's Mastering Markdown Guides for additional reference.
1. Formatting headers with the hashtag symbol #
We structure markdown documents through the use of #
symbol to create headers. Multiple #
symbols in a row will format smaller headers. Here is a suggested usage example:
Code
# Document Title
## Main Heading 1
### 1. Subheading 1
## Main Heading 2
### 1. Subheading 1
### 2. Subheading 2
Result
Document Title
Main Heading 1
1. Subheading 1
Main Heading 2
1. Subheading 1
2. Subheading 2
It is important that you follow the example shown above, with a single '#' being used for the document title, '##' being used for section headings, and '###' being used for subheadings. This allows us to generate and organize reading interfaces based on these headings.
Please do not adjust the number of '#' symbols used for the aesthetic purpose of adjusting the side of headings, as shown here:
Code
# Document Title
## Main Heading 1
### 1. Subheading 1
## Main Heading 2
### 1. Subheading 1
### 2. Subheading 2
Result
Document Title
Main Heading 1
1. Subheading 1
Main Heading 2
1. Subheading 1
2. Subheading 2
2. Tables
Markdown allows you to create tables, separating the header with the first row with hyphens '-', and separating each column with a pipe symbol '|'.
Here's an example:
Code
First Header | Second Header
------------- | -------------
Content Cell | Content Cell
Content Cell | Content Cell
Result
First Header | Second Header |
---|---|
Content Cell | Content Cell |
Content Cell | Content Cell |
You can also choose to align cell contents:
Code
| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:----------------:| -------------:|
| Left | Center | Right |
| Left Aligned | Center Aligned | Right Aligned |
Result
Left Aligned | Center Aligned | Right Aligned |
---|---|---|
Left | Center | Right |
Left Aligned | Center Aligned | Right Aligned |
We control text alignment through the colons ':'. The left and right most pipes |
are purely aesthetic, and can be omitted. Blank spaces serve no functional purpose besides code readability.
3. Images
All images should be stored in the Images
folder. Images should be refered to by their relative path name, rather than an absolute path name.
For example, you should use ![N1UI](Images/N1UI.png)
instead of ![N1UI](https://github.com/dji-sdk/Onboard-SDK/blob/master/Onboard_API_Doc/en/Images/N1UI.png)
4. Code
Inline code blocks should be wrapped in backticks:
Code
'var example = true'
Result
var example = true
To insert multiple lines of code, used a Fenced Code Block. Surround code with three tildes '~' to format it:
Code
~~~
void get_control_callback(const void* p_data, unsigned int n_size) { }
~~~
Result
void get_control_callback(const void* p_data, unsigned int n_size) { }
Including the name of the language after the opening triple tilde will allow for syntax highlighting:
Code
~~~c
void get_control_callback(const void* p_data, unsigned int n_size) { }
~~~
Result
void get_control_callback(const void* p_data, unsigned int n_size) { }