Documentation

qmdoc 0.1.0

Welcome to little lamb

qmdoc(1)

qmdoc manual

qmdoc(1)

NAME

qmdoc - Quick markdown documentation generator

SYNOPSIS

qmdoc [OPTION..] FILE..

DESCRIPTION

qmdoc is a small tool to generate static HTML documentation from MarkDown files. The generated documentation is only made of HTML and CSS, without any JavaScript.

OPTIONS

-a, --author AUTHOR

Will use AUTHOR as author name for the generated documentation. It will be featured inside a meta tag as well as in the footer of generated pages.

-b, --buttons

Will add Previous and Next buttons on the bottom of generated pages.

-C, --no-css

Do not include qmdoc's own CSS. Any custom CSS specified via --css will still be processed.

-c FILE, --css FILE

Use FILE as additional custom CSS. By default qmdoc comes with its own CSS and generated pages are thus fully styled.

You can however add styling of your own, in which case references to the specified FILE will be added to generated pages, alongside qmdoc's own CSS.

Limitations

Note that only one CSS file can be added. If used multiple times, only the last value of FILE will be used.

-d DIR, --destdir DIR

Write generated pages (and CSS files) into DIR instead of current directory.

-F FILE, --footer FILE

Insert FILE as footer on every generated page. FILE is expected to contain valid HTML code, and will be inserted as-is on top of the page's content.

Hint

You can have the content of FILE inserted right at the opening of the body tag by using --wide-include

-H FILE, --header FILE

Insert FILE as header on every generated page. FILE is expected to contain valid HTML code, and will be inserted as-is on bottom of the page's content.

Hint

You can have the content of FILE inserted right before the closing of the body tag by using --wide-include

-h, --help

Show the help screen and exit.

-I, --inline-css

Use inline CSS instead of external files. By default qmdoc will copy its own CSS as qmdoc.css alongside the generated pages, and reference it via a <link> tag.

When this option is used, the actual CSS is placed on every page inside a <style> block, obviously leading to larger files. It might be interesting when generating a single page, to obtain a self-contained HTML file without any other dependencies.

Information

If you add custom CSS using --css it will also be inlined, in a separate <style> block.

-i, --index

Force index mode, that is creation of an index page containing the overall table of contents for the entire generated documentation.

See INDEX MODE for more information.

-l LNG, --lang LNG

Set LNG as language attribute, used as value for the lang attribute of the <html> tag of generated pages.

-M URL, --man-url URL

Use URL as prefix for external man-page links. That is, when a so-called man-page links can't be resolved internally, use URL as prefix for the link.

For example, with URL set to http://www.example.com/man/ the following would result in a link to http://www.example.com/man/foobar.1.html :

mdSee [foobar](1) for more.

Information

The given URL is used as-is as prefix, to which is added the text from the link, followed by a dot, the section number, and the .html extension.

It is up to you to ensure the resulting URL will be valid, e.g. make sure it ends with a slash (/), an equal sign (e.g. ...&page=) or whatever is needed.

See MAN-PAGE LINKS for more.

-o, --overwrite

Overwrite destination files without confirmation if they already exist.

-s TEXT, --subtitle TEXT

Set TEXT as general subtitle. It will be featured right below the general title (see --title) on the left-side of each pages (above its TOC).

-T, --no-toc

Don't write a table of contents on each page. The entire left column of generated pages will not be featured (including --title and --subtitle).

This implies --no-index

-t TITLE, --title TITLE

Set TITLE as general title. It will be featured on top of the TOC of every generated pages.

-W, --wide-include

When using --header andor --footer the content of the specified file is included within the page's <section>, thus appearing on topbottom of the page's content (i.e. on the right side, "after"/next to the Table of Contents).

When using --wide-include it will be inserted right after the opening of the <body> for the header, right before its closing for the footer.

-X, --no-index

Disable index mode. See INDEX MODE for more information.

PAGE HEADER

For every file to process, qmdoc will check for a page header in the first lines.

From the begining of a file, every line starting with a percent sign and a space will be considered an header line. The first line not to start with the percent sign & space will mark the begining of the content to convert.

Up to four lines are recognized by qmdoc, all of them are optional. You can effectively include as many header line as you need : the first four will be processed as described below, while others will simply be ignored.

The first line is used to set the page's title. Said title will be used for the <title> tag of the page, as well as in the Table of Contents.

If not specified, the file name (including the .html extension) is used instead.

Man page mode

The three other lines are intended for use in the writing of man pages. They consist of the following :

the name field
the version field
the date field

The first field (second line) is "required" in the sense that you need to specify one in order to enable the man page mode, else all are ignored.

Other fields are optional; meaning that if you only wanted to specify a name and date field, without version field, you would simply leave the version field empty (i.e. leaving only the header mark), e.g:

% Page Title
% Some Name
% 
% Date goes here

Once a name is present, and man page mode enabled, the other fields have default values to be used when left unspecified :

Version field defaults to name field
Date field defaults to page title

Results

Man page mode results in an additional line added on top and bottom of the page. Each consists of three sections : left, middle and right. They are filled as follows :

NAME                                 TITLE                                 NAME


VERSION                               DATE                                 NAME

Lastly, the page title used in the <title> tag will consist of the name field and the title field (given on first header line), concatenated with a dash. E.g: NAME - TITLE

Note that on the TOC only the name field will be used.

Thusly, one can get a typical man-page look, for example when first written this page used the following header :

md% qmdoc manual
% qmdoc(1)
% qmdoc 0.1.0
% 2023-01

INDEX MODE

For every generated page, qmdoc will generate the page's TOC (table of contents) using the different titles it contains. The resulting TOC will be featured on the left side, alongside links to every other generated pages - in the order they were processed.

In addition, the so-called index mode will have qmdoc generate a global TOC (comprised of the TOCs of all pages) and generate an index.html file featuring said global TOC.

This index.html will also be linked from every page, as if it was the first generated page, titled "Table of Contents".

You can disable index mode by specifying --no-index. Each page will still feature its own TOC with links to other generated pages.

Customize the global TOC

By default, index mode is enabled if no index.md was given - and thus no index.html would have been generated - or if one was given as first file to be processed.

In the later case the file will actually be generated last, and an special tag <TOC> can be used, to be replaced by the global TOC. The rest of the page is of course processed as usual.

Hint

You can also force index mode via --index so that if an index.md was specified, regardless of its position, it will be processed last and support the <TOC> tag.

Of course if none was given, qmdoc's internal one will be used as usual.

MARKDOWN SYNTAX

qmdoc is using md4c as parser, and as such is mostly compliant with CommonMark specification version 0.30.

Mostly, because a set of specific extensions has been added to help with our intended use of creating/writing documentation.

Emphasis & the likes

The way to set emphasis and other style has been adjusted :

Text in between stars (e.g. *foobar*) will be bold
Text in between slashes (e.g. /foobar/) will be italic
Text in between underscores (e.g. _foobar_) will be underlined
Text in between tildes (e.g. ~foobar~) will be ~~striked~~
Text in between equal signs (e.g. =foobar=) will be highlighted

Code blocks

Code blocks are supported, either by indentation or as fenced blocks, i.e. enclosed in lines beginning with 3 tildes or more.

Fenced code blocks can have a text featured on the opening line, after the tildes (referred to as info string). The first word (space-separated) is used as indication for the "language" of the block.

This is only used by qmdoc to be featured in a little blue box on the top-left corner of the block, as indication to the reader.

Attributes

Additionaly, custom parameters can be specified, in the key[=value] form :

hl : Enable highlighting effects. Then, any text in between <hl> and </hl> tags will be highlighted, in between <em> and </em> will be in italic, and in between <b> and </b> will be in bold.
from=N : Enable line numbering, starting from N

Line numbering is also automatically enabled for any fenced code blocks unless its language is set to pre

Hint

It is of course possible to have line numbering for pre blocks, either by using another term as language, e.g. raw, or by adding from=1

You can also use from=0 to disable the line numbers, all the while keeping the alternate line background as well as language name being shown.

INDENTATION

qmdoc also supports indented text : lines starting with a colon (:) will be intended. It is possible to use more than one colon to increase the indentation.

This was for example used in the OPTIONS section, to indent option names, and indent more the descriptions.

BOXES

Special boxes are supported, by give out informations, hints or warnings. This is done by creating a block of text, made up of lines all beginning with an exclamation point.

The first line is a special line, it must contain the type of box to create (default is WARNING) followed by a colon, and optionally a title.

Supported types are :

WARNING : For warnings, default title: "Warning"
INFO : For informations, default title: "Information"
HINT ! For hints, default title: "Hint"
NOTE : For notes, default title: "Note"

If no supported type is found, the entire line is used as title for a WARNING box.

Example

To get the following box :

Test

This is some warning.

You would use this mardown source :

1
2

md! Test
! This is some =warning=.

You can of course use regular MarkDown syntax within such boxes, including code blocks.

MAN-PAGE LINKS

qmdoc will recognize special link, so-called man-page links, as links whose target is nothing but a single digit from 1 to 8 (included) - and process them differently.

For example, the following would be recognized as a man-page link:

mdSee [foobar](1) for more.

Such links are processed in a special manner to allow ease of man-page creations :

Firstly, a file name is constructed as target for the link. This file name will be the text of the link (between brackets), then a dot, the section number, and the .html extension. E.g: foobar.1.html
Then, qmdoc checks to see if such a page has been or will be generated. If so, an "internal" link to said page is created.
If no such page has been nor will be generated, it checks if a prefix URL was specified via the --man-url option. If so, a link constructed by using the given prefix followed by the target file name is created.
Else, no link is created, and qmdoc simply outputs what would otherwise be the text of the link : the text of the link, followed by the section number in between parenthesis; E.g: foobar(1)

Note that the text of the link will be in bold, even when no link is created.

INTRA LINKS

In addition to regular and man-page links, qmdoc also recognize another kind of links, sometimes known as "wiki-links". However, they have nothing to do with wiki here, only their syntax is similar :

[[target]]
[[target|some text]]

The later form allows you to use the specified some text as text for the link. As for the link, it will point to :

If the target is the file name of a page, minus the extension (e.g. "foobar" for a file named foobar.md) then a link to said page (e.g. foobar.html) is generated,
Else, it is assumed to be a title from the current page, and a link to its anchor is generated.

The later is what allows to easily link to a section within the page, e.g. to link to this very section you could simply use [[INTRA LINKS]].