== MMU2HTML 0.3

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

=== 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". This file is used for
creating the menu.

=== Usage

Just execute

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

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

=== 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
{file_content} is the actual parsed file conent

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

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

===== Table of content

use

[toc]

on a single line to get the table of content for each headline.
