mirror of
https://github.com/Icinga/icingaweb2.git
synced 2025-11-07 14:40:07 +01:00
60 lines
2.3 KiB
Markdown
60 lines
2.3 KiB
Markdown
# <a id="module-documentation"></a> Writing Module Documentation
|
|
|
|
|
|
|
|
Icinga Web 2 is capable of viewing your module's documentation, if the documentation is written in
|
|
[Markdown](http://en.wikipedia.org/wiki/Markdown). Please refer to
|
|
[Markdown Syntax Documentation](http://daringfireball.net/projects/markdown/syntax) for Markdown's formatting syntax.
|
|
|
|
## <a id="location"></a> Where to Put Module Documentation?
|
|
|
|
By default, your module's Markdown documentation files must be placed in the `doc` directory beneath your module's root
|
|
directory, e.g.:
|
|
|
|
example-module/doc
|
|
|
|
## <a id="chapters"></a> Chapters
|
|
|
|
Each Markdown documentation file represents a chapter of your module's documentation. The first found heading inside
|
|
each file is the chapter's title. The order of chapters is based on the case insensitive "Natural Order" of your files'
|
|
names. <dfn>Natural Order</dfn> means that the file names are ordered in the way which seems natural to humans.
|
|
It is best practice to prefix Markdown documentation file names with numbers to ensure that they appear in the correct
|
|
order, e.g.:
|
|
|
|
1-about.md
|
|
2-installation.md
|
|
3-configuration.md
|
|
|
|
## <a id="toc"></a> Table Of Contents
|
|
|
|
The table of contents for your module's documentation is auto-generated based on all found headings inside each
|
|
Markdown documentation file.
|
|
|
|
## <a id="linking"></a> Linking Between Headings
|
|
|
|
For linking between headings, place an anchor where you want to link to, e.g.:
|
|
|
|
# <a id="heading"></a> Heading
|
|
|
|
Now you can reference the anchor either in the same or **in another** Markdown documentation file, e.g.:
|
|
|
|
This is a link to [Heading](#heading).
|
|
|
|
## <a id="images"></a> Including Images
|
|
|
|
Images must placed in the `img` directory beneath your module's `public` directory, e.g.:
|
|
|
|
example-module/public/img/doc
|
|
|
|
Module images can be accessed using the following URL:
|
|
|
|
{baseURL}/img/{moduleName}/{file} e.g. icingaweb/img/example-module/doc/example.png
|
|
|
|
Markdown's image syntax is very similar to Markdown's link syntax, but prefixed with an exclamation mark, e.g.:
|
|
|
|
|
|
|
|
URLs to images inside your Markdown documentation files must be specified without the base URL, e.g.:
|
|
|
|
|