everkm-publish does what Hugo, Jekyll, and Zola do: turn Markdown into a static website. We didn't build it to be another blog generator. We built it so notes, docs, and knowledge bases can stay organized, discoverable, and interlinked as they grow over time — a problem the Everkm ecosystem has tackled from day one.
The sections below compare capabilities and show where we diverge from typical SSGs. For the full feature set, see Everkm Publish.
What we have in common
- No database required
- Local preview + static export
- Deploy anywhere static files go: Nginx, CDN, GitHub Pages, Vercel, and more
- Content and presentation separated: Markdown for body text, themes for layout
The output is standard HTML — SEO-friendly, no runtime dependencies.
1. Positioning: blogs, docs, and knowledge bases — you define the shape
Everkm Publish is not "wiki-only." One toolchain can host:
| Shape | How |
|---|---|
| Blog | template: list + tags / list pages |
| Book / docs site | template: book + _nav.md chapter tree |
| Knowledge base / wiki | Inner links + multi-level directories |
| Product site | Homepage + docs / changelog sections |
Hugo and Zola skew general-purpose; Jekyll skews blogging. Everkm covers the same ground, but site structure comes from folders, not a fixed "home → category → post" blog skeleton.
It shares indexing semantics with Abox Note, so writing and publishing are one pipeline — not two unrelated toolchains.
See also: Concepts and Architecture, Directory Configuration, Everkm Publish — Markdown Static Site Generator.
2. Site structure: folders config vs convention-based directories
This is one of the biggest differences.
Everkm declares rules per path in everkm.yaml#folders:
- Per-directory templates (
book/list/post, etc.) - URLs decoupled from disk layout (
url_slug,hide_in_url) - Hash-scattered storage (
hash_scatter) - Breadcrumbs and
query(e.g.nav_file) inherited and merged up the ancestor chain
/blog/2025/hello.md on disk can become /posts/hello.html publicly — intermediate folders don't have to appear in the URL.
| Everkm Publish | Hugo | Jekyll | Zola | |
|---|---|---|---|---|
| Structure | Explicit folders YAML | content/ + sections | _posts/ + collections | content/ + sections |
| URL control | Per-directory config + stable id | permalinks / slug | permalink templates | slug / section path |
| Doc navigation | _nav.md + built-in nav_tree | theme or plugins | plugins | custom |
See also: Directory Configuration.
3. Stable URL IDs: rename the title, keep the link working
In most SSGs, URLs follow titles or slugs — change the title and old inbound links break.
Everkm embeds a stable page ID in the URL by default (url_id_suffix: true):
/blog/hello-abc123.html ← slug + stable id
- Titles and slugs can change;
iddoes not - The host platform resolves or redirects by ID, so old links still reach the same page
- For short paths, turn it off:
url_id_suffix: false→/blog/hello.html
Plain static files won't redirect on their own — you need exported metadata + platform support:
| Capability | What it does |
|---|---|
| Export metadata | Index / file-meta output includes publish URLs; aliases and permalink feed the redirect graph |
| Nginx | --with-nginx-map generates url_map |
| Vercel | --with-vercel generates platform redirect config |
| Extra rules | everkm.yaml#redirects, merged with index aliases and the permalink map |
We wire "stable ID → URL mapping → Nginx / Vercel config" into the publish pipeline because knowledge gets retitled — inbound links shouldn't break.
See also: Directory Configuration, Article Metadata, Export and Publish, Site Configuration, CLI Quick Reference.
4. Everkm Markdown: a dialect built for linking
On top of standard Markdown and GFM, we added extensions aimed at writing and interconnection (full reference: Everkm Markdown Format):
| Extension | Purpose |
|---|---|
[[inner links]] | Cross-link pages and media; resolved to final URLs on export; ambiguity fails lint / export |
Macros macro/toc, macro/include | Auto TOC; embed Markdown, tables, code files, etc. |
| dCard | Declare display cards in body (downloads, audio/video, etc.); themes render HTML |
| Block / inline attributes | {.class}, #id, alignment, color, background, radius on headings, paragraphs, tables, links, images |
| Underline / superscript / subscript / highlight | {ul}#…#, ^…^, ~…~, … |
_nav.md | Chapter TOC, paired with nav_tree for book sidebars |
How to write links — by context:
- Body Markdown: Inner links
[[...]]are flexible — match by slug or title, relative directory ([[./faq/]]), site-root path ([[/docs/guide/quick-start.md]]), anchors ([[./page#section-id]]), custom display text ([[./faq/|FAQ]]), and more (see Links and Inner Links). - Export constraint: Don't use standard Markdown relative path links for intra-site navigation (e.g.
[Next page](./next.html)); validation blocks them on export. Use inner links instead. - Templates:
from_file/pathinnav_tree,post_detail, etc. also use[[...]], not relative file paths. - Validation:
everkm-publish lintcatches broken and ambiguous links; export / CI fails immediately on unresolvable links; preview marks them with a dashed underline without aborting the page.
Hugo has ref / relref, Jekyll relies on plugins, Zola has partial shortlink syntax — we unified inner links, attribute sets, macros, and dCard into one dialect and baked it into publish validation.
See also: Everkm Markdown Format, Links and Inner Links, Navigation and Table of Contents, Display Cards (dcard).
5. Themes: remote install + Jinja2 / TSX side by side
| Everkm Publish | Hugo | Jekyll | Zola | |
|---|---|---|---|---|
| Template engine | Jinja2 syntax and TSX / JS rendering as peers — use either or both | Go templates | Liquid | Tera |
| Theme distribution | theme install remote / ZIP | Modules / submodule | Gem | manual copy |
| Site overrides | __everkm/extend/ | layouts/ | _layouts/ | templates/ |
Theme ≠ page template. A theme is a full skin package; folders.template picks which page template a directory uses.
Reference themes:
Jinja2 and TSX are peers, not tiers. A single theme can mix both: Jinja2 for simple pages, TSX / JS rendering for complex layouts — pick per page.
For the TSX path we recommend SolidJS — far lighter than React, no virtual DOM, well suited to the build-time JS sandbox. You only need TSX syntax to structure HTML; no routing, state management, reactive primitives, or the rest of a framework stack. The build outputs everkm-render.js, which renders static HTML once in the sandbox — not runtime SSR. See the official reference in theme-youlog and Theme Development.
Compared to passing template variables layer by layer, componentized TSX stays clearer and scales better for large themes.
See also: Theme Development, Concepts and Architecture, Site Configuration.
6. Build and export: crawl by default, add entry points when needed
Default export:
Start at /index.html → follow inner links → export referenced pages and assets
Unreferenced assets don't land in dist/; put extra files in __everkm/extend/assets/.
If a page isn't reachable by inner-link crawl (e.g. a deep-link-only landing page), use --start-urls to add traversal roots to the export graph.
Hugo, Jekyll, and Zola usually compile the entire content/ tree. We publish what's linked — closer to how knowledge sites work. Need everything? Add entry points via CLI flags.
See also: Export and Publish.
7. Search: Algolia wired into export
config.algolia+push_on_export: true→ reset + push after exportsite/channelseparate multi-site and multi-section indexes- Or run
everkm-publish algoliaon its own
Other SSGs can hook up Algolia too, usually via plugins or custom CI. We made "export → push index" the official happy path.
See also: Embedded Search.
8. Build-time rendering
At generation time you can:
- Highlight code server-side (no browser highlight bundle)
- Render math to inline SVG server-side (no browser math engine)
Toggle via everkm.yaml; other SSGs rely on built-in highlighters or plugins — we folded the switches into site config.
See also: Site Configuration.
9. Toolchain and ecosystem
| Capability | Everkm Publish | Hugo / Jekyll / Zola |
|---|---|---|
| CLI | serve / lint / theme / algolia / web / file-meta | each its own CLI |
| Lint | Front Matter + inner links, --auto-fix available | mostly external tools |
| i18n | language dirs + @i18n: + --lang | Hugo strong; others vary |
| Plugin ecosystem | themes + extend + dCard | Modules / plugins more mature |
| URL stability | stable id + Nginx / Vercel metadata export | mostly hand-written redirects |
| Note interoperability | Abox Note → publish, same pipeline | none |
See also: CLI Quick Reference, Internationalization (i18n), FAQ.
10. When to choose what
| Scenario | Notes |
|---|---|
| Blog, marketing site, docs, knowledge base | Everkm supports all of them; Hugo / Jekyll / Zola can too — the gap is whether the model fits long-lived knowledge |
| Wiki-style inner links + pre-publish lint | First-class in Everkm |
| Titles change often; inbound links must resolve by ID | Everkm + Nginx / Vercel |
| Full-text search on export | Everkm + Algolia |
| Huge mature third-party plugin ecosystems | Hugo / Jekyll have larger pools |
| Already writing in Everkm / Abox Note | Publish directly — no toolchain switch |
Difference at a glance
Everkm Publish is the Markdown static site generator in the Everkm ecosystem: write Markdown, pick a theme, preview locally, export HTML, deploy to any static host.
Like Hugo, Jekyll, and Zola, it needs no database, outputs standard HTML, and runs on CDN / Nginx / Vercel / GitHub Pages. The difference: we optimize for knowledge that accumulates over time, not just "ship a blog post."
One tool, many site shapes
Blogs, book-style docs, knowledge bases / wikis, product sites — one CLI handles them all. Structure comes from folders, not a locked-in blog skeleton. Reference themes youlog (docs / knowledge) and paper (blog) show the range.
URLs decoupled from directories — retitle without breaking links
Disk layout and public URLs can diverge; default URLs carry a stable page ID (slug-id), so IDs survive title / slug changes. Export metadata and generate Nginx / Vercel redirect configs so old inbound links still reach the same content.
Everkm Markdown: a dialect for interconnection
Extensions on standard Markdown: inner links [[...]] (slug, relative path, site-root path, anchors, custom display text, and more), macros, dCard cards, block / inline attributes, chapter TOC via _nav.md. Intra-site navigation uses inner links; lint before publish catches broken and ambiguous links to protect the knowledge graph.
Dual-track themes: Jinja2 and TSX as peers
Themes can use Jinja2 syntax or TSX / JS rendering — equal options, combinable by page complexity. TSX pairs well with SolidJS: lighter than React, just TSX for HTML structure, no routing or state stack; one-shot static HTML at build time. Themes install remotely; sites override via extend/.
Export that follows the knowledge graph — with optional entry points
Default export crawls from the homepage along inner links; unreferenced pages stay out of dist/. Add traversal roots with --start-urls. Assets not linked from body text go in extend/assets/.
Built-in search and build-time rendering
Algolia full-text search can push on export; site / channel isolate multi-site / multi-section indexes. Code highlighting and math rendering can finish at build time, easing the browser load.
Shared roots with Abox Note
Writing in notes and publishing to a site share indexing semantics — not two disconnected pipelines.
General-purpose SSGs offer broader plugin ecosystems and more raw freedom. Everkm Publish is a better fit when you want long-lived Markdown to become static sites that stay organized, interlinked, searchable, and link-stable after retitles.
In one sentence
Everkm Publish builds beautiful static sites like Hugo, Jekyll, and Zola. We go further with multi-shape sites, URL decoupling via folders, stable IDs plus platform redirects, Everkm Markdown inner links and lint, Jinja2 / TSX dual-track themes, crawl-based export, built-in Algolia and build-time rendering, and shared semantics with Abox Note — connecting writing to being found.