To compile your web site, use the following command:

# stog <root-directory>

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.

Site location

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/>.

Template paths

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.

Module paths

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.

Additional definitions

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/>.

Plugins

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 Developing plugins.

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.

Handling languages

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.

Caching

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 Predefined modules and functions), 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.

Filtering published documents

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:

At last, the condition foo="" is true if the document has no attribute foo or if the attribute foo is empty.

Using with Make

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.

For information you can see the source code of the page.

<page title="Running Stog"
navbar-doc="active"
>
<p>
To compile your web site, use the following command:
</p>
<command>stog &lt;root-directory&gt;</command>
<p>Stog will generate the result in <icode>./stog-output</icode>,
except if you use the <icode>-d</icode> option to specify another
output directory.
</p>
<p>You can specify a template directory with the <icode>--tmpl</icode>
option. By default, the templates are searched in the <icode>.stog/templates</icode> directory
of the specified root directory.
</p>
<p>
It is possible to give more than one directory to <icode>stog</icode>. 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.
</p>
<p>
Stog can also be used to <doc href="single-documents">compile single documents</doc>.
</p>

<section id="siteurl" title="Site location">
<p>The <icode>--site-url</icode> option is used to override the <icode>stog:site-url</icode>
field of the main document. It it useful to generate a local site, for example
</p>
<command>stog --site-url file:///tmp/website your-directory</command>
<p>
to test your site locally with correct links.
</p>
</section>
<p id="optionlocal">
As a shortcut, the <icode>--local</icode> option sets <icode>stog:site-url</icode> to
<icode>file://&lt;absolute path of output directory/&gt;</icode>.
</p>

<section id="template-path" title="Template paths">
<p>By default, Stog will look for templates in the following directories, in this
order: <icode>.stog/templates</icode>, <icode>/path/to/stog/share/templates</icode>.
</p>
<p>The <icode>--tmpl &lt;dir&gt;</icode> 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:
</p>
<command>stog --tmpl dir1 --tmpl dir2 ...</command>
<p>Stog will look for templates in the following directories, in this order:
<icode>dir1</icode>, <icode>dir2</icode>, <icode>.stog/templates</icode>,
<icode>/path/to/stog/share/templates</icode>.
</p>
</section>

<section id="module-path" title="Module paths">
<p>By default, Stog will look for modules in the following directories, in this
order: <icode>.stog/modules</icode>, <icode>/path/to/stog/share/modules</icode>.
</p>
<p>The <icode>--mods &lt;dir&gt;</icode> 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:
</p>
<command>stog --mods dir1 --mods dir2 ...</command>
<p>Stog will look for modules in the following directories, in this order:
<icode>dir1</icode>, <icode>dir2</icode>, <icode>.stog/modules</icode>,
<icode>/path/to/stog/share/modules</icode>.
</p>
</section>

<section id="def" title="Additional definitions">
<p id="optiondef">
The <icode>--def</icode> option can be used to define an additional global rule. For example
</p>
<command>stog --def stogdir:`pwd`</command>
<p>
will make the current working directory accessible using <ixml>&lt;stogdir/&gt;</ixml>.
</p>
</section>

<section id="plugins" title="Plugins">
<p>The <icode>--plugin</icode> option makes <icode>stog</icode> 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 <page href="writing_plugins"/>.
</p>
<p>
If a plugin was installed with ocamlfind, the <icode>--package</icode> option can be used
to specify a list of comma-separated packages to load. <icode>ocamlfind</icode> will
then be used to get the location and required files to load these packages, in bytecode
for <icode>stog.byte</icode> or native-code for <icode>stog</icode>.
</p>
</section>
<section id="multilang" title="Handling languages">
<p>The <icode>--lang</icode> option is used to generate the website
for one language. By default, the only known languages are "en" and "fr".
If you use the <icode>--lang en</icode> option, then pages will be generated
in <icode>.html.en</icode> files and all <ixml>&lt;fr&gt;</ixml> nodes will be removed.
Then you can run <icode>stog</icode> with the <icode>--lang fr</icode>
to generate the "fr" part of your web site, removing all <ixml>&lt;en&gt;</ixml>.
</p>
<p>
The default language is "en". It is used when generating date representations.
The default language can be changed by using the <icode>--default-lang</icode> option,
for example:
</p>
<command>stog --default-lang fr ...</command>
<p>will generate pages with no language suffix, but with dates printed in french.</p>
<!--
<p>
If you need more languages, just define "stog:languages" in the main document
this way:
</p>
<hcode><![CDATA[<type main="true" ... stog:languages="es,de,fr,en">...</type>]]></hcode>
<p>This makes &lt;languages/&gt; returning the list of languages, and it is used by
the provided
-->
</section>

<section id="caching" title="Caching">
<p>
Stog will keep computed documents in directory <code>.stog/cache</code>.
To prevent stog from using this cache, use the <code>--nocache</code>
command line option. The cache won't be read, but it will nevertheless
be updated by contents of computed documents.
</p>
<p>
The caching strategy uses dependencies between documents: if a document
refers to another one (see <doc href="funs"/>), 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.
</p>
<p>
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 <code>--depcut</code> option specifies
to use non-recursive dependencies in the caching strategy.
</p>
</section>

<section id="filter" title="Filtering published documents">
<p>
By default, Stog will not compute documents having definition
<ixml>published="false"</ixml> or <ixml>published="0"</ixml>
in its header.
</p>
<p>The <icode>--publish-only</icode> option takes a filter and will
make Stog keep only the documents matching this filter.
</p>
<p>
For example, the following command will compute all documents except
the ones having "ocaml" in their topics:
</p>
<command>stog --publish-only "! (topic='ocaml')" ...</command>
<p>
See <doc href="module_base#documents">here</doc> 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 <rule>documents</rule> rule.
</p>
<p>Some attributes in the filter are handled specially:</p>
<ul>
<li><icode>type="t"</icode> is true if the document is of type <icode>t</icode>,</li>
<li><icode>keyword="k"</icode> is true if the document has <icode>k</icode> among its keywords,</li>
<li><icode>topic="t"</icode> is true if the document has <icode>t</icode> among its topics,</li>
<li><icode>set="s"</icode> is true if the document belong to set <icode>s</icode>.</li>
</ul>
<p>
At last, the condition <icode>foo=""</icode> is true if the document has no
attribute <icode>foo</icode> or if the attribute <icode>foo</icode> is empty.
</p>
</section>

<section id="makefile" title="Using with Make">
<p>
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 <ext-a href="https://github.com/zoggy/stog/tree/master/doc/Makefile">this
Makefile</ext-a> used to build stog documentation.
</p>
</section>
</page>