Hamill

This document describes in English the Hamill language. La documentation en français est disponible ici.

Hamill is a lightweight markup language like Markdown, Textile, AsciiDoc or reStructuredText, to write documentation in a text file with structure information (headings, divisions, paragraphs) and formatting (bold, italics…).

Its lightweight syntax makes it easier to read the text file directly than the corresponding HTML file. Hamill dœs, however, provide a tool for transforming a Hamill file (extension .hml) into an HTML file (extension .html).

Its syntax is both easier and more complete than that of the original Markdown from 2004.

Hamill has been around since 2020, is currently at version 2 since 2022 and has two implementations that produce the same result:

The project's source code is available on GitHub.

You can try it directly online

The current version is 2.0.5. Hamill is released under the MIT license.

Damien Gouteux 2020-2024

This page has been translated from French to English with the help of DeepL Translator.

Contents

Use

Hamill comes in the form of two scripts: hamill and weyland (extension .mjs for the JavaScript version and .py for the Python version). Weyland handles the lexical and syntactic analysis of the various languages, while Hamill transforms the Hamill file (.hml extension) into a document made up of several nodes. This document is then translated into HTML. To do this, Hamill is used on the command line:

node.exe hamill.mjs
python.exe hamill.py

By default, it will display the help menu detailing the various commands available.

Running Hamill v2.0.5
---
> Use hamill.mjs --process (or -p) <input config filepath> to convert the HML file to HTML
  The file must be an object {} with a key named targets with an array value of pairs :
            ["inputFile", "outputDir"]
> Use hamill.mjs --tests (or -t) to launch all the tests (99).
> Use hamill.mjs --eval (or -e) to run a read-eval-print-loop from hml to html
> Use hamill.mjs --help (or -h) to display this message

The configuration file is a JSON file with an object as its root. This object must have a targets key which is a list of pairs, the first element indicating the target hamill file, the second element indicating the directory where to put the result of the transformation into HTML. The result will have the same filename as the target hamill file, except that its extension will be .html instead of .hml. If the first element is the string "comment", this pair will be ignored.

{
    "targets": [
        [
            "comment",
            "Root pages"
        ],
        [
            "./input/index.hml",
            "../"
        ]
    ]
}

Comments, HR and BR

Comments can be made by putting !rem or §§ at the beginning of the line, and the entire line is then a comment.

!rem This is a comment
§§ This is another comment

A line that is entirely a comment will be exported as HTML if the EXPORT_COMMENT variable is set to true.

A horizontal line can be made with a line consisting only of - of length greater than or equal to 3.

---

You can force a line break with ## surrounded by a space before and after it, and not at the beginning of the line (otherwise it's a title):

this is a line break ##.

this is a line break
.

Titles

A number of # is placed at the beginning of the line, corresponding to the level of the title you want.

### Level 3 title

Text formatting

Div, p and span

!css span.spoiler {background: black; user-select: none;}
!css span.spoiler:active {background: lightgrey; user-select: none;}
This is text with a hidden part: {{.spoiler Darth Vader is Luke's father}}. To avoid spoilers.

This is a text with a hidden part: Darth Vader is Luke's father. To avoid spoilers.

Details

<<This is a short note.

<<Short note → This is a short note.

<<Long note
* This is a long note
* With Hamill in it ##
<<end>>
Long note
  • This is a long note
  • With Hamill in it

Code

We use @@for inline code@@. Hamill has a syntax colorizer for Python and JSON, so we specify : @@python def function(par1, par2)@@.

For a block of code, there are two solutions:

You can start with a line containing only @@, followed by the language you want, and then continue with lines containing @@ at the beginning, up to a line containing only @@. For example:

@@python
@@# This is a comment
@@def function(par1, par2):
@@ return "This is a function"
@@

Gives :

# This is a comment
def function(par1, par2):
 return "This is a function"

You can also make a line with only @@@ followed by the language you want, then lines with nothing up to a line with only @@@. For example:

@@python
# This is a comment
def function(par1, par2):
return "This is a function"
@@@

Gives :

# This is a comment
def function(par1, par2):
    return "This is a function"

Lists

  1. + for a numbered list, item 1/2
  2. + item 2/2
  1. - for an inverted numbered list, item 1/2
  2. - item 2/2

Definition lists

Cuirassier
    heavily equipped mounted soldier
Cuirassier
heavily equipped mounted soldier

Tables

Thisis a table
My table is pretty

You can, of course, add text modifiers, links or an image to an array.

This is a table
It is a prettydifferent table.

You can also center a box by following the opening column with = and right-aligning with > :

Left and also very long Centered Right
Right Centered Left and also very long

You can also specify a colspan with #cVALUE# for example: #c3# and combine with centering =#c3# :

Column 1Column 2Column 3
Centered and colspan=3

LIMITATION: no lists in a table

Images

Constants

Constants can be defined by putting !const at the beginning of the line. Constants can be defined anywhere in the document, but only once.

Some constants are predefined but have no value, so they can be defined once again:

Some constants are predefined with a value, so cannot be redefined:

For the display of the day in the week, only English and French are managed according to the LANG constant.

Variables

Variables can be defined by putting !var at the beginning of the line. You can change the value of a variable by redefining it in the document as many times as you like.

If NEXT_TAB_CLASS and DEFAULT_TAB_CLASS are defined, the value of NEXT_TAB_CLASS will be used.

Including HTML files

You can include an HTML file with !include at the beginning of the line. The content of the file will be copied directly into the document.

Linking to a CSS or JavaScript file

We can link our document to a CSS or JavaScript file with the !require command at the beginning of the line.

The link to a required CSS (.css) file is automatically placed at the head of the HTML document.

The link to a required JavaScript file (.js or .mjs) is automatically placed at the top of the HTML document.

Special