1# how to create a zola site
2
3a walkthrough for building a static site with [zola](https://www.getzola.org) on sublimated. zola is a fast static site generator that uses markdown content and tera templates.
4
5live demo: [docs.sublimated.com/zola/](https://docs.sublimated.com/zola/)
6
7## folder structure
8
9minimum zola site:
10
11```
12mysite/
13 config.toml site configuration (required)
14 content/
15 _index.md homepage
16 templates/
17 base.html shared layout
18 index.html homepage template
19 page.html single page template
20 section.html section listing template
21```
22
23## 1. config.toml
24
25the only required field is `base_url`. sublimated uses this to detect zola sites.
26
27```toml
28base_url = "https://myspace.sublimated.com/mysite"
29title = "my site"
30description = "a zola site on sublimated"
31compile_sass = false
32build_search_index = false
33generate_feeds = false
34
35[extra]
36```
37
38rules for `base_url`:
39- custom domain: `https://mysite.com`
40- subdomain: `https://myspace.sublimated.com/mysite`
41- must match the URL where the site will be served
42
43## 2. content
44
45content files are markdown with TOML frontmatter (between `+++` markers).
46
47```md
48+++
49title = "my first post"
50date = 2026-04-20
51description = "hello world"
52[taxonomies]
53tags = ["demo", "first"]
54+++
55
56the post body goes here. standard markdown: **bold**, *italic*, [links](https://example.com), `code`.
57```
58
59### content organization
60
61- `content/_index.md` — homepage (or section root)
62- `content/blog/_index.md` — creates a `/blog/` section with its own listing
63- `content/blog/my-post.md` — a page at `/blog/my-post/`
64- `content/about.md` — standalone page at `/about/`
65
66### sections vs pages
67
68- a folder with `_index.md` is a **section** — it lists its child pages
69- a standalone `.md` file is a **page**
70- sections use `section.html` template, pages use `page.html`
71
72### co-located assets (images)
73
74put images next to your markdown by using a folder with `index.md`:
75
76```
77content/blog/my-post/
78 index.md the post content
79 photo.jpg referenced as 
80 diagram.png
81```
82
83sublimated stores binary files in CAS and rewrites URLs to serve them from CDN. no special config needed.
84
85### frontmatter fields
86
87```toml
88+++
89title = "page title" # required
90date = 2026-04-20 # for sorting
91description = "page description" # meta description
92draft = false # hide from listings
93weight = 1 # manual sort order
94
95[taxonomies]
96tags = ["tag1", "tag2"] # tag pages auto-generated
97
98[extra]
99author = "name" # custom fields, access via page.extra.author
100image = "photo.jpg" # custom fields for templates
101+++
102```
103
104### summary separator
105
106use `<!-- more -->` to split a post into summary and body:
107
108```md
109this part shows in listings as the summary.
110
111<!-- more -->
112
113this part only shows on the full page.
114```
115
116access in templates: `{{ page.summary }}` and `{{ page.content }}`.
117
118## 3. templates
119
120templates use [tera](https://keats.github.io/tera/) syntax with inheritance.
121
122### base.html — shared layout
123
124```html
125<!DOCTYPE html>
126<html lang="en">
127<head>
128 <meta charset="utf-8">
129 <title>{% block title %}{{ config.title }}{% endblock %}</title>
130 <style>
131 /* all CSS goes here — inline for best performance */
132 body { font-family: -apple-system, sans-serif; max-width: 700px; margin: 0 auto; padding: 1rem; }
133 a { color: #1a5cc8; }
134 </style>
135</head>
136<body>
137 <header><a href="/">{{ config.title }}</a></header>
138 <main>{% block content %}{% endblock %}</main>
139 <footer>powered by zola + sublimated</footer>
140</body>
141</html>
142```
143
144### index.html — homepage
145
146```html
147{% extends "base.html" %}
148{% block content %}
149 {{ section.content | safe }}
150 {% set posts = get_section(path="blog/_index.md") %}
151 {% for page in posts.pages %}
152 <article>
153 <a href="{{ page.permalink }}">{{ page.title }}</a>
154 <time>{{ page.date | date(format="%B %d, %Y") }}</time>
155 </article>
156 {% endfor %}
157{% endblock %}
158```
159
160### page.html — single page
161
162```html
163{% extends "base.html" %}
164{% block title %}{{ page.title }} | {{ config.title }}{% endblock %}
165{% block content %}
166 <h1>{{ page.title }}</h1>
167 <time>{{ page.date | date(format="%B %d, %Y") }}</time>
168 <span>{{ page.reading_time }} min read</span>
169 {{ page.content | safe }}
170{% endblock %}
171```
172
173### section.html — section listing
174
175```html
176{% extends "base.html" %}
177{% block content %}
178 <h1>{{ section.title }}</h1>
179 {{ section.content | safe }}
180 {% for page in section.pages %}
181 <article>
182 <a href="{{ page.permalink }}">{{ page.title }}</a>
183 <time>{{ page.date | date(format="%B %d, %Y") }}</time>
184 </article>
185 {% endfor %}
186{% endblock %}
187```
188
189### useful template variables
190
191- `config.title`, `config.description`, `config.base_url`
192- `page.title`, `page.date`, `page.content`, `page.permalink`
193- `page.reading_time`, `page.word_count`, `page.toc`
194- `page.taxonomies.tags` — array of tag names
195- `page.extra.*` — custom frontmatter fields
196- `page.summary` — content before `<!-- more -->`
197- `section.pages` — child pages of a section
198- `current_path` — current URL path (useful for nav active states)
199
200## 4. shortcodes
201
202shortcodes are reusable snippets. create tera templates in `templates/shortcodes/`.
203
204`templates/shortcodes/note.html`:
205```html
206<div style="background:#dbeafe;border-left:3px solid #3b82f6;padding:0.75rem 1rem;margin:1rem 0;border-radius:4px">
207 <strong>Note:</strong> {{ body }}
208</div>
209```
210
211use in markdown:
212```
213{%/* note() */%}
214this is an important note.
215{%/* end */%}
216```
217
218## 5. taxonomies (tags)
219
220enable in config.toml:
221```toml
222taxonomies = [{ name = "tags" }]
223```
224
225create templates:
226- `templates/tags/list.html` — all tags page
227- `templates/tags/single.html` — posts for one tag
228
229add tags in frontmatter:
230```toml
231[taxonomies]
232tags = ["cooking", "travel"]
233```
234
235zola auto-generates `/tags/` and `/tags/cooking/` pages.
236
237## 6. push and build
238
239via git:
240```bash
241git add .
242git commit -m "my zola site"
243git push
244```
245
246or via CloudStorage — just save files, they sync automatically.
247
248sublimated detects `config.toml` with `base_url`, sends text files to the zola WASM builder, stores the output, and serves it at your URL. builds typically take under 1 second.
249
250## 7. image resizing
251
252append query params to image URLs for on-demand resizing:
253
254```html
255<img src="{{ page.extra.image }}?w=128">
256```
257
258- `?w=128` — resize to 128px wide (keeps aspect ratio)
259- works on any image served through sublimated CDN
260
261## what works
262
263- markdown with TOML frontmatter
264- tera templates with inheritance
265- syntax highlighting (40+ themes, 200+ languages)
266- shortcodes (body and inline)
267- taxonomies (tags, categories)
268- table of contents (auto-generated from headings)
269- internal links (`@/path/to/file.md` — validated at build time)
270- reading time and word count
271- Atom/RSS feeds
272- clean URLs
273- dark mode (CSS `prefers-color-scheme`)
274- co-located images and binary assets
275
276## what doesn't work yet
277
278- sass/scss compilation
279- search index generation
280- zola image processing (`resize_image()`)
281- `load_data()` from external URLs
282- multilingual sites (`default_language` config)
283
284## real example
285
286the kanapka site is a live reference: [kanapka.sublimated.com](https://kanapka.sublimated.com) — a food blog with sections, author pages, image thumbnails, and responsive layout.