Last modified: 2022-05-08 12:25

mdc is a command line tool to translate Markdown source to HTML. This file explains how to edit and compile markup source.

Using mdc

Compiling markup files

How ever you edit your markup files, sooner or later you have to run mdc to compile them. mdc has some different operation modes which are controlled with the -m option, which takes one parameter to set the mode.

mdc -m compile src ...

compiles the source files from the command line into .html files. This is the default if the mode is not set. Notice that although the output files contain the markup source at the end of the file as an HTML comment, mdc does not accept .html files as source arguments.

The compile operation is the only that accepts multiple command line arguments. All others - they are listed in the table below - work only on a single file.

Mode Operation
edit loads the source code into an editor and compiles when the editor exits.
html prints only the HTML text excluding the source.
index creates the configured indexfile from compiled HTML if first argument is an .html file; else files are recompiled from .md, which is slower but better.
meta prints the file's meta information.
reindex like index but recompiles always all source files.
source prints the source code only.
store reads markup from stdin and writes it to the given file.

Editing files

vi

vim can automatically reformat text to make it fit on lines. This works if you have set the line width first:

set tw=72

(tw is an alias for textwidth). For manual reformatting you must select the lines (SHIFT+V) and give the command gw. You can set the option

set formatoptions+=a

and vim breaks the lines automatically as you type the text. To activate these settings automatically put

setlocal textwidth=72
setlocal formatoptions+=a

into your ~/.vim/ftplugin/markdown.vim.

lynx

lynx is a well-known HTTP/HTML-browser for the UNIX console. Calling an editor to edit local files is supported: simply press E inside lynx. Of course, the editor needs to be configured. For mdc-generated HTML files you would set the options -editor='mdc -m edit'. The complete command line would then be something like lynx --editor='mdc -m edit' index.html. This displays the html file.

When you invoke the editor, mdc

When editing markup from within an HTML file mdc creates a ~ backup file of it before the new version is ceated.

A simple wrapper shell script would be

#!/bin/sh
#
# mde - Run lynx to edit .md files from HTML.
#


if [ -f ~/.config/lynx/markdown.lss ]; then
    OPT="$OPT -lss=~/.config/lynx/markdown.lss"
fi

exec lynx -scrollbar -use_mouse \
	$OPT \
	-editor='mdc -m edit' "$@"

that sets the editor plus other preferred options.

w3m

w3m is another console browser and it allows to editing local files too. For integration with mdc you would put

editor mdc -m edit %s

into ~/.w3m/config or set that with the -o option on the command line. Think about a wrapper script like the one above. Furthermore, in w3m you must use SHIFT+E to edit the file.