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.

Features:

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

mmu2thml (C) 2013-2016 Ralf Hoffmann.

Download

The current release is mmu2html 0.4 (34 kB) (signature) from 2016-07-16.

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.

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]

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.

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]