File organization
Inside a given working directory, wmk
assumes the following subdirectories for
content and output. They will be created if they do not exist:
-
htdocs
: The output directory. Rendered, processed or copied content is placed here, andwmk serve
will serve files from this directory. -
templates
: Mako templates. Templates with the extension.mhtml
are rendered directly intohtdocs
as.html
files (or another extension if the filename ends with.$ext\.mhtml
, where$ext
is a string consisting of 2-4 alphanumeric characters), unless their filename starts with a dot or underscore or contains the stringbase
, or if they are directly inside a subdirectory namedbase
. For details on context variables received by such stand-alone templates, see Context variables. -
content
: typically markdown (*.md
) and/or HTML (*.html*
) content with YAML metadata, although other formats are also supported. For a full list, see Input formats above. - Markdown (or other supported content) will be converted into HTML and then
"wrapped" in a layout using the
template
specified in the metadata ormd_base.mhtml
by default. - HTML files inside
content
are assumed to be fragments rather than complete documents. Accordingly, they will be wrapped in a layout just like the converted markdown. In general, such content is treated just like markdown files except that the markdown-to-html conversion step is skipped. For instance, shortcodes can be used normally, although they may not work as expected if they return markdown rather than HTML. (Complete HTML documents are best placed instatic
rather thancontent
). - The YAML metadata may be (a) at the top of the md/html document itself,
inside a frontmatter block delimited by
---
; (b) in a separate file with the same filename as the content file, but with an extra.yaml
extension added; or (c) it may be inindex.yaml
files which are inherited by subdirectories and the files contained in them. For details, see Site, page and nav variables. - The target filename will be
index.html
in a directory corresponding to the basename of the source file – unlesspretty_path
in the metadata isfalse
or the name of the file itself isindex.md
orindex.html
(in which case the relative path is remains the same, except that the extension is of course changed to.html
if the source is a markdown file). - The processed content will be passed to the Mako template as a string in the
context variable
CONTENT
, along with other metadata. - A YAML datasource can be specified in the metadata block as
LOAD
; the data in this file will be added to the context. For further details on the context variables, see Context variables. -
Files that have other extensions than
.md
,.html
or.yaml
will be copied directly over to the (appropriate subdirectory of the)htdocs
directory. This is so as to enable "bundling", i.e. keeping images and "attachments" together with related markdown files. -
data
: YAML files for additional metadata. May be referenced in frontmatter data or used by templates. Other data files (CSV, SQLite, etc.) should typically also be placed here. -
py
: Directory for Python files. This directory is automatically added to the front ofsys.path
before Mako is initialized, meaning that Mako templates can import modules placed here. Implicit imports are possible by settingmako_imports
in the config file (see Configuration file). There are also two special files that may be placed here:wmk_autolaod.py
in your project, andwmk_theme_autoload.py
in the theme'spy/
directory. If one or both of these is present, wmk imports a dict namedautoload
from them. This means that you can assignPREPROCESS
andPOSTPROCESS
page actions by name (i.e. keys in theautoload
dict) rather than as function references, which in turn makes it possible to specify them in the frontmatter directly rather than having to do it via a shortcode. (For more onPRE-
andPOSTPROCESS
, see Site, page and nav variables). -
assets
: Assets for an asset pipeline. The only default handling of assets involves compiling SCSS/Sass files in the subdirectoryscss
. They will be compiled to CSS which is placed in the target directoryhtdocs/css
. Other assets handling can be configured via settings in the configuration file, e.g.assets_commands
andassets_fingerprinting
. This will be described in more detail in Site, page and nav variables. Also take note of thefingerprint
template filter, described in Template filters. -
static
: Static files. Everything in here will be rsynced directly over tohtdocs
.