Last modified: 2022-08-28 10:16

Text formatting is one thing, working with multiple files is another. mdc supports a common layout, navigation and Javascript (e.g. to have keyboard navigation) through configuration information inside the source files.

Meta Information

mdc produces HTML from your markdown source code. The conversion rules are (more or less precisely) laid down and the previous document shows what mdc supports and its extensions. When working with more that one file you may want to

Meta information format

mdc addresses these aspects with meta information. Meta (or file control) information is made up of lines starting with the unindented :fc: and is stored inside the source code. The format is :fc: key: value. Here is an example:

: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 already guess, this header adds a CSS

definition to the HTML file.

Unlike markup, 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 due to the way mdc's parser works, the code block takes precedence and the :fc: is not recognized as meta information header.

Overview

The following meta information are available. They are explained in the following sections.

Option Function
auto-update: f define if files are automatically recompiled when meta information has changed
css: fn insert a link to a style sheet.
file: fn add fn to the set of markdown files.
gopher-file: fn a gopher index is created together with the HTML indexfile and stored in fn.
indexfile: fn define the HTML index file.
rel-name: fn assign a navigation function to fn. Possible options for name are home, contents, index, privacy, and up.
relfile: fn read meta information from fn.
script: fn add a link to a Javascript file.
style: css define an HTML style.

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.notice { margin: 1em; border: 1px solid blue; }

mdc does not support breaking up long lines into multiple input lines. All meta information must fit on one single line.

Alternatively, you can put all style definitions into a single file and link to that using the css option:

:fc: css: styles.css

The css option may be used multiple times and stylesheets are added in the order as the appear.

Adding Javascript files

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

:fc: script: keyboard.js

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

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 mentioned above must be defined, see the navigation section below.

Centralizing meta information

Now consider you have several Markdown files and they share some configuration like the style definitions. Instead of putting the definitions in every of your files, you can put all the common options into one of your markdown files:

:fc: file: index.md
:fc: file: supported-markup.md
:fc: file: meta-information.md
:fc: css: style.css
:fc: script: keyboard.js

That information may appear anywhere in the file, e.g. in a single block at the end of the file or in pieces.

This meta information is then referenced from other files, using the relfile option:

:fc: relfile: index.md

reads index.md to extract the meta information from it when the file is compiled to HTML. Notice that the markup file may have its own meta options and depending on the option they add up (e.g., style or script) or the latter overwrites the first (e.g. rel-home). Furthermore, only one relfile option is supported.

Navigation

As soon as there is at least one rel- or file option, the HTML file gets a simple navigator at its top.

The navigator consists of two parts. First there will be links to related files, which are configured with the rel- options

  • rel-home
  • rel-index
  • rel-contents
  • rel-privacy (links to the file showing the site's privacy notice.)
  • rel-up

These must have the filename (or URL) as parameter, e.g.

:fc: rel-index: index.md

This part if followed by the prev-next navigator, which is constructed from the order of the file options.

Automatic retranslation

mdc creates static HTML files. This has two effects:

  • Files display correctly without any runtime computation.
  • Files needs to be recompiled when e.g. a new file is added to an existing set.

The configuration option auto-update

:fc: auto-update: yes

controls if recompilation of all files should be done automatically when a file's meta information has changed.

If set to yes, mdc compares a source file's meta information against what is stored in the existing HTML file (the HTML files contain a copy of the markup) when translating a file. If both versions differ then all listed Markdown files (rel- and file options) are translated too. Due to the way this feature works it is mostly only useful then compiling a set's relfile because this contains the complete list of files and options. If something changes there (e.g. a shared style definition changes, a file is added), all other files need to be updated too and this is what is configured with auto-update.

Automatic contents listing

mdc can create a simple index file of all Markdown and referenced files found in a set of source files. This is controlled with two options:

:fc: indexfile: contents.md
:fc: rel-contents: contents.md

The indexfile: option defines where the list is stored: When creating the index with mdc -m index relfile, mdc creates (and overwrites) the corresponding HTML file. If the markup file given as parameter to the indexfile option exists (the HTML file should not be used with indexfile) the list of files is appended to it.

The second option in the example above :fc: rel-contents: contents.md is not related to the index creating but adds that file to the HTML navigator. Index creation works without that option.

The file list is created from four parts:

  1. All rel- files up to the first file: entry.
  2. All file: files.
  3. All files linked from another file.
  4. All other rel- files.

and mdc uses the following rules to create the list:

  • mdc creates the part 3 list of files from references found in the files from parts 1, 2 and 4.

  • Files outside the local directory are listed if configured or linked but they are not scanned for further links.

  • mdc uses the file's title as link text. For markup files this is the first #-style heading and else (for non Markdown files) the file's title found in the first reference ((...)[...] markup) to it.

  • If a Markdown file has a text paragraph before the first header element this test is displayed as description.

Recommendations

Here are some recommendations for working with meta information.

  1. Add all your meta information to one markdown file only. Use your directory's "home page" (e.g. index.md) for that. Then add :fc: relfile: index.md to all other files belonging to the same file group.

  2. Enumerate your files in the relfile with :fc: file: .... Use only files with .md extension when listing files there or referencing them from Markdown. mdc translates the names automatically to .html.

  3. If your file set has a special home page (or similar), configure that using :fc: rel-home: ... but don't put it into your :fc: file: enumeration too.

  4. Add :fc: auto-update: yes to make mdc recompile all files when the meta information has changed.

  5. If you want an automatic list of files, choose a name, configure it and make sure that the page shows up in your page navigator.