qmdoc: Quick MarkDown Documentation Generator

qmdoc is a simple, lightweight, fast tool that will convert MarkDown files into HTML files, with an aim at documentation.

The generated files are pure HTML/CSS, without any JavaScript. Thus they are static files that can easily be made available and shared.

Relying on the md4c parser, it is mostly CommonMark compliant - mostly, because it comes with a few (unique) extensions to easy things up.

For example, 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

As expected qmdoc supports code blocks, quote blocks, lists, etc as well as indentation blocks (usefull to write man page-like document) and so-called boxes to present warnings, information, hints or simply notes.

It also supports "man-page links" - that is links of the form [foobar](n) where n is a digit from 0 to 9. Such links will be automatically made to target a matching page (e.g. foobar.n.html) being generated if any, else can be linked using a specified prefix URL, or simply not made into link. Either way, the text will be in the form foobar(n) as you'd expect.

qmdoc will also generate a Table of Contents for each generated pages, as well as a global TOC encompassing all generated pages, thusly creating an overall (customizable) index.html providing the user with the full documentation's TOC.

Latest release: 0.2.0 (2023-07-24)

• Allow section 0

• Add option --sharedir

• Add symlinks support, directories & (sorting) groups

  • Symlinks that don't include a slash in their destination are processed as "links", i.e. we don't generate a page for them but any link to them will be set to the page they're pointing to.
  • Directories can now be specified as argument, in which case they'll be scanned and processed recursively.
  • Adding notions of groups & sorting groups. Files to be converted are always in both. Groups are used on page's TOC, only links to pages in the same group are featured. Sorting groups are used to sort pages before processing them (and thus, in TOC). Can have more than one sorting group per group. A new group implies a new sorting group. One can use "+g" and "+sg" on command line to start a new group or sorting group, respectively. Additionally, whenever a directory is read a new (sorting) group is started. This is enforced because the first group is not sorted, thusly allowing user-defined order on command line.
  • Option --sort-group can be "title" (default) or "file" to use page's title or file name, optionally prefixed with (or just) "d:" for descending order.
  • Options --dir & --subdir can be "group" or "sort" to define whether or new group (default) or sorting group, respectively, is started when processing a directory (from command line), or sub-directory (via recursion).

• Add options -q/--quiet & --verbose

• index: Add for index of all pages

• TOC: Add special sorting for man pages

• Update to latest md4c

• Update limb dependency to 0.1.0

• Some fixes & tweaks (refer to git log for more)

Components

Those are internal components, the required source code is included in the tarball and they lead to no runtime dependency.

• comain version 0.0.4
• md4c version 0.4.8.lila.2

Dependencies

Those are dependencies on librairies that will need to be present at build time. A runtime dependency will be set, unless static linking was used.

• limb version 0.1.0

Free Software

Released under GPL-2.0, see COPYING for more. Copyright (C) 2023 Olivier Brunel

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2, as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.