Custom CSS

A published Project can use one global CSS stylesheet to customize its public site. The stylesheet applies to every published page on both the default Zelares Publish address and a verified custom domain.

Upload, replace, or remove CSS

Open the Project's Publish page.
Open Site settings.
In Site branding, find Custom CSS.
Choose Upload CSS or Replace CSS and select a .css file.
Use Remove CSS whenever you want to return to the default reader design.

A stylesheet must be valid UTF-8 CSS, non-empty, and no larger than 256 KiB. A successful replacement gets a new cache revision, so visitors do not remain pinned to the previous stylesheet.

Use publication-owned images and fonts

Custom CSS can reference images and fonts that you upload to the same publication. Open Custom CSS assets in Site settings, choose a stable handle such as hero-background, upload the file, then copy its CSS reference.

Supported images: PNG, JPEG, and WebP.
Supported fonts: WOFF2.
Maximum: 5 MiB per asset, 20 assets, and 25 MiB total per publication.
Handles use lowercase letters, numbers, and hyphens and remain stable when your Project slug or custom domain changes.

Use the copied logical reference instead of a storage URL:

[data-zelares-publish-root] {
  background-image: url("zelares-asset:hero-background");
  background-size: cover;
}

A publication-owned WOFF2 font can be used with @font-face:

@font-face {
  font-family: "Acme Sans";
  src: url("zelares-asset:acme-sans") format("woff2");
  font-display: swap;
}

[data-zelares-markdown] {
  font-family: "Acme Sans", ui-sans-serif, system-ui, sans-serif;
}

The zelares-asset: reference is the author-facing contract. Zelares resolves it to a revision-qualified same-origin reader URL when the stylesheet is served. Raw R2 keys, bucket URLs, internal API credentials, and Project identifiers are not part of your CSS.

Replacing an asset with the same handle keeps your CSS unchanged but gives visitors a new cache-safe revision. Zelares will not remove an asset while the active stylesheet still references it; remove the reference from Custom CSS first, then remove the asset.

What Custom CSS can and cannot do

Custom CSS is intentionally limited to presentation. Zelares does not accept custom JavaScript, HTML templates, theme ZIP files, or code injection through this feature.

Normal selectors, custom properties, media queries, supports/container queries, pseudo-elements, and animations are supported when the stylesheet passes validation.
@import remains blocked.
Arbitrary external, relative, data:, or blob: resource URLs remain blocked.
image-set(...) and other resource-loading functions outside the documented publication-asset contract remain blocked.
@font-face is allowed only when its resource-bearing source is a publication-owned WOFF2 asset.
Image url(...) values are allowed only through a valid same-publication zelares-asset: image handle.

These limits prevent an authored stylesheet from becoming an arbitrary third-party network or tracking channel. Publication-owned assets are delivered through the published-site origin instead of publisher-selected external hosts.

Use stable Zelares Publish hooks

Target the semantic hooks below when you style major reader regions. They are the supported customization contract and are designed to survive normal component and Tailwind refactors.

[data-zelares-publish-root]
[data-zelares-region="identity"]
[data-zelares-region="search"]
[data-zelares-region="sidebar"]
[data-zelares-region="navigation"]
[data-zelares-region="article"]
[data-zelares-region="outline"]
[data-zelares-region="graph"]
[data-zelares-markdown]

Tailwind utility classes, generated/hashed class names, and incidental nested DOM structure are implementation details and are not stable Custom CSS APIs.

Examples

Adjust the article width and use a system font stack:

[data-zelares-region="article"] {
  max-width: 72rem;
  margin-inline: auto;
}

[data-zelares-markdown] {
  font-family: Inter, ui-sans-serif, system-ui, sans-serif;
  line-height: 1.7;
}

Adjust navigation spacing and add a mobile rule:

[data-zelares-region="navigation"] {
  padding-block: 0.75rem;
}

@media (max-width: 640px) {
  [data-zelares-region="article"] {
    padding-inline: 1rem;
  }
}

Test responsive and accessible behavior

Custom CSS can intentionally override layout, contrast, spacing, and visibility, so test the published site on desktop and mobile and in any light/dark states your design targets. Keep text readable, preserve keyboard/focus visibility, and avoid hiding navigation or content visitors need.

Large images and fonts also affect page weight. Optimize uploaded assets and use font-display deliberately. Custom CSS is never applied to the authenticated Zelares dashboard; if the public design becomes unusable, return to Site settings and remove the stylesheet.

See Publishing a Project for the publication workflow and Custom Domains for using your own hostname.