diff --git a/modules/doc/doc/1-module-documentation.md b/modules/doc/doc/1-module-documentation.md new file mode 100644 index 000000000..968dd32d7 --- /dev/null +++ b/modules/doc/doc/1-module-documentation.md @@ -0,0 +1,59 @@ +# Writing Module Documentation + +![Markdown](/img/doc/doc/markdown.png) + +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. + +## 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 + +## 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. Natural Order 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 + +## 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. + +## Linking Between Headings + +For linking between headings, place an anchor where you want to link to, e.g.: + + # 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). + +## 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.: + + ![Alt text](http://path/to/img.png "Optional Title") + +URLs to images inside your Markdown documentation files must be specified without the base URL, e.g.: + + ![Example](/img/example-module/doc/example.png) diff --git a/modules/doc/public/img/doc/markdown.png b/modules/doc/public/img/doc/markdown.png new file mode 100644 index 000000000..93e729bc7 Binary files /dev/null and b/modules/doc/public/img/doc/markdown.png differ