== MMU2HTML 0.5

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.

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

MMU2HTML (C) 2013-2019 Ralf Hoffmann

=== Configuration

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:

----
input = ...
----

sets the directory of all input files

----
files = ...
----

sets the directory of additional files which are parsed

----
output = ...
----

sets the directory where all target files are created

----
copy = [ "style.css", "foo/bar" ]
----

list of files and directories to copy into the output directory

----
css = style.css
----

name of the css file to use

----
template = website.tpl
----

name of the template file

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

----
cache = <directory>
----

Optional directory to cache intermediate files to avoid recreation
(like for thumbnails of images).

----
sign = [0|1]
----

Enable signing generated files with gpg.

----
sign_key = <key name or ID>
----

Set specific key to use for signing, unset to use gpg's default.

----
char_replace = { "<character>": "<replacement>", ... }
----

Replace listed characters with replacement text. Can be used to
replace special characters like umlauts.

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

=== Usage

Just execute

----
mmu2html.py -c <your ini file>
----

Additional options are:

 - -d: if enabled, stale output file will be deleted so you get a clean
   output directory with only the files generated or copied by mmu2html.
 - -v: if set, mmu2html will be more verbose
 - -V: show the program version
 - --validate: if set, the generated HTML files are validated with the
   tool "tidy"

=== 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:

{title} will be the tile of the file
{css_name} is the location of the css file
{menu_content} is the complete menu content
{menu_toplevel} is only the toplevel menu
{menu_submenu} is the submenu of the current toplevel entry
{groupmenu_content} is the group menu
{file_content} is the actual parsed file conent
{sig_link} a link to the signature of the generated HTML file (if signing has been enabled)

=== Content files

The content files can start with option lines of format

<keyword>:<value>

Available options are:

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

 - http, mailto, ftp
   * B can be regular text or start with img:
 - file
   * B can be regular text or start with img:
   * if B is an img: tag but the file is not existing,
     it will be created from the file named by A.
     ImageMagick's convert tool is used with the width
     given in the attributes C (or by using a default width)
 - img
   insert the image into the html page
   B is not used here
 - res
   link to resource (file, directory) located in same web space, but not
   handled by mmu2html
   * B can be regular text or start with img:
 - taglist
   list all available tags used anywhere in any file
 - taglist:...
   list all pages with given tag
 - absolute or relative path to cms page
   * B can be regular text or start with img:
   A may end with an anchor name (site#anchor)
 - starting with # and no B
   An anchor will be inserted.

C can be additional attributes:

 - for img:
   * width=...
   * align=right
 - for links:
   * name=...

===== text formatting

*bold* for bold text

_underline_ for underlined text

==== Special single line markups

Some markups can only be used as a single entry in a line.

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

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

 - toplevelmenu
 - submenu
 - menunona
 - groupmenu
 - taglist
 - tag-ul
 - file-tag
 - tag-count
 - blog-overview
 - blog-title
 - blog-content
 - blog-list
 - blog-nav
 - blog-newer
 - blog-older
 - toc
 - toc_entry
 - webpage_sig
