Last modified: 2021-08-22 14:22

HTML Integration

mdc produces HTML from your markdown source code. There isn't much to say more: the conversion rules are (ok, no to precisely) laid down in the (various) markdown description(s). The previous page showed the supported markup and the mdc extension. But there are some more things beyond formatting text.

mdc supports reading so-called meta information or file configuration from the file. This is not some more markup but really additional information. It is about adding

  1. HTML styles
  2. Javascript files
  3. Information of other files related to this

Meta information format

Meta information is stored line-wise inside the markdown file. It consumes always a whole line of text and all data on the line is (in some way) relevant. Meta information lines may appear everywhere in the markdown file and have the format :fc: key: value. An example is

:fc: style: BODY { background: #333333; color: #FFFFFF; }

:fc: is the "magic token" that marks the line as meta information, style is the key's name and BODY { background: #333333; color: #FFFFFF; } its value. As you can guess, this header adds a CSS definition to the HTML file.

Unlike markdown, the :fc: token can't be quoted with a backslash \. If you want to write :fc: at the beginning of the line you have to indent it with one blank. Usually this is not a problem; only if the token should appear inside a code block as in the example above. But to the way mdc's parser works, the code block takes precedence and the :fc: is not recognized as meta information header.

Adding HTML style definitions

mdc reads plain-text files and creates HTML that should look good not only in simple console-based but also in modern graphical browsers. For the latter it supports stylesheets. You can add style information in single meta-information lines

:fc: name: value

Examples would be

:fc: style: BODY { font-size: 12pt; }
:fc: style: DIV.notive { margin: 1em; border: 1px solid blue; }

or put all the definitions into an additional file and load that

:fc: css: style.css

Adding Javascript files

You can add one or more Javascript files to your HTML file. Simply reference the script's location in a script header:

:fc: script: keyboard.js

loads the keyboard.js script along with your HTML file.

Keyboard navigation

mdc comes with the Javascript file keyboard.js to implement a simple - you guess is - keyboard navigation. These are the keys and what they do.

Key Goes to
Ctrl-X, C contents
Ctrl-X, F first page
Ctrl-X, H home page
Ctrl-X, I index page
Ctrl-X, L last page
Ctrl-X, N next page
Ctrl-X, P previous page
Ctrl-X, U up
+ next link
- previous link
A-Z next link starting with that letter

Of course the related links must be defined but this is explained on the next page.

Working with multiple files

Now consider you have some Markdown files and they share some configuration like, e.g. the style definitions. But instead of putting the definitions in every of your files you can put all the common options into one of your markdown files and refer it with a relfile: header. I prefer to put common options into the index file, so it would be

:fc: relfile: mdc-index.md

Having that in the files make mdc read the meta information from that file.

With a central location for file options you can give your file a reading order:

:fc: file: mdc-index.md

:fc: file: mdc-supported-markup.md

and so on. mdc takes the file list and creates a prev/next navigator from it.

You can add more navigational pages. mdc understands

and insert appropriate navigational links to the HTML files.

Notice:

mdc produces static HTML files. Whenever you change an option in the relfile you must recompile the markup file. You can do this with

mdc -m compile *.md

Otherwise the options will not be updated in the HTML files.