1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
+++
title = "Overview"
weight = 10
+++
Zola uses the directory structure to determine the site structure.
Each child directory in the `content` directory represents a [section](@/content/section.md)
that contains [pages](@/content/page.md) (your `.md` files).
```bash
.
└── 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 `path` or
`slug` attribute of the [page front-matter](@/content/page.md#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.
The `content` directory in this case has three `sections`: `content`, `blog` and `landing`. The `content` section has only
one page (`something.md`), the `landing` section has no pages and the `blog` section has 4 pages (`cli-usage.md`,
`configuration.md`, `directory-structure.md` and `installation.md`).
Sections can be nested indefinitely.
## Asset colocation
The `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 `latest-experiment.md`), but
as an `index.md` file in a dedicated directory (`latest-experiment/index.md`), like so:
```bash
└── research
├── latest-experiment
│ ├── index.md
│ └── yavascript.js
├── _index.md
└── research.jpg
```
With this setup, you may access `research.jpg` from your 'research' section
and `yavascript.js` from your 'latest-experiment' page directly within the Markdown:
```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 `https://example.com/research/latest-experiment/`.
### Excluding files from assets
It is possible to ignore selected asset files using the
[ignored_content](@/getting-started/configuration.md) 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"]
```
## Static assets
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 `static` directory
will be copied, without modification, to the `public` directory.
Typically, you might put site-wide assets (such as the site favicon, site logos or site-wide
JavaScript) in the root of the static directory. You can also place any HTML or other files that
you wish to be included without modification (that is, without being parsed as Markdown files)
into the static directory.
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):
```bash
.
└── 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/configuration` directory and then link to it with a
relative path from the `index.md` page. This is the approach described under **co-location**
above.
* You could save the image to a `static/blog/configuration` directory 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).
|
