To compile your web site, use the following command:
]]>
Stog will generate the result in ./stog-output,
except if you use the -d option to specify another
output directory.
You can specify a template directory with the --tmpl
option. By default, the templates are searched in the .stog/templates directory
of the specified root directory.
It is possible to give more than one directory to stog. In this case,
all documents are merged as if all were defined in the last directory
given. It may be useful to gather blogs or pages to generate one big site. Or not.
Stog can also be used to compile single documents.
The --site-url option is used to override the stog:site-url
field of the main document. It it useful to generate a local site, for example
stog --site-url file:///tmp/website your-directory
to test your site locally with correct links.
As a shortcut, the --local option sets stog:site-url to
file://<absolute path of output directory/>.
By default, Stog will look for templates in the following directories, in this
order: .stog/templates, /path/to/stog/share/templates.
The --tmpl <dir> option allows to specify an additional
directory to look for templates, before the default ones. This options can be used
several times. In the following example:
stog --tmpl dir1 --tmpl dir2 ...
Stog will look for templates in the following directories, in this order:
dir1, dir2, .stog/templates,
/path/to/stog/share/templates.
By default, Stog will look for modules in the following directories, in this
order: .stog/modules, /path/to/stog/share/modules.
The --mods <dir> option allows to specify an additional
directory to look for modules, before the default ones. This options can be used
several times. In the following example:
stog --mods dir1 --mods dir2 ...
Stog will look for modules in the following directories, in this order:
dir1, dir2, .stog/modules,
/path/to/stog/share/modules.
The --def option can be used to define an additional global rule. For example
stog --def stogdir:`pwd`
will make the current working directory accessible using <stogdir/>.
The --plugin option makes stog dynamically
load the given OCaml object file. The loaded plugin can define new functions
to associate to some tags, or even override some pre-defined functions.
See .
If a plugin was installed with ocamlfind, the --package option can be used
to specify a list of comma-separated packages to load. ocamlfind will
then be used to get the location and required files to load these packages, in bytecode
for stog.byte or native-code for stog.
The --lang option is used to generate the website
for one language. By default, the only known languages are "en" and "fr".
If you use the --lang en option, then pages will be generated
in .html.en files and all <fr> nodes will be removed.
Then you can run stog with the --lang fr
to generate the "fr" part of your web site, removing all <en>.
The default language is "en". It is used when generating date representations.
The default language can be changed by using the --default-lang option,
for example:
stog --default-lang fr ...
will generate pages with no language suffix, but with dates printed in french.
Stog will keep computed documents in directory .stog/cache
.
To prevent stog from using this cache, use the --nocache
command line option. The cache won't be read, but it will nevertheless
be updated by contents of computed documents.
The caching strategy uses dependencies between documents: if a document
refers to another one (see ), a dependency will be
added and stored in the cache directory, so that this dependency will
be used during the next run of stog. A document can also depend
on files: the templates used, the files included, ... Dependencies are
recursively computed.
In some cases, using recursive dependencies may be too complete. For example,
if you have a menubar appearing in all pages, all pages will depend on
the documents referenced by the menubar, leading to all documents depending
on all documents. A change in any document will then make every document recomputed
at each run. To prevent this, the --depcut
option specifies
to use non-recursive dependencies in the caching strategy.
By default, Stog will not compute documents having definition
published="false" or published="0"
in its header.
The --publish-only option takes a filter and will
make Stog keep only the documents matching this filter.
For example, the following command will compute all documents except
the ones having "ocaml" in their topics:
stog --publish-only "! (topic='ocaml')" ...
See here for filter syntax. Beware
that the condition to keep only some documents to publish is evaluated
without performing XML rewriting on the document definitions, as opposed
as when evaluating filters in the documents rule.
Some attributes in the filter are handled specially:
- type="t" is true if the document is of type t,
- keyword="k" is true if the document has k among its keywords,
- topic="t" is true if the document has t among its topics,
- set="s" is true if the document belong to set s.
At last, the condition foo="" is true if the document has no
attribute foo or if the attribute foo is empty.
A convenient way to use stog is to create a Makefile with different targets,
to generate your site for a local test and for online publishing.
Have a look at this
Makefile used to build stog documentation.