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, and
wmk servewill serve files from this directory.
templates: Mako templates. Templates with the extension
.mhtmlare rendered directly into
.htmlfiles (or another extension if the filename ends with
$extis a string consisting of 2-4 alphanumeric characters), unless their filename starts with a dot or underscore or contains the string
base, or if they are directly inside a subdirectory named
base. 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
templatespecified in the metadata or
- HTML files inside
contentare 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 in
- 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
.yamlextension added; or (c) it may be in
index.yamlfiles 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.htmlin a directory corresponding to the basename of the source file – unless
pretty_pathin the metadata is
falseor the name of the file itself is
index.html(in which case the relative path is remains the same, except that the extension is of course changed to
.htmlif 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
.yamlwill be copied directly over to the (appropriate subdirectory of the)
htdocsdirectory. This is so as to enable “bundling”, i.e. keeping images and “attachments” together with related markdown files.
- Markdown (or other supported content) will be converted into HTML and then “wrapped” in a layout using the
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 of
sys.pathbefore Mako is initialized, meaning that Mako templates can import modules placed here. Implicit imports are possible by setting
mako_importsin the config file (see Configuration file). There are also two special files that may be placed here:
wmk_autolaod.pyin your project, and
wmk_theme_autoload.pyin the theme’s
py/directory. If one or both of these is present, wmk imports a dict named
autoloadfrom them. This means that you can assign
POSTPROCESSpage actions by name (i.e. keys in the
autoloaddict) 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 on
POSTPROCESS, 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 subdirectory
scss. They will be compiled to CSS which is placed in the target directory
htdocs/css. Other assets handling can be configured via settings in the configuration file, e.g.
assets_fingerprinting. This will be described in more detail in Site, page and nav variables. Also take note of the
fingerprinttemplate filter, described in Template filters.
static: Static files. Everything in here will be rsynced directoy over to