The document template in detail

The document template is Git repository with all the directories an files necessary to start writing a new Decidim document.

Document template public repository

Anatomy of a document repository

All document repositories have the following file structure after importing the template:

.
├── ca (1)
│   ├── antora.yml
│   └── modules
│       └── ROOT
│           ├── […​]
│           └── pages
│               └── […​]
├── CONTRIBUTING.adoc (2)
├── en (3)
│   ├── antora.yml (4)
│   └── modules
│       └── ROOT
│           ├── assets
│           │   ├── attachments (5)
│           │   └── images (6)
│           ├── _attributes.adoc (7)
│           ├── examples (8)
│           ├── nav.adoc (9)
│           └── pages (10)
│               ├── _attributes.adoc (11)
│               ├── contributing.adoc (12)
│               ├── doc-info.adoc (13)
│               ├── introduction.adoc (14)
│               ├── _partials (15)
│               │   ├── CONTRIBUTING.adoc (16)
│               │   └── README.adoc (17)
│               └── single-page.adoc (18)
├── es (19)
│   ├── antora.yml
│   └── modules
│       └── ROOT
│           ├── […​]
│           └── pages
│               └── […​]
├── LICENSE (20)
├── README.adoc (21)
├── .editorconfig (22)
└── .gitignore (23)
1 Directory for the Catalan version, with some parts elided. Some parts have been elided, but it has the same structure as the English directory.
2 Authorship criteria and how to contribute to this document. It is an exact copy of 16, cloned here for easy browsing from GitHub web site.
3 Directory for the English version.
4 File with configuration information for the publication of the document in the documentation site.
5 All files to be downloaded from the website (e.g. PDF files) belong to this directory.
6 All images (in PNG, SVG or JPEG format) are stored here.
7 You do not need to change this file. It defines some Asciidoc attributes and is included in 11.
8 If you need to include (parts of) code listings in your documentation, put your source code files in this directory.
9 Navigation file for publication of the document in the documentation site.
10 All text is placed in this directory, with an .adoc file for every chapter or section.
11 You do not need to change this file. It defines some Asciidoc attributes. It needs to be included in every page in 10 for a correct while editing.
12 You do not need to modify this file. It can be used in the navigation to show the information contained in 16 (authoring and contributing).
13 You do not need to modify this file. It can be used in the navigation to show the information contained in 17 (metadata).
14 An file example for a possible section or chapter. Rename the file if you do not want to have any section named "Introduction".
15 Put in this directory .adoc files that you want only to include from other .adoc files but without generating a proper page to be independently shown in the documentation website.
16 Authorship criteria and how to contribute to this document. You do not need to change this file.
17 Metadata file: it defines a value for attributes like {title}, {authors}, {summary}, etc. that can be reused all across the document source files.
18 A file including all other .adoc files. See section Add a reference to the new file in single-page.adoc.
19 Directory for the Spanish version, with some parts elided.
20 The GFDL-1.3 license. The CC-BY-SA-4.0 license is not included in the repository, it is enough to refer to it in the needed places.
21 Metadata file. It is an exact copy of 17, cloned here for easy browsing from GitHub web site. You need to copy the file again every time 17 is modified.
22 An EditorConfig file. In combination with the EditorConfig VS Code extension, it facilitates uniform line-ending and other conventions across different OSs. The contents of this file should not be modified.
23 Initial .gitignore file. If you add items to it remember to commit the changes.

This structure may seem artificially complex, but the web publishing tool relies on it to automatically generate an static site.

The most important part is that .adoc files must be placed in a pages directory under a modules/ROOT subtree.

Header lines for .adoc files

TODO.