Please note that determining the output location for assets differs significantly from other systems for example Jekyll. Whereas in Jekyll you normally set the permalink of an asset, in Qgoda you normally set the output path and the permalink is computed from the path. The result is very similar but maybe more flexible.
By default, an asset's location is simply preserved. That means if you have an
asset {srcdir}/assets/images/logo.jpeg it will be copied to
{sitedir}/assets/images/logo.jpeg.
Processed assets are subject to path translation. Their relative path to
the site directory is by default modified. With the default configuration
the asset {srcdir}/pages/en/about-qgoda.htm would end up as
{sitedir}/pages/en/about-qgoda/index.htm and the markdown input file
{srcdir}/posts/en/version-0.2-released.md would end up as
{sitedir}/posts/en/version-0.2-released/index.html.
For the gory details of the process, let's take the input location
{srcdir}/posts/en/version-0.2-released.md as an example.
The starting point is the relative path to the source directory
/posts/en/version-0.2-released.md which has the following components:
By default the output location of a document in Qgoda relative to the
configured site directory is
{directory}/{basename}/{index}.{suffix}. The variable index
has the default value index
which is no coincidence but the default value
used by all common web servers.
Asset processing is triggered by the suffixes of the source file. The triggers
are defined in the variable processors.triggers in the site configuration
file _qgoda.yaml. Look at this excerpt of the Qgoda default configuration:
processors:
triggers:
md: markdown
html: html
htm: html
chains:
markdown:
modules: [Markdown, HTML]
suffix: html
wrapper: html
html:
modules: HTML
modules:
Markdown: Markdown
HTML: Template::Toolkit
The suffix md triggers the processor chain markdown. This chain
has configured an output suffix html. The translated filename of the
output file is therefore not index.md but index.html.
The processor chain html does not define an output suffix. The suffix is
therefore left untouched.
A filename can have multiple suffixes, for example
what-is-qgoda.md.utf8.fr. This is useful for content negotiation as
implemented in the popular Apache web server. When doing suffix translation,
Qgoda translates the rightmost suffix. The example filename would therefore
be translated into what-is-qgoda/index.md.utf8.fr.
It is also important to note that all suffixes are considered for processor
chain selection. The rightmost suffix wins
. If you have a filename
example.html.md the markdown processor chain will be selected because
md is right of html.
You may have noticed in one the above example the filename
version-0.2-released.md which gets translated into
version-0.2-released/index.md. Obviously only md is considered a suffix
and 2-released is not.
Qgoda's notion of a suffix is a string of one or more alphanumerical
characters. Since 2-released contains a hyphen, it is not considered
a suffix.
Suffixes are extracted right to left, stopping at the first false positive.
Take version-0.22.beta-released.utf8.en.md as a rather esoteric example.
The software would consider md, en, utf8 suffixes and stop then
because beta-released contains a non-alphanumerical character. Although
22 (before the string beta
) contains only alphanumerical characters
because the suffix extraction had already stopped.
Permalinks are computed from the output location. By default, they are
simply the relative path to the site directory. If the filename portion
of the output location matches the configured index string (normally
index
) followed by one or more suffixes the filename is stripped off.
For example posts/en/about-qgoda/index.utf8.md would be translated into
the permalink /posts/en/about-qgoda/.
You can fully customize both output location and permalinks by setting the
variables location or permalink respectively in the front matter of an
asset, as a default for a certain directory or site wide in _qgoda.yaml.
You can interpolate all kinds of asset variables into the configured string
by placing them inside {curly} braces. For example the default configuration
for the variable location is /{directory}/{basename}/{config.index}.{suffix}.
The following variables are meaningful for location and permalink customization:
Note that variables are not necessarily plain old strings but can be more complicated. Take this example configuration in YAML:
dictionary:
foo: 1 # dictionary.foo
bar: 2 # dictionary['bar']
baz: 3 # dictionary["baz"]
array:
- Tom # array[0]
- Dick # array.1 also works.
- Harry # array['2'], you can also use double quotes.
Quoted strings have JavaScript semantics!