A theme changes how the site is presented while article and page files keep their content. Start with a local theme, get the shared layout right, and check the same content in both wide and narrow windows.

Create and select a theme

npx edgepress theme list
npx edgepress theme create my-theme
npx edgepress theme use my-theme
npm run dev

theme create copies the default layout scaffold and creates an empty assets/style.css for your styles. It does not create a finished visual design. Select an installed theme with theme use, or install a published theme package with npx edgepress theme install <package>. If the site has a root theme: entry in config.yml, that selects the theme; older projects can use paths.theme in the build configuration.

themes/my-theme/
  theme.json
  layouts/layout.html
  layouts/partials/head.html
  layouts/partials/header.html
  layouts/partials/footer.html
  assets/style.css
  assets/data-saver-theme.css
  package.json
  README.md

Build the shared layout first

<html lang="{{site.language}}">
<head>{{> head}}</head>
<body>
  <a class="skip-link" href="#main">{{site.skipToContent}}</a>
  {{> header}}
  <main id="main">{{{page.content}}}</main>
  {{> footer}}
  <script defer src="/edgepress/language-select.7d871c5f0e7a9327.js"></script>
</body>
</html>

Templates are HTML partials. {{page.title}} and other ordinary placeholders are escaped; {{{page.content}}} inserts the framework's already-rendered content. Keep the head partial, consent support, language navigation and the framework's local runtime. A theme should not copy those browser implementations.

Preserve the skip link, one main landmark, visible keyboard focus and one page-level H1. Use a full-height body and a growing main so the footer stays at the bottom on short pages. Test long titles, articles, project lists, empty states and the localized 404 page.

Style real page elements

Use assets/style.css for your palette, typography, spacing and responsive rules. Built-in font variables are --edgepress-font-sans, --edgepress-font-serif and --edgepress-font-mono; font assets remain local. Style the page-builder rows and cells, article body, navigation, tables, code, project recordings and notices. Avoid fixed desktop widths that overflow on phones.

Keep editorial images in content/assets/ and only theme-owned decoration in the theme assets. Local CSS and JavaScript and their dependencies receive content hashes at build time. The output preserves one-year immutable caching for those hashes while HTML and unversioned metadata revalidate.

Add behavior without changing the publishing model

Small local theme interactions can live in assets/. Build-time plugins belong in the paths listed in edgepress.config.mjs; they are trusted Node code. Optional external services belong in the flat plugins.consent.services list in config.yml, with a name, purpose, data disclosure and current service consent before requests. Keep comments in iask rather than building a separate comment system into the theme.

Images, media galleries and document elements use the existing reusable viewers. Preserve their focus handling, consent gates and lazy loading. Do not copy a player or document engine to adjust its colors.

Check the theme with actual content

Run npm run build and npm run check, then inspect light and dark palettes, keyboard navigation, translated menus and mobile layouts. Test an article with code and tables, a two-column page, a recording with its seek bar and a document preview. A successful build checks structure; you still need to look at the resulting page.

A lightweight text variant is optional. If you add one, test its actual request behavior as well as its layout: text-view configuration.

Writing and Pages · Theme element reference