# Where should I put component definitions in Zola 0.23? **URL:** \ **Category:** Support\ **Created:** [August 7, 2026, 5:21pm UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957 "2026-08-07T17:21:21Z")\ **Posts on this page:** 17\ **Page:** 1
**Author:** ![Rratic](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/rratic/32/1527_2.png) [@Rratic](https://zola.discourse.group/u/Rratic)\ **Post date:** [August 7, 2026, 5:21pm UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/1 "2026-08-07T17:21:21Z")
I used to put shortcodes under `templates/shortcodes`, but putting component definitions there doesn’t work. I tried `templates/components` but still doesn’t work. It’s not mentioned at all in documentation and I can’t find any examples using 0.23! ---
**Author:** ![keats](https://avatars.discourse-cdn.com/v4/letter/k/34f0e0/32.png) [@keats](https://zola.discourse.group/u/keats)\ **Post date:** [August 7, 2026, 6:25pm UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/2 "2026-08-07T18:25:33Z")
You can put them anywhere, they are discovered automatically. For the docs of Zola for example I’m putting them in [zola/docs/templates/components.html at master · getzola/zola · GitHub](https://github.com/getzola/zola/blob/master/docs/templates/components.html) but they could really any scattered across any files if you want. ---
**Author:** ![Colas.Nahaboo](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/colas.nahaboo/32/1610_2.png) [@Colas.Nahaboo](https://zola.discourse.group/u/Colas.Nahaboo)\ **Post date:** [August 7, 2026, 9:12pm UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/3 "2026-08-07T21:12:08Z")
Yes, they are scattered in 8 template files on my converted site, and in 7 templates files in my local copy of the apollo theme I use. They are scattered because I quickly auto-migrated my site to tera2 with AI, so they stayed in their previous place when they were macros or shortcodes, but I will surely now refactor them in a more logical way. PS: AI is superbly efficient to work with opinionated systems such as Zola, it would have struggled with Hugo sites for instance. You can see how I did it at [Migration of this site to the new Zola Tera2](https://colas.nahaboo.net/blog/migration-of-this-site-to-the-new-zola-tera2/) ---
**Author:** ![Rratic](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/rratic/32/1527_2.png) [@Rratic](https://zola.discourse.group/u/Rratic)\ **Post date:** [August 8, 2026, 3:06am UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/4 "2026-08-08T03:06:24Z")
Thanks I’ll try that out. Previously I used GPT 5.6 Sol and it did edit the files but keep failing the build (`Unknown component `...` `), then it turns to persuade me that there’s some bug in scaning templates on Windows. ---
**Author:** ![Rratic](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/rratic/32/1527_2.png) [@Rratic](https://zola.discourse.group/u/Rratic)\ **Post date:** [August 8, 2026, 3:50am UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/5 "2026-08-08T03:50:39Z")
Well AI still keep persuading me there’s some bug in Windows. Probably I shall stop trying and wait until some more stable version releases. ---
**Author:** ![keats](https://avatars.discourse-cdn.com/v4/letter/k/34f0e0/32.png) [@keats](https://zola.discourse.group/u/keats)\ **Post date:** [August 8, 2026, 6:03am UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/6 "2026-08-08T06:03:42Z")
> [@Rratic](#): > > it turns to persuade me that there’s some bug in scaning templates on Windows. Not that I am aware. Tera runs tests on Windows too. Can it create a repro that fails? ---
**Author:** ![Colas.Nahaboo](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/colas.nahaboo/32/1610_2.png) [@Colas.Nahaboo](https://zola.discourse.group/u/Colas.Nahaboo)\ **Post date:** [August 8, 2026, 6:24am UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/7 "2026-08-08T06:24:18Z")
- Did you use GPT 5.6 Sol (I used Luna, btw) via its web interface or via an harness (e.g opencode)? ---
**Author:** ![Rratic](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/rratic/32/1527_2.png) [@Rratic](https://zola.discourse.group/u/Rratic)\ **Post date:** [August 8, 2026, 9:13am UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/8 "2026-08-08T09:13:28Z")
I’m using Codex App and gave it link to the CHANGELOG, and it also requested several times to read source code of Zola 0.23 and Tera v2. Well I think probably just some very strange situation is happening here. Me myself cannot find where’s wrong either. ---
**Author:** ![Rratic](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/rratic/32/1527_2.png) [@Rratic](https://zola.discourse.group/u/Rratic)\ **Post date:** [August 8, 2026, 9:13am UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/9 "2026-08-08T09:13:59Z")
Ok let me work out a minimal reproduceable example. ---
**Author:** ![Rratic](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/rratic/32/1527_2.png) [@Rratic](https://zola.discourse.group/u/Rratic)\ **Post date:** [August 8, 2026, 9:31am UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/10 "2026-08-08T09:31:47Z")
Here’s an example in [GitHub - Rratic/zola-test · GitHub](https://github.com/Rratic/zola-test) when you run `zola build` (using Zola 0.23.1), it will say: ```auto Building site... Failed to build the site Failed to render page content of '\\?\D:\my-blog\test\content\component.md' Reason: error: Unknown component `hello` --> __tera_one_off:1:3 | 1 | {{}} | ``` To provide more information, I put the repo in `D:\my-blog\test`, running through cmd, using Windows 10.0.19045.6466 ---
**Author:** ![Colas.Nahaboo](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/colas.nahaboo/32/1610_2.png) [@Colas.Nahaboo](https://zola.discourse.group/u/Colas.Nahaboo)\ **Post date:** [August 8, 2026, 12:29pm UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/11 "2026-08-08T12:29:04Z")
Strange, your zola-test repo works for me on linux, both with Zola 0.23.1 and Zola 0.23.2 ```auto colas@colas:~/git/zola-test$ zola build Building site... -> Creating 1 pages (0 orphan) and 0 sections Done in 17ms. colas@colas:~/git/zola-test$ zola -V zola 0.23.0 # updating zola... colas@colas:~/git/zola-test$ zola -V zola 0.23.2 colas@colas:~/git/zola-test$ zola build Building site... -> Creating 1 pages (0 orphan) and 0 sections Done in 238ms. ``` ---
**Author:** ![keats](https://avatars.discourse-cdn.com/v4/letter/k/34f0e0/32.png) [@keats](https://zola.discourse.group/u/keats)\ **Post date:** [August 8, 2026, 2:57pm UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/12 "2026-08-08T14:57:18Z")
> [@Colas.Nahaboo](#): > > - (\*) I think Zola 0.23 should have been renamed Zola2 Nah, LLMs can just be pointed at the docs if needed. Not going to inconvenience human users for AI. Thanks for the repro i’ll have a look even though I don’t have a Windows machine x). It’s probably due to `\\?\D:` i’ll try to make a repro in CI ---
**Author:** ![Rratic](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/rratic/32/1527_2.png) [@Rratic](https://zola.discourse.group/u/Rratic)\ **Post date:** [August 8, 2026, 3:52pm UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/13 "2026-08-08T15:52:50Z")
I just tried using 0.23.2 and put the repo on desktop and still can’t work. ---
**Author:** ![Colas.Nahaboo](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/colas.nahaboo/32/1610_2.png) [@Colas.Nahaboo](https://zola.discourse.group/u/Colas.Nahaboo)\ **Post date:** [August 8, 2026, 4:39pm UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/14 "2026-08-08T16:39:04Z")
Some hints from AI: ```auto The \\?\D: form is not something Zola decides — it's forced by Rust std inside Tera. In tera::load_from_glob (tera/src/globbing.rs:32): let parent_dir = std::fs::canonicalize(parent_dir).unwrap_or_else(|_| PathBuf::from(parent_dir)); std::fs::canonicalize on Windows uses GetFinalPathNameByHandleW(FILE_NAME_NORMALIZED), which always returns the verbatim \\?\D:\... form (there's no registry key, env var, or path style that changes it; it's the only unambiguous canonical form, and Rust deliberately returns it). So no config, zola.toml setting, or environment variable can stop Tera from seeing \\?\D:. The only way to keep paths non-verbatim is a code change in Tera: after canonicalize, run the path through dunce::simplified() (strips the \\?\ prefix back to D:\), or swap canonicalize for std::path::absolute (no verbatim prefix, but doesn't normalize ./.., so dunce is the right fix). That's upstream Tera work, not a user workaround. ``` ```auto Found it — the CLI canonicalizes the root at /tmp/zola-git/src/main.rs:109: let cli_dir: PathBuf = cli.root.canonicalize()... So on Windows root_dir is \\?\D:\my-blog\test and that verbatim form flows into the content path (matching your error) and into Tera's template glob. Let me check the upstream issues — this is a brand-new 0.23.x release, there may be a known report. %WebFetch https://api.github.com/search/issues?q=repo:getzola/zola+%22Unknown+component%22+OR+%22component+%60%22+windows %WebFetch https://api.github.com/search/issues?q=repo:getzola/zola+windows+%22templates%22+%22canonicalize%22+OR+%22verbatim%22+OR+%22%5C%5C%3F%5C%22 + Thought: 32.9s That's the confirmation — and it matches a documented Zola issue (#1692) with the identical //?/D: symptom and a fix-attempt PR (#1626) titled "Don't canonicalize paths because windows \\? prefix seems to break globbing." Let me verify the exact injection points in the current code. →Read /tmp/zola-git/src/main.rs [limit=40, offset=100] + Thought: 24.2s Confirmed the injection point at /tmp/zola-git/src/main.rs:109: let cli_dir: PathBuf = cli.root.canonicalize()... On Windows, std::fs::canonicalize always returns \\?\D:\.... That canonicalized root then flows into Site::new → load_tera → the template glob, and Tera's load_from_glob (tera/src/globbing.rs:32) canonicalizes again. So the verbatim form is forced by two hardcoded canonicalize() calls — it's not a Zola setting. ``` ---
**Author:** ![keats](https://avatars.discourse-cdn.com/v4/letter/k/34f0e0/32.png) [@keats](https://zola.discourse.group/u/keats)\ **Post date:** [August 9, 2026, 10:44am UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/15 "2026-08-09T10:44:26Z")
It should be fixed in the next branch ([Next version by Keats · Pull Request #3222 · getzola/zola · GitHub](https://github.com/getzola/zola/pull/3222)) if you want to try building it yourself ---
**Author:** ![shartrec](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/shartrec/32/1640_2.png) [@shartrec](https://zola.discourse.group/u/shartrec)\ **Post date:** [August 13, 2026, 3:07am UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/16 "2026-08-13T03:07:30Z")
I had exactly this same problem, but it was not the placement of the components, but the syntax required to invoke them. For short code I used ```auto {% warning() %}You can only edit a transaction if the following conditions are met: - The transaction occurred within the **current, open accounting period**. - **Strict Audit Mode** is turned **off** in the organization's settings. If these conditions are not met, the "Edit" button will be disabled. {% end %} ``` `but now for the component the following format is required` ```auto {{}} ``` This took me ages to work out. The changelogs and docs were no help. ---
**Author:** ![keats](https://avatars.discourse-cdn.com/v4/letter/k/34f0e0/32.png) [@keats](https://zola.discourse.group/u/keats)\ **Post date:** [August 13, 2026, 8:09am UTC](https://zola.discourse.group/t/where-should-i-put-component-definitions-in-zola-0-23/2957/17 "2026-08-13T08:09:15Z")
This is not the required format, if you want to take a body: > You can do ```auto {% %} You can only edit a transaction if the following conditions are met: - The transaction occurred within the **current, open accounting period**. - **Strict Audit Mode** is turned **off** in the organization's settings. If these conditions are not met, the "Edit" button will be disabled. {% %} ``` and print `{{ body }}` in your component