NAME

qmdoc - Quick markdown documentation generator

SYNOPSIS

qmdoc [OPTION..] FILE|DIR..

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

1

mdSee [foobar](1) for more.

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 :

2. the name field
3. the version field
4. 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 :

1
2
3
4

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 same group.

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, as well as an alphabetical index of all pages & links.

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. You can also disable such TOCs using the --no-toc option.

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 some special tags can be used :

• Special tag <TOC> can be used, to be replaced with the global TOC.
• Special tag <INDEX> can be used, to be replaced with an alphabetical index of all pages & links processed.

GROUPS AND SORTING GROUPS

In addition to files, it is possible to specify directories as arguments for qmdoc to process. In such a case, it will read the directory's content and process every file it contains whose name ends in .md

Directories are scanned recursively, meaning that any subdirectory will also be scanned and its files be processed.

Because when reading a directory the order in which entries (files) are read is undetermined (aka random), it is necessary to sort them. To do so, qmdoc uses the notion of "groups".

Groups

Files can be grouped together, and sorting files will be done group by group. Every time a directory was specified on command line, a new group is created in which all the directory's files will be put.

Similarly, when a subdirectory in encountered a new group is created as well.

By default, files will be sorted by their page's title in ascending order This can be changed using the --sort-group option. Possible values are title (default) and file, to use file names. One can also prefix the value with d: to have them sorted in descending order.

Sorting groups

Two kinds of groups are actually supported : regular groups, and sorting groups. The difference between the two only comes with regard to each page's table of content (TOC), i.e. regular groups are an extension over sorting groups.

By default, all pages are featured on the TOC found on every generated page. However, when groups are involved, only pages from the same group will be featured.

Manually grouping pages

No group exists by default, allowing one to define the order in which pages will be processed/generated via the order they're given on command-line.

However, it is possible to group files without using directories, by using special arguments :

• Using +sg as argument will start a new sorting group;
• Using +g as argument will start a new (regular) group.

That way, one can easily specify a bunch of files to processed, and have them be sorted.

You can use as many such arguments as needed, in whatever order needed. Note that, however, once a (sorting) group has been added (manually or by specifying a directory), it is not possible to specify a manual order of processing, since every file from then on will be in a (sorting) group.

Consider the following example :

1

shqmdoc first.md +g *.md

The TOC on the page from first.md will not include links to any other files, similarly all other pages' TOC will not include links to the first.md page.

While the shell is likely to expand *.md in a sorted fashion, it should be worthy to note here that because files are in a group, they will be sorted by qmdoc and, by default, using their titles (not their file names).

Another example :

1

shqmdoc first.md +sg foo*.md bar*.md +sg *.md

All files whose name begin with either foo or bar will be sorted/listed together after first.md, all the other files will be sorted/listed on their own afterwards.

SYMLINKS

Symbolic links are handled in a special manner, in order to allow one page to have multiple names linking to it.

Restrictions

First off, such special handling only applies to symlinks that do not contain any slashes (/) in their content. In other words, they must point to a different file, or name, within the same directory.

In addition, this only applies to MAN-PAGE LINKS and INTRA-LINKS, not "regular" links. This is simply because in the later case you specify a target for the link, and that target is used as-is. It is up to you to ensure it will actually point to something that does exist.

Handling

When a symlink without slashes is found, instead of opening/processing the file pointed to, qmdoc will simply remember that any link (in any of the processed pages) to it shall be made to the pointed page instead.

As a result, no page is actually processed/generated from such symlinks, but any link to the symlink will be properly placed, pointing to the page it points to.

For this reason, one last limitation is in effect: If a symlink points to a non-existent page, it will have no effect.

Example

So, imagine you've written a small library and you want one single page documenting two functions, because things are simpler/easier that way. What you can do then, is have you page written under e.g. foobar.3.md and then have a symlink barfoo.3.md pointing to it.

As a result, qmdoc will only generate a single file - namely foobar.3.html - but if in any other pages you have a links such as [barfoo](3) then a link will be made, only pointing to foobar.3.html, as per the symlink.

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

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 :

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:

1

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]].