input files

whenever you want to add a page to your site, you add a corresponding file in src. pub.pl does different things to each file depending on its extension, that is, the string following the last . in a file's name. for instance, in the filename index.md, the extension is md.

• markdown (md): markdown is a lightweight, human-readable, human-writable syntax for adding formatting cues to plain-text documents. when pub.pl encounters a .md file, it formats it in HTML and saves the compiled version as a .html file. so for instance, if you have a file src/index.md, this will be compiled to out/index.html.
• text files (txt): text files are handled similarly to markdown files except they are not processed for formatting cues. they are given a top-level header based on the filename and each line is split into a paragraph. there is no way to add formatting such as bold text, links, or lists.
• HTML files (html): if you need more control than markdown can give you, you can place snippets of HTML code directly in the src directory tree. these should not be full HTML documents as their contents will be embedded in the standard page template. html files receieve no processing.
• any other file types, including files with no extension, are copied raw to out. this includes things like images, stylesheets, audio, and video.

if for whatever reason you need to include the raw, completely unformatted version of md, txt, or html file (such as to give your site a functional robots.txt), you can simply place .raw after the true file extension. for example, src/robots.txt.raw is copied unchanged to out/robots.txt.