Themes — Blog-Doc

A Blog-Doc theme is a self-contained folder inside app/themes/ that contains HTML templates, assets, and a JSON manifest. The active theme controls everything the visitor sees — Blog-Doc's admin layer is completely separate.

Theme anatomy

app/themes/my-theme/
├── theme.json           # Required — manifest
├── screenshot.webp      # Required — marketplace/admin preview
├── templates/
│   ├── home.html        # Required
│   ├── 404.html         # Required
│   ├── page.html        # Recommended
│   ├── blog.html        # Required if "blog" feature declared
│   ├── post.html        # Required if "blog" feature declared
│   ├── taxonomy.html    # Required if taxonomy routes desired
│   └── partials/        # Optional shared partials
└── assets/
    ├── css/
    └── js/

Note: the opional partials folder can be at the same level as the templates directory.
A theme can have multiple optional folders like: components, contents, custom, layouts...

IMPORTANT: you can use a content.html template that will render pages and posts. If you use content.html, page.html and post.html are not needed. See Rendering a page or post.

What makes a valid theme

Only two templates are unconditionally required: home.html and 404.html. This minimum allows any kind of site — a landing page, a coming-soon page, a full blog — to be valid.

This requirement is enforced at three points:

ZIP install — validated inside the archive before any files touch disk
Theme activation — checked before writing to active-theme.json
Build pre-flight — checked before _site/ is wiped

page.html is strongly recommended for any site with pages, but its absence is tolerated — the live server returns 404 for page routes and the build reports per-page errors without aborting.

Switching themes

Go to Themes in the admin, click Activate on any installed theme. Blog-Doc immediately serves the new theme on the live site — no restart needed.

Installing themes

Two methods are available from the Themes admin view:

From ZIP — Upload a .zip file using the Install Theme button. The ZIP may contain the theme at its root or inside a single top-level folder.

From the Marketplace — Browse the Marketplace tab, click Install. Blog-Doc downloads and installs the ZIP in one step. If a newer version of an already-installed theme is available, an Update badge appears.

Customizing a Theme

If you want to customize a theme without losing your changes when the original theme is updated, create a copy of the theme instead of editing it directly.

For example, to customize the default theme:

Duplicate the app/themes/default folder.
Rename the copied folder to something like default-copy.
Open app/themes/default-copy/theme.json.
Update the name and id fields to match the new folder name. For example:
```
{
  "id": "default-copy",
  "name": "Default Copy"
}
```

CRITICAL: make sure the id matches the folder name.

If the theme uses prefixed menu names, update those as well. For example:

menus["default-main"]

should become:

menus["default-copy-main"]

That's it. By working with a copied theme, you can safely customize it without your changes being overwritten when the original theme is updated.

Distributing a theme

Zip your theme folder so theme.json is either at the ZIP root or one level deep:

my-theme.zip
└── my-theme/
    ├── theme.json
    └── ...

To list in the marketplace, submit a pull request to the Blog-Doc themes repository on Codeberg. The generate-manifest.js script builds the manifest automatically from the themes/ directory.