How mdsite Works

mdsite can be thought of as a recursive copy command (like cp -r) that does some processing of the file contents as they're copied from INPUTDIR to OUTPUTDIR. Most file types (.js, .css, .jpg, .png, etc.) are simply copied with no processing.

Files in INPUTDIR that have an .md or .html extension will be processed. If the file is markdown, it gets compiled to HTML. Then the HTML is inserted into a template, which by default just wraps the content in bare-bones HTML boilerplate. Here is the default template:

<!DOCTYPE html>
<html>
  <head>
    <title>{{title}}</title>
  </head>
  <body>
    {{content}}
    <nav>
      {{home}} | {{up}} | {{prev}} | {{next}}
    </nav>
  </body>
</html>

{{title}} and {{content}} are macros. They instruct mdsite to insert some data into the page.

  • {{content}} inserts the content of the source file.
  • {{title}} inserts the content of the first <h1> element on the page, or the filename if there is no <h1>.

Custom Templates

You can customize the HTML template for your pages by creating a template.html file in the directory where you run mdsite.

Macros

The available macros are:

  • {{content}} inserts the content of the source file.
  • {{title}} inserts the content of the first <h1> element on the page, or the filename if there is no <h1>.
  • {{toc}} inserts a table of contents for the current directory and subdirectories.
  • {{next}} creates a link to the next page. The order of pages is determined by the set of order.txt files (see below).
  • {{prev}} creates a link to the previous page. The order of pages is determined by the set of order.txt files (see below).
  • {{up}} creates a link that goes one level up in the hierarchy. If used on a "leaf" page, it goes to the sibling ./index.html file; if used on an index page, it goes to ../index.html.
  • {{home}} links to the root /index.html file.
  • {{breadcrumb}} links to ancestor index.html files.
  • {{inputpath}} outputs the source path of the current file.
  • {{macro ...args}} outputs {{macro}} notation with literal double curly braces. Useful if you're writing documentation for mdsite.

For more details, see the page on macros.

You can use most of these macros anywhere—in your template file, or in HTML or markdown content. The exception to this is {{content}}, which should only be used in the template file.

All of the generated links are relative, making it safe to deploy your site to a subdirectory of your domain.

Table of Contents, {{toc}} and order.txt

{{toc}} is a macro which inserts a table of contents formatted as a nested list. {{toc}} recursively lists the files and directories within the current file's parent directory.

By default, entries in the table of contents are ordered lexicographically by title. You can customize the ordering of the entries in a directory by creating an order.txt file in that directory. The order.txt file simply lists the entries (files or directories) in the order you want them displayed, one per line. E.g.

foo.md
bar.md
baz.md
quux
kludge

Any files you don't list in order.txt will be ordered by title, after the listed files.

Each order.txt file can only affect the order of its sibling files/directories; order.txt can't reach into subdirectories. Any lines in order.txt that contain a slash are ignored.

To populate your INPUTDIR with order.txt files, you can run mdsite order [-i INPUTDIR]. This does the following:

  • Creates an order.txt in each directory that lacks one.
  • Appends any missing files and folders to each order.txt, below an !unspecified line which causes them to be ignored when sorting files.

Running mdsite order won't mess with the filenames you've listed manually, and won't affect the overall order of the pages on your site.

Markdown rendering

mdsite uses Marked to convert Markdown to HTML. The following extensions are included:

Ben Christel made this with mdsite.