<page title="Stog documents"
navbar-doc="active"
>
<p>
A document is an XML tree, defined in a file matched by the regular expressions
given in the <doc href="overview#config-file">configuration file</doc>.
It has one of the following forms. First form:
</p>
<hcode lang="xml">
<![CDATA[<type title="Element title"
 attribute="value"
 attribute2="value2"
 ...
>
Here is the body of the document.
</type>
]]>
</hcode>
<p>Second form, almost the same, except that <ixml>with-contents="true"</ixml>
indicates that more attributes are given in subnodes, and the body is in the
<ixml>contents</ixml> subnode:
</p>
<hcode lang="xml">
<![CDATA[<type title="Element title"
 with-contents="true"
 attribute="value"
 ...
>
 <attribute2>value2</attribute2>
 ...
 <contents>Here is the body of the document.</contents>
</type>
]]>
</hcode>
<p id="documenttype">
<icode>type</icode> can be any string (like "post", "page", ...) and defines the type
of the document. This allows different treatments according to the document type.
</p>
<p>
You can specify any attribute for a document. Some attributes are used
internally:
</p>
<ul>
<li><b>title</b>: this is the title of the document; use <ixml>&lt;doc-title/&gt;</ixml>
in templates to access it,</li>
<li><b>keywords</b>: the list of comma-separated keywords associated to the document;
use <ixml>&lt;doc-keywords/&gt;</ixml> in templates to insert the list of keywords
with links to by-keyword index,</li>
<li><b>topics</b>: same as keywords, but for topics (access with <ixml>&lt;doc-topics/&gt;</ixml>),</li>
<li id="date"><b>date</b>: the document date, used for sorting in list. The date format follows
<ext-a href="https://tools.ietf.org/html/rfc3339">RFC 3339</ext-a> (<code>YYYY-MM-DD</code>).
The format <code>YYYY/MM/DD</code> is still supported for backward compatibility.
Use <ixml>&lt;doc-date/&gt;</ixml> in templates to insert it. The time of the document
is set to 00h00m00s.
</li>
<li id="datetime"><b>datetime</b>: the document date and time, used for sorting in list. The datetime format
follows <ext-a href="https://tools.ietf.org/html/rfc3339">RFC 3339</ext-a>
(like <code>1990-12-31T23:59:60Z</code> or <code>1937-01-01T12:00:27.87+00:20</code>).
Use <ixml>&lt;doc-datetime/&gt;</ixml> in templates to insert it.
</li>
<li><b>sets</b>: a comma-separated list of set names; sets can be used to list documents
belonging to a set,</li>
<li><b>language-dep</b>: can be set to <i>false</i> to indicate that this page is not
language dependent, when generating multi-language sites (this affects the name of the
generated file),</li>
</ul>
<p>
Any other attribute will be available by its name in the environment when processing the template
associated to the document type. The document type can be accessed with <ixml>&lt;doc-type/&gt;</ixml>.
More details in <doc href="atts-functions"></doc>.
</p>
<p>
To generate the file corresponding to a document, <icode>stog</icode> will use the type of
the document (for example "post") to load the associated template (for example "post.tmpl" in
the templates directory).
</p>
<p>If the XML template file used for a document type specifies a DOCTYPE, it is used
in the final XML file. If DOCTYPE is "HTML" (case-insensitive), tags are not self-closed, except
    <ext-a href="http://www.w3.org/html/wg/drafts/html/master/syntax.html#void-documents">HTML5 void documents</ext-a>.
</p>
<p>You can have a look at the source of the pages of this site at the bottom of each page.
The sources of this site can be a good starting point. You can browse it in the
<ext-a href="https://framagit.org/zoggy/stog/blob/master/doc">doc directory of the
distribution</ext-a>.
</p>
<hr width="100%"/>
<notes/>
</page>