mkdir ~/local
curl https://github.com/jorgefranconunes/yawg/releases/yawg-1.0.0-RC3.tar.gz \
| tar xfz -C ~/localThis is the user guide for Yawg. Yawg is a static site generator. Given a source directory tree with files, a new directory tree will be populated with HTML files generated from the baking of the source files. Yawg is able to bake files in AsciiDoc and HTML formats. Other types of files will just be copied without any modification.
This document is intended for end users.
The remainder of this document is organized as follows:
Requirements — Describes the pre-requisites needed for installing and running Yawg.
Downloading and installing Yawg — Provides instructions on installing the Yawg software.
Running Yawg — Shows you how to run Yawg and describes the command line options.
Baker types — Introduces you to the currently supported baker types: AsciiDoc, and HTML. The type of baker used defines how a given source file will be baked.
Configuring the baking process — Describes how the baking process can be configured per-directory. For example, which template to use, or which files should be ignored.
Page templates — Describes how templates are used for the rendering of the final HTML. This section also addresses the data model the template has access to for injecting data into the generated HTML.
For running Yawg you will need the following:
Linux — Any typical Linux distribution from the last five years should "just work" ™.
Java 8 — The Oracle JVM is known to work.
Graphviz — But only if you want to have PlantUML diagrams in your content.
While Windows is not yet explicitly supported, you can still run Yawg just fine under Cygwin.
Tarballs of Yawg releases are hosted on GitHub.
After downloading the tarball, the installation consists simply of untaring said tarball. An example combining download and untaring follows:
mkdir ~/local
curl https://github.com/jorgefranconunes/yawg/releases/yawg-1.0.0-RC3.tar.gz \
| tar xfz -C ~/localThe example example above would have installed Yawg under directory
$HOME/local/yawg-1.0.0-RC3/.
The only files under the installation directory you need to know about are listed below. All other files are for internal use by Yawg. You should not, of course, ever need to modify any of the files under the installation directory.
bin/yawg — The command line tool for running yawg. Described in
detail in the next section.
doc — End user documentation.
The command line tool to bake sites lives at bin/yawg under the
installation directory. This is the tool that is used for baking a
site from a tree of documents.
Yawg requires Java 8 to run. You tell the bin/yawg tool which JVM to
use in one of the following ways:
If the environment variable YAWG_JAVA_HOME is defined, it will be
used to select the JVM.
Otherwise, if the environment variable JAVA_HOME is defined, it
will be used to select the JVM.
Otherwise, Yawg will attemp to use the java accessible in the
PATH.
Otherwise, Yawg will despondently give up, and print a failure message gently reminding you of the error in your ways.
Running bin/yawg without any arguments will just print some
information on how to use the tool.
Yawg 1.0.0 - CLI Baker
Copyright (c) 2016 Yawg project contributors.
Usage: yawg [OPTION] ...
Bakes a site from a directory tree.
Options:
-h,--help show this help text and exit
--page-var <NAME=VALUE> additional page variable
--source <PATH> path of source directory
--target <PATH> path of target directory
--templates <PATH> path of templates directory
-v,--version show version and exit
--verbose show abundant logging
Find additional information at http://yawg.varmateo.com/
The bin/yawg command supports the following command line options:
--page-var <NAME=VALUE> — Defines a page variable that will be
visible to the templates for all pages. The value of page variables
defined through this option will always be strings. You can give this
option multiple times to specify more than one page variable.
--source <PATH> — Path to the directory containing the content
source files to be baked.
--target <PATH> — Path to the directory where the results of the
baking will be copied to. If this directory does not yet exist, it
will be created.
--templates <PATH> — Path to the directory containing the page templates
that may be used during the baking.
--verbose — Print detailed logging during the baking. By default
only minimal logging is shown.
--version — Prints the version of the Yawg software and exits.
There are three types of baker at the moment.
Asciidoc — Converts input files in AsciiDoc format to HTML.
HTML — Converts an input file in HTML format to another HTML file generated by the selected page template.
Copy — Just copies the input file to the target directory without making any change.
A set of baking parameters can be used to influence the baking process. Each directory under the source directory being baked can specify its own set of baking parameters.
The baking parameters are defined in a file named .yawg.yml inside
each directory. The existence of the .yawg.yml file is optional. If
there is no .yawg.yml file in a given directory, then the baking
parameters for the parent directory will be used instead.
The .yawg.yml file, as you might have guessed, is in
YAML format.
The supported baking parameters are listed below.
bakerTypes (Map<String,List<String>>) — Map that specifies the
baker type to be used for certain files. This is useful when you want
to override the default baker type for some files (e.g. when you want
*.txt files baked with the asciidoc baker). The keys are baker
types. The values are a list of glob patterns representing the files
to be baked by that baker type.
exclude (List<String>) — List of glob patterns representing the
files that are to be excluded from the bake. These files will not be
processed in any way.
excludeHere (List<String>) — List of glob patterns representing
the files that are to be excluded from the bake only in the
directory where this parameter is specified. This parameter is not
propagated to child directories.
extraDirsHere (List<String>) — List of additional directories
to be baked into the current target directory. The elements of the
list are file system paths of directories. If a path is relative it is
taken as being relative to the directory currently being baked. Only
the content of the extra source directories is baked into the current
target directory. The target directory will not contain a directory
with the same name as the extra directory.
includeHere (List<String>) — List of glob patterns representing
the files in the directory that are to be baked. All other files in
the directory will be skipped. This parameter takes precedence over
the exclude and excludeHere parameters.
pageVars (Map) — Set of additional variables to be added to the
page template data model. These variables will be propagated to
child directories. See Page templates.
pageVarsHere (Map) — Set of additional variables to be added to the
page template data model. These variables will not be propagated to
child directories. See Page templates.
template (String) — The name of the page template to use for
baking the files in the directory. If not specified it will default to
default.ftlh.
templatesHere (Map<String,List<String>>) — Map that specifies
the templates to be used for certain files. The keys are template
names. The values are a list of glob patterns representing the files
for which the corresponding template will be used. This parameter is
not propagated to child directories.
The baker types that can be specified for the bakerTypes parameter
are the ones described in Baker types. The possible values
currently supported are the following:
asciidoc — AsciiDoc baker.
html — HTML baker.
copy — Plain copy baker.
Yawg supports Freemarker page templates.
The page template files are read from the directory specified with the
--templates command line option.
The page template has access to a set of variables while it is being processed during the baking of a document. We call data model to the set of variables accessible to the page template.
The variables composing the data model are described below.
yawg.bakeId — Unique bake ID. Each bake will have a different
identifier.
yawg.body — String containing the raw HTML resulting from
converting the source document into HTML. This is an HTML snippet
ready to be included in a <body> element, or any other block level
element.
yawg.pageUrl — The URL of the page being baked relative to the
top URL of the baked site.
yawg.productName — The name of the Yawg software
(i.e. "Yawg"). The value of this template variable is always the
same, for a given Yawg release.
yawg.rootRelativeUrl — The relative URL for the top URL of the
baked site. Useful for refering to resources at the top of the
document tree.
yawg.title — The document title. If the source document did not
define a title, then the base name of the source document file will
be used as title.
yawg.version — The version of the Yawg software. The value of
this template variable is always the same, for a given Yawg release.