. └── content ├── content │ └── something.md // -> https://mywebsite.com/content/something/ ├── blog │ ├── cli-usage.md // -> https://mywebsite.com/blog/cli-usage/ │ ├── configuration.md // -> https://mywebsite.com/blog/configuration/ │ ├── directory-structure.md // -> https://mywebsite.com/blog/directory-structure/ │ ├── _index.md // -> https://mywebsite.com/blog/ │ └── installation.md // -> https://mywebsite.com/blog/installation/ └── landing └── _index.md // -> https://mywebsite.com/landing/
Each page path (the part after the
base_url, for example
blog/cli-usage/) can be customised by changing the
attribute of the page front-matter.
You might have noticed a file named
_index.md in the example above.
This file is used to store both metadata and content of the section itself and is not considered a page.
To make sure the terminology used in the rest of the documentation is understood, let's go over the example above.
content directory in this case has three
content section has only
landing section has no page and the
blog section has 4 pages:
While not shown in the example, sections can be nested indefinitely.
content directory is not limited to markup files though: it's natural to want to co-locate a page and some related
assets, for instance images or spreadsheets. Zola supports that pattern out of the box for both sections and pages.
Any non-markdown file you add in the page/section folder will be copied alongside the generated page when building the site, which allows us to use a relative path to access them.
For pages to use assets colocation, they should not be placed directly in their section folder (such as
latest-experiment.md), but as an
in a dedicated folder (
latest-experiment/index.md), like so:
└── research ├── latest-experiment │ ├── index.md │ └── yavascript.js ├── _index.md └── research.jpg
In this setup, you may access
research.jpg from your 'research' section,
yavascript.js from your 'latest-experiment' directly within the Markdown:
Check out the complete program [here](yavascript.js). It's **really cool free-software**!
By default, this page will get the folder name as its slug. So its permalink would be in the form of
It is possible to ignore selected asset files using the
ignored_content setting in the config file.
For example, say you have an Excel spreadsheet from which you are taking several screenshots and
then linking to those image files on your website. For maintainability purposes, you want to keep
the spreadsheet in the same folder as the markdown, but you don't want to copy the spreadsheet to
the public web site. You can achieve this by simply setting
ignored_content in the config file:
ignored_content = ["*.xlsx"]
In addition to placing content files in the
content directory, you may also place content
files in the
static directory. Any files/folders that you place in the
will be copied, without modification, to the public directory.
Note that the static folder provides an alternative to colocation. For example, imagine that you had the following directory structure (a simplified version of the structure presented above):
. └── content └── blog ├── configuration │ └── index.md // -> https://mywebsite.com/blog/configuration/ └── _index.md // -> https://mywebsite.com/blog/
If you wanted to add an image to the
https://mywebsite.com/blog/configuration page, you would
have three options:
content/blog/configurationfolder and then link it with a relative path from the
index.mdpage. This is the approach described under colocation, above.
static/blog/configurationfolder and link it in exactly the same way as if you had colocated it. If you do this, the generated files will be identical to if you had colocated; the only difference will be that all static files will be saved in the static folder rather than in the content folder. Depending on your organizational needs, this may be better or worse.
static/images. Using this approach, you would no longer be able to use relative links, but could use an absolute link to
images/[filename]to access your image. This might be preferable for small sites or for sites that associate images with multiple pages (e.g., logo images that appear on every page).