GuideStart a new project
Project structure
The folders of a Douze site, what each one holds, and how source files map to output files.
A Douze site is a folder. Douze recognizes a few folders by their names, all optional, and builds everything else with conventions. This page describes them, and how a source file becomes an output file.
A typical siteLink to this heading
my-site/
├── _content/ pages and files to publish
│ ├── index.md
│ ├── about.md
│ ├── blog/
│ │ ├── blog.yml folder data for blog/ and its subfolders
│ │ └── first-post.md
│ ├── css/site.css
│ └── feed.xml.liquid
├── _data/ site data
│ ├── site.json
│ └── sidebar.yml
├── _includes/ layouts, includes and templates
│ ├── base.liquid
│ ├── post.liquid
│ └── shortcodes/ shortcodes
│ └── callout.liquid
├── douze.yml optional configuration
├── _site/ the output, written by douze
└── .douze/ the cache, written by douze
FoldersLink to this heading
| Folder | Default | Contains |
|---|---|---|
| content | _content if it exists, else the source folder |
Pages, folder data files, and any other file to publish |
| data | _data if it exists, else none |
Site data |
| includes | _includes if it exists, else the source folder |
Layouts, includes and templates |
| shortcodes | shortcodes in the includes folder |
Shortcodes |
The site section of douze.yml changes them (content, data, includes, shortcodes), and a folder set there
is used whether or not it exists. Paths are relative to the source folder.
site:
content: docs
data: data
includes: templates
_contentLink to this heading
Every file of the content folder goes through the workflow. Markdown (.md), HTML (.html) and Liquid (.liquid)
files are pages: their front matter is read, they are rendered as Liquid, and the HTML ones get their layouts. The data
files (.yml, .yaml, .json, .xml) are folder data, not published: their top-level keys apply to the pages of
their folder and its subfolders. Every other file, such as an image, a stylesheet or a font, is copied as it is.
The content folder is removed from output paths: _content/blog/first-post.md is published at /blog/first-post/.
_dataLink to this heading
Each file of the data folder is a site value named after the file: _data/site.json is site, _data/sidebar.yml
is sidebar, and _data/pkgs/Contoso.Hosting.json is pkgs["Contoso.Hosting"]. Two files cannot define the same
name. See Data files.
_includesLink to this heading
Layouts (layout: post.liquid), files of {% include %} and {% render %}, and the templates of steps (liquid
with a template, highlight templates, social-image templates) are looked up in the includes folder. See
Layouts and Includes and shortcodes.
_includes/shortcodesLink to this heading
Each Liquid file of this folder is a tag that every template can use: shortcodes/callout.liquid is
{% callout %}. See Includes and shortcodes.
douze.ymlLink to this heading
The optional configuration file at the root of the source folder: the site, markdown and steps sections. See
Configuration overview.
_siteLink to this heading
The output folder. Douze writes the site there, and after a successful build deletes the files that previous builds
wrote and this one did not. -o sets another folder, relative to the current folder, and site.output in
douze.yml sets one relative to the source folder; -o wins. Without either, the output is _site in the current
folder, so douze -s my-site run from the parent folder writes to ./_site.
.douzeLink to this heading
The cache folder: the results of the previous builds (.douze/cache/), the tools that steps download
(.douze/tools/) and the temporary folders of command steps (.douze/tmp/). --cache-dir moves it. Add both
.douze/ and _site/ to your .gitignore.
_site/
.douze/
The output folder and the cache folder are skipped when they are inside the source folder.
Sites without _contentLink to this heading
Without _content, the source folder is the content folder, and without _includes it is also the includes folder.
That is fine for a site of a few pages, but every file of the folder is then a page or an asset, layouts included:
base.html is published as /base/, and so are dot files and folders such as .gitignore, .git/ or
node_modules/. Only douze.yml, the data and includes folders when they exist, the output folder and .douze/ are left out.
How files map to outputsLink to this heading
The permalink step computes each output path from the source path, with the content folder removed:
| Source | Output | url |
|---|---|---|
_content/index.md |
index.html |
/index.html |
_content/about.md |
about/index.html |
/about/index.html |
_content/blog/first-post.html |
blog/first-post/index.html |
/blog/first-post/index.html |
_content/blog/index.html |
blog/index.html |
/blog/index.html |
_content/feed.xml.liquid |
feed.xml |
/feed.xml |
_content/css/site.css |
css/site.css |
/css/site.css |
_content/blog/blog.yml |
not published (folder data) |
A page's front matter permalink overrides its path, and permalink: false leaves it out. See
Routing and permalinks.