tsunami  input-files.md at [6f8377c8fe]

File src/doc/input-files.md artifact 2ff644eab2 part of check-in 6f8377c8fe


# 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](markdown.html) (`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`.