Install a theme from the hub: Papermood in five minutes

Papermood is a blog theme in the spirit of hugo-PaperMod. It gives you post cards, a dark-mode toggle, archives, tag pages, and client-side search. It loads no webfonts and no frameworks. The theme is on the hub, together with a starter template named papermood-blog.

This post takes three steps. First, we scaffold the starter template. Second, we install the theme by itself, into a site you already have. Third, we open the theme’s demo site and read it like a textbook. The demo is the best teacher here, because every feature you see has its source one file away. Every transcript below comes from a recorded session.

Step 1: start with the template

You want a Papermood blog and you have no site yet? Then the starter template is your fastest path:

accent init my-blog --template papermood-blog
cd my-blog
accent serve

That is a complete blog. You get a card feed, dark mode, archives, client-side search, and a language switcher. The starter speaks English, German, and French.

The CLI did more than a download. It resolved papermood-blog through the hub registry’s signed index. It then compared the archive with the SHA-256 checksum from the signed manifest. A tampered archive does not install.

The starter ships Papermood in its themes/ directory, and its content already binds to the theme. The rest of this post shows those parts one by one, so you can apply them to your own site.

Step 2: install the theme on an existing site

You do not need the starter. One command adds the theme to any Accent site – no git clone, no ZIP:

accent theme install papermood

Resolving papermood from https://raw.githubusercontent.com/AccentCMS/hub-registry/main...
  papermood@1.0.0 by accentx
Installed theme 'papermood@1.0.0' to ./themes/papermood

Note: this project's active theme is 'simple', so the new theme is not in use yet.
      Set `theme.name: papermood` in config.yaml to activate it.

Activation is one config key, exactly as the note says. In config.yaml:

theme:
  name: papermood
  directory: ./themes

The registry route gives you three things that a manual copy does not:

• Provenance. The index and each version manifest carry a registry signature, and the checksum pins the archive. What lands in themes/ is what the registry entry describes, or the install fails.
• Versions. accent theme outdated tells you when a new release exists. accent theme update moves you forward when you decide.
• Compatibility. Each registry entry declares the Accent versions it supports. Papermood 1.0.0 declares >=0.28.0, and the CLI refuses an install that your binary cannot serve.

One honest step remains on an existing site: your pages must use Papermood’s template names. accent validate is your feedback loop. It names each gap, for example Missing template: "blog" not found in current theme, and it reports a clean site once the names match. The next section shows which names the theme expects.

Step 3: learn from the demo

The theme repository carries a full demo site in its demo/ directory. The live demo is a build of exactly that content. Clone the repository and start the demo locally:

git clone https://github.com/AccentCMS/Papermood
cd Papermood/demo
accent serve --no-tls
# http://127.0.0.1:4477

The demo is small, but it exercises almost every option of the theme and many features of Accent. When you want to know how a page on the demo works, open its source file under demo/content/. Here is the tour.

One config block controls the theme

All theme options live under site.extra.papermood in demo/config.yaml. A trimmed excerpt:

site:
  languages: [en, de, fr]
  extra:
    papermood:
      default_theme: auto
      show_reading_time: true
      show_breadcrumbs: true
      show_toc: true
      show_share_buttons: true
      home_limit: 5
      menu:
        - name: Posts
          url: /posts
        - name: Archives
          url: /archives
        - name: Search
          url: /search
      social:
        - name: github
          url: https://github.com/AccentCMS/accent

The header menu, the social icons, the reading time, the breadcrumbs, the table of contents – each is one key. The demo also sets edit_post, which puts an edit link on each post. That link points at the source file on GitHub. The theme’s README documents the full list.

Pages select their template by name

A theme defines a set of template names. A page selects one with the template: key in its frontmatter. The demo’s four section pages show the whole set:

# content/home/default.md      -> the homepage card and feed
template: home

# content/posts/default.md     -> the card list
template: list

# content/archives/default.md  -> posts by year and month
template: archives

# content/search/default.md    -> client-side search
template: search

These names are the contract between your content and the theme. This is the part accent validate checks for you after a theme switch.

The posts page also declares its collection in frontmatter. It lists its child pages, newest first, five per page:

content:
  items: "@self.children"
  order:
    by: date
    dir: desc
  limit: 5

One model sets site-wide defaults

The demo sets the site-wide author once, in models/default.yaml, not in every post:

name: Post
extends: post
defaults:
  author: Jane Doe

This project model replaces the theme’s default model and extends the theme’s post model. It keeps the same fields and the same validation, and it adds inherited values. A post without an author: line shows “Jane Doe”. The post /posts/writing-fast-sites writes its own author: John Smith line and keeps it. Use the same mechanism for a shared tag, a toc: true, or a cover policy.

The posts show the feature set

Each demo post teaches one area. Read the rendered page and its source side by side.

• Covers. The getting-started post keeps a cover.svg next to its default.md. The frontmatter names it with cover:, cover_alt:, and cover_caption:.
• Components. The components-tour post uses the canonical Accent components: callouts, tabs, accordions, cards, and buttons. The theme dresses them, so your content stays portable between themes.
• Diagrams. The diagrams-tour post writes Mermaid and Svgbob sources in fenced code blocks. The demo sets diagrams.render_mode: server, so each diagram arrives as inline SVG. The page loads no diagram JavaScript.
• Three languages. A translation is one file next to the original: default.md, default.de.md, default.fr.md. The language switcher appears when site.languages lists two or more entries.
• Canonical links. The writing-fast-sites post sets canonical_url:, the right move for a post that first appeared somewhere else.

Where to go next

Start from the template, then make the site yours. When you are not sure how to do something, the demo probably already does it: find the page, open its source, and copy the pattern. The README documents every option, and the hub tracks every release. From an empty directory to a trilingual blog is one accent init – the other five minutes are yours.