asciidoctor -d book -D docs *.adocThis document gives you the information you need to get started contributing to Kudu documentation. For code contribution guidelines, see Contributing to Kudu.
Kudu documentation is written in Asciidoc and compiled into HTML and output using the Asciidoctor toolchain. This provides several advantages. Among them:
Asciidoc is a superset of Markdown, so if you already know Markdown you can get started right away.
Github includes support for Asciidoc in its Atom editor, as well as real-time simplified HTML rendering.
Patch submissions are small and easy to review.
Within reason, try to adhere to these standards:
100 or fewer columns per line
2 spaces rather than tabs for indentation
No more than 4 nested levels in the documentation if possible: (Document → Chapter
→ Section → Subsection)
When possible, provide the language that a code listing is in, using the
[source,<language>] macro. for example, [source,sql]
In general, do not indent Asciidoc, as indentation is significant. Code listings are one exception.
To build the documentation locally, you need the Asciidoctor Ruby application. To build the
entire Kudu documentation set, change to the docs/ directory and run:
asciidoctor -d book -D docs *.adocThis builds the HTML output in a new docs/ directory within the current directory. Some content, such as the per-daemon configuration reference files, is not populated during a local build.
To view the HTML, open docs/index.html in your local browser.
You can also build only a single chapter. such as introduction.adoc, by passing its name instead.
Asciidoc supports a lot of syntax that we do not need to use. When possible, stick with the following, adapted from the HBase Reference Guide:
| Element Type | Desired Rendering | How to do it |
|---|---|---|
A paragraph |
a paragraph |
Table of Contents
Just type some text with a blank line at the top and bottom. |
Add line breaks within a paragraph without adding blank lines |
Manual line breaks |
Table of Contents
This will break + at the plus sign. Or prefix the whole paragraph with a line containing '[%hardbreaks]' |
Give a title to anything |
Colored italic bold differently-sized text |
Table of Contents
|
In-Line Code or commands |
monospace |
Table of Contents
`text` |
In-line literal content (things to be typed exactly as shown) |
bold mono |
Table of Contents
*`typethis`* |
In-line replaceable content (things to substitute with your own values) |
bold italic mono |
Table of Contents
*_typesomething_* |
Code blocks with highlighting |
monospace, highlighted, preserve space |
Table of Contents
[source,java]
----
myAwesomeCode() {
}
----
|
Code block included from a separate file |
included just as though it were part of the main file |
Table of Contents
[source,ruby] ---- include::path/to/app.rb[] ---- |
Include only part of a separate file |
Similar to Javadoc |
Table of Contents
|
File names, directory names, new terms |
italic |
Table of Contents
_hbase-default.xml_ |
External naked URLs |
A link with the URL as link text |
Table of Contents
http://www.google.com |
External URLs with text |
A link with arbitrary link text |
Table of Contents
link:http://www.google.com[Google] |
Create an internal anchor to cross-reference |
not rendered |
Table of Contents
[[anchor_name]] |
Cross-reference an existing anchor using its default title |
an internal hyperlink using the element title if available, otherwise using the anchor name |
Table of Contents
<<anchor_name>> |
Cross-reference an existing anchor using custom text |
an internal hyperlink using arbitrary text |
Table of Contents
<<anchor_name,Anchor Text>> |
A block image |
The image with alt text |
Table of Contents
image::sunset.jpg[Alt Text] (put the image in the src/main/site/resources/images directory) |
An inline image |
The image with alt text, as part of the text flow |
Table of Contents
image:sunset.jpg [Alt Text] (only one colon) |
Link to a remote image |
show an image hosted elsewhere |
Table of Contents
image::http://inkscape.org/doc/examples/tux.svg[Tux,250,350] (or |
Add dimensions or a URL to the image |
depends |
Table of Contents
inside the brackets after the alt text, specify width, height and/or link="http://my_link.com" |
A footnote |
subscript link which takes you to the footnote |
Table of Contents
Some text.footnote:[The footnote text.] |
A note or warning with no title |
The admonition image followed by the admonition |
Table of Contents
NOTE: My note here WARNING: My warning here |
A complex note |
The note has a title and/or multiple paragraphs and/or code blocks or lists, etc |
Table of Contents
.The Title [NOTE] ==== Here is the note text. Everything until the second set of four equals signs is part of the note. ---- some source code ---- ==== |
Bullet lists |
bullet lists |
|
Numbered lists |
numbered list |
|
Checklists |
Checked or unchecked boxes |
Table of Contents
Checked: - [*] Unchecked: - [ ] |
Multiple levels of lists |
bulleted or numbered or combo |
Table of Contents
. Numbered (1), at top level * Bullet (2), nested under 1 * Bullet (3), nested under 1 . Numbered (4), at top level * Bullet (5), nested under 4 ** Bullet (6), nested under 5 - [x] Checked (7), at top level |
Labelled lists / variablelists |
a list item title or summary followed by content |
Table of Contents
Title:: content Title:: content |
GUI menu cascades |
bold text with arrows to show levels |
Table of Contents
Use an ASCII arrow. *File -> Print* renders like File → Print |
Sidebars, quotes, or other blocks of text |
a block of text, formatted differently from the default |
Table of Contents
Delimited using different delimiters, see http://asciidoctor.org/docs/user-manual/#built-in-blocks-summary. Some of the examples above use delimiters like ...., ----,====. [example] ==== This is an example block. ==== [source] ---- This is a source block. ---- [note] ==== This is a note block. ==== [quote] ____ This is a quote block. ____ If you want to insert literal Asciidoc content that keeps being interpreted, when in doubt, use eight dots as the delimiter at the top and bottom. |
Nested Sections |
chapter, section, sub-section, etc |
Table of Contents
= Book (or chapter if the chapter can be built alone, see leveloffset below) == Chapter (or section if the chapter is standalone) === Section (or subsection, etc) ==== Subsection and so on up to 6 levels (think carefully about going deeper than 4 levels, maybe you can just titled paragraphs or lists instead). Note that you can include a book inside another book by adding the |
Include one file from another |
Content is included as though it were inline |
Table of Contents
include::[/path/to/file.adoc] For plenty of examples. see docs/docs.adoc. |
A table |
a table |
Table of Contents
See http://asciidoctor.org/docs/user-manual/#tables. Generally rows are separated by newlines and columns by pipes |
Comment out a single line |
A line is skipped during rendering |
Table of Contents
|
Comment out a block |
A section of the file is skipped during rendering |
Table of Contents
//// Nothing between the slashes will show up. //// |
Highlight text for review |
text shows up with yellow background |
Table of Contents
Test between #hash marks# is highlighted yellow. |