. └── 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
base_url, for example
blog/cli-usage/) can be customised by changing the
slug 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 the metadata and content of the section itself and is not considered a page.
To ensure that 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
one page (
landing section has no pages and the
blog section has 4 pages (
Sections can be nested indefinitely.
content directory is not limited to markup files. It's natural to want to co-locate a page and some related
assets, such as images or spreadsheets. Zola supports this pattern out of the box for both sections and pages.
All non-Markdown files you add in a page/section directory will be copied alongside the generated page when the site is built, which allows us to use a relative path to access them.
Pages with co-located assets should not be placed directly in their section directory (such as
index.md file in a dedicated directory (
latest-experiment/index.md), like so:
└── research ├── latest-experiment │ ├── index.md │ └── yavascript.js ├── _index.md └── research.jpg
With this setup, you may access
research.jpg from your 'research' section
yavascript.js from your 'latest-experiment' page directly within the Markdown:
Check out the complete program [here](yavascript.js). It's **really cool free-software**!
By default, this page's slug will be the directory name and thus its permalink will be
Excluding files from assets
It is possible to ignore selected asset files using the
ignored_content setting in the config file.
For example, say that you have an Excel spreadsheet from which you are taking several screenshots and
then linking to these image files on your website. For maintainability, you want to keep
the spreadsheet in the same directory as the Markdown file, but you don't want to copy the spreadsheet to
the public web site. You can achieve this by 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/directories that you place in the
will be copied, without modification, to the
Note that the static directory provides an alternative to co-location. 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/
To add an image to the
https://mywebsite.com/blog/configuration page, you have three options:
- You could save the image to the
content/blog/configurationdirectory and then link to it with a relative path from the
index.mdpage. This is the approach described under co-location above.
- You could save the image to a
static/blog/configurationdirectory and link to it in exactly the same way as if you had co-located it. If you do this, the generated files will be identical to those obtained if you had co-located the image; the only difference will be that all static files will be saved in the static directory rather than in the content directory. The choice depends on your organizational needs.
- Or you could save the image to some arbitrary directory within the static directory. For example,
you could save all images to
static/images. Using this approach, you can no longer use relative links. Instead, you must 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).