Project layout
.
|-- contributors.txt # Contributors
|-- docs # Documents dir
| |-- index.adoc # Homepage on Github Pages
| |-- Document1 # Section's (Level 0) dir
| | |-- section1 # Section's (Level 1) dir
| | | |-- section1-1.adoc # Section (Level 2)
| | | `-- ...
| | |-- section1.adoc # Section (Level 1)
| | `-- ...
| |-- Document1.adoc # Section (Level 0)
| |-- README-CN.adoc # README in Chinese
| |-- README-EN.adoc # README in English
| `-- ...
|-- fonts # Fonts dir
|-- Gemfile
|-- images # Images dir
| |-- Document1 # Document1's image dir
| `-- ...
|-- LICENSE # License
|-- public # Output dir
|-- Rakefile
|-- README.adoc # README
|-- themes # Themes dir
| |-- docinfo-footer.html
| |-- html.css # HTML theme
| `-- pdf.yml # PDF theme
`-- ...File names are all lowercase, with “-” instead of spaces. The file name of the document in English/Chinese ends with “EN”/“CN”. File naming and folder structure should be consistent in the title level.
= Document Title (Level 0)
== Level 1 Section Title
=== Level 2 Section Title
...Section
Capitalize the first letter of each word when writing a section title.
Custom IDs must start with a letter and contain only lowercase letters and Arabic numerals and “-”.
Put the custom section ID ([[id]]) above the section title:
[[section-id]]
== Section Title
Refer to <<section-id,Section Title>>.Do not use autogenerated section IDs if there are many duplicate titles.
HTML Entities
Asciidoctor PDF doesn’t support all named HTML entities (e.g. ×), so you have to use entity numbers (e.g. ×) here.
Tables
Use the following format to write a table (capitalize only the first letter of the table title):
[[table-id]]
.Table title
[%header,cols="3*1"]
|===
|Column 1
|Column 2
|Column 3
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|Cell in column 1, row 3
|Cell in column 2, row 3
|Cell in column 3, row 3
|===| Column 1 | Column 2 | Column 3 |
|---|---|---|
Cell in column 1, row 2 |
Cell in column 2, row 2 |
Cell in column 3, row 2 |
Cell in column 1, row 3 |
Cell in column 2, row 3 |
Cell in column 3, row 3 |
Table of Contents
We recommend that you use tools rather than maintaining the “List of Tables” and the “List of Figures” manually.
See Golang AsciiDoc Tools for tools that may be useful.
