mmu2html

mmu2html

Information

mmu2html is a tool to convert text files with mixed markup and html code into html files. It can be used for static website generation (it is used for this very web site). It has been designed with asciidoc in mind, but with additional support for menu creation, file linking, and with full control about what gets created. Also, it does not require javascript.

Features:

mmu2html is free software released under the GNU General Public License V3 or later. For details read COPYING.

mmu2thml (C) 2013-2020 Ralf Hoffmann.

Download

The current release is mmu2html 0.6 (42 kB) (signature) from 2020-11-26.

Changes

Requirements

Usage

mmu2html comes with a simple example in the "example" directory which is a good starting point for creating own web pages.

mmu2html uses an ini file to configure its behavior. There is an example file "mmu2html.ini" to start with. Here are the options to set: 
  1. input = ...
    sets the directory of all input files. 
  2. files = ...
    sets the directory of additional files which are parsed. 
  3. output = ...
    sets the directory where all target files are created. 
  4. copy = [ "style.css", "foo/bar" ]
    list of files and directories to copy into the output directory. 
  5. css = style.css
    name of the css file to use. 
  6. template = website.tpl
    name of the template file. 
  7. separate_submenu = 1
    if set, include the toplevel menu entry again in the submenu and the toplevel entry will always be marked as it would be selected directly. 
  8. cache = <directory>
    Optional directory to cache intermediate files to avoid recreation (like for thumbnails of images). 
  9. sign = [0|1]
    Enable signing generated files with gpg. 
  10. sign_key = <key name or ID>
    Set specific key to use for signing, unset to use gpg's default. 
  11. char_replace = { "<character>": "<replacement>", ... }
    Replace listed characters with replacement text. Can be used to replace special characters like umlauts. 
  12. base_url = ...
    Some tags insert this base url when creating absolute links.

Operation

All files in the input directory ending with .txt will be parsed and the resulting html file will be put into the output directory.

The only exception is the file named "menu.txt" and the file named "group.txt". This former file is used for creating the menu, the latter for an optional group menu.

To create all web pages, just execute 
mmu2html.py -c <your ini file>
Additional options are:

Menu file

The menu file is just a list of menu items of the following format: 
[name_of_file_without_ending|item_text]

Example:
If you want to put a menu entry for a file foo/bar.txt, you can do it like this:

[foo/bar|Some text]
The hierarchical structure of the directories is taken into account for menu creation. This means that the first element of a (sub)directory is firstly mentioned, it will be used as a top level entry while all other elements will be sub-elements of the top level element.

Example:

[foo/bar|BAR]
[foo/foo|FOO]
will be presented like: 
* BAR
** FOO

Group file

The group file can be used to display a separate menu based on the group of each menu entry. Each group is described by a name and a prefix. All files with that prefix will belong to that group. Multiple prefixes can be used for the same group.

The format is as follows:

[prefix|link|text]
All document files with the same prefix belong to the same group. The link is used used in the group menu to lead to the entry page of the group. Keep "prefix" empty for the default group that will be used for any file not matching another group.

Example:
If you want to use a group "foo" for entries in directory /bar, you can do it like this:

[bar/|bar/index|Foo group]

A fourth paramter number can used to order the group in a custom way. Example:

[bar/|bar/index|Bar group|4]
[foo/|foo/index|Foo group|3]

In this example the "Foo group" is placed before the "Bar group".

Tags

Files can be tagged with one or mulitple tags to make it easier to find files of a given topic. Use the markup [tag:foo] described below to insert a tag "foo" (in this example).

A special template file "by-tags.txt" must be placed in the top-level which is used to generate per-tag overview pages which can be accessed by clicking on a tag link to see all other pages of the same tag.

You can use the markup [taglist] to get a list of all defined tags.

Blogging support

mmu2html also supports simple blog entries. Each file marked with blog-date: ... is considered a blog entry and listed in the blog overview (see below for details about blog markup).

Template file

The template file can contain any text, usually it is a valid html file with some placeholders for actual content.

The following keywords are available:

Content files

The content files can start with a line 
title:...
to set the title information. If this information is missing, the title of the parent page will be used instead. 
number_headings:yes
to number h1 to h6 headers. 
blog-date: YYYY-MM-DD-NUMBER
Mark file as a blog entry of given daten (used to sort by date).

Supported markup

enumerated lists
# level 1
## level 2
### level 3
or 
 # level 1
   # level 2
     # level 3
leading space is important for the latter format
bullet point list
- level 1
-- level 2
--- level 3
or 
 - level 1
   - level 2
     - level 3
leading space is important for the latter format
head lines
== h1
=== h2
==== h3
up to h6
raw include
[rawinclude:A]
A is the local file name to include, no replacement is done
links
Basic format: 
[A|B] or [A|B|C]
A can start with C can be additional attributes:
Special characters

If you need to use a character that has some special meaning for mmu2html, then you can put a backslash before the character to stop mmu2html to parse it.

text formatting

*bold* for bold text

_underline_ for underlined text

Table of content
use [toc] on a single line to get the table of content for each headline.

You can set a limit of depth by adding an attribute "limit=<number>":

[toc|limit=2]
Blog overview
Use 
[blog-overview]
to get the latest three blog entries inserted into the current document.

List of blog entries

Use 
[blog-list]
to get a list of all blog entries defined (by using the blog-date attribute) anywhere in the project tree.
Blog navigation
Use 
[blog-nav]
to get newer/older links to corresponding blog entry.
Git repo representation
Two tags can be used to generate a static view of a git repository: 
[git-repo-checkout:<git repo base dir>]
This tag adds the text that can be used to clone the repositoy. It uses the config variable base_url. 
[git-repo-commits:<git repo base dir>|branch=...|commits=...]
This tag adds a list of the last ten commits including the commit time, hash and subject. The first commit entry also contains a download link for an archive of that commit. The optional arguments 'branch' can be used to name a branch to use, and the 'commits' can be used to set the number of commits to show.
Comment
any line starting with <<< is considered a comment and will be ignored completely

CSS classes used

Here is a list of css classes defined in the generated html files which can be used to customize the layout of the content.
Visits: Last modification: 2020-11-26
(C) 2001-2024 Ralf Hoffmann sig