Theme Configuration

Paper is a minimal blog theme for everkm-publish, with post as the default template. Site-level configuration is placed under the config node in workspace __everkm/everkm.yaml; URL rules for content directories are set in folders.

Configuration Overview

# __everkm/everkm.yaml

config:
  site: { ... }           # Site basic info
  home: '[[_home]]'       # Homepage hero content
  about: '[[_about]]'     # About page content, or an absolute URL
  posts: { ... }          # Post list pagination and featured tag
  features: { ... }       # Feature toggles
  header_nav: [ ... ]     # Extra header links (after About by default; optional at_before)
  code_highlight: { ... } # Server-side code highlighting
  math_render: { ... }    # Server-side math rendering
  socials: [ ... ]        # Social links (homepage hero & footer)
  share_links: [ ... ]    # Share links on post pages
  copyright: { ... }      # Footer copyright
  body_end_html: "..."    # HTML appended at end of body

folders:
  "/":
    url_slug: posts
    url_id_suffix: true

Site Info site

Example:

config:
  site:
    name: My Blog
    description: A personal blog powered by Paper Theme
    author: Jane Doe
    lang: en
    timezone: UTC

Virtual Pages home / about

Paper uses virtual templates for the homepage and about page. Hero and about body content come from Markdown files referenced by inner links:

Example content layout:

en/
├── _home.md          # Homepage hero (required)
├── _about.md         # About page (required)
├── README.md         # Theme configuration docs
├── CHANGELOG.md      # Changelog
└── posts/
    └── *.md          # Blog posts

Do not create a root index.md. If /index.html resolves to a Markdown file, it renders as a regular post detail page instead of the virtual homepage.

Absolute about URL

To point About to an external page, set about to an http(s):// URL. The header About link opens that URL (new tab, skipping View Transition), and the local /about/ virtual page no longer loads Markdown content.

config:
  about: https://example.com/about

Header Links header_nav

Add custom links in the top nav, mixed with the built-in items (Posts / Tags / About).

Default order:

Search (if enabled) → items with at_before: true → Posts → Tags → About → remaining header_nav → Archives → theme toggle

External links include data-no-vt, and by default also target="_blank" / rel="noopener", so View Transitions do not intercept them.

config:
  header_nav:
    - title: Everkm
      url: https://everkm.com
      at_before: true
    - title: GitHub
      url: https://github.com/everkm/theme-paper
    - title: Docs
      url: https://publish.everkm.com
      new_window: true

title / url also support everkm-publish multilingual maps (resolved by the publish system for the current language):

config:
  header_nav:
    - title:
        _default: Everkm
        zh: 毓知
      url:
        _default: https://everkm.com
        zh: https://everkm.cn/
      at_before: true

Posts posts

Featured posts example:

---
title: My Featured Post
tags:
  - featured
  - release
---

Feature Toggles features

Example:

config:
  features:
    light_and_dark_mode: true
    show_archives: true
    show_back_button: true
    view_transitions: true
    edit_post:
      enabled: false

Search algolia

When configured, the Algolia full-text search component appears in the header (requires plugin-in-search build artifacts).

config:
  algolia:
    app_id: YOUR_APP_ID
    api_key: YOUR_SEARCH_API_KEY
    index_name: your_index
    site: your-site-id

Code Highlighting code_highlight

Paper supports server-side syntax highlighting via everkm-publish:

config:
  code_highlight:
    server: true

When server: true, code blocks are highlighted at build time using syntect themes scoped to .app-prose.

Math Rendering math_render

Server-side math rendering via Typst:

config:
  math_render:
    server: true
    font_size: 14

Use $...$ for inline math and $$...$$ for block math in Markdown.

Social Links socials

Displayed on the homepage hero section and in the footer:

config:
  socials:
    - name: github
      url: https://github.com/everkm/theme-paper
    - name: everkm
      url: https://everkm.com

Supported name values include github, twitter, linkedin, mail, and others mapped to icons in the theme.

Share Links share_links

Optional share links on post detail pages:

config:
  share_links:
    - name: twitter
      url: https://twitter.com/intent/tweet
    - name: facebook
      url: https://www.facebook.com/sharer/sharer.php

Copyright copyright

Footer copyright line, rendered as ©year text. If link is set, the text becomes a hyperlink. When text is omitted, falls back to site.name.

config:
  copyright:
    text: everkm
    link: https://everkm.com

Body End HTML body_end_html

Append custom HTML before each page's </body>, for analytics scripts, live chat widgets, and other third-party integrations.

config:
  body_end_html: |
    <script defer src="https://example.com/analytics.js"></script>

Directory Rules folders

Paper's default theme configuration maps content at / to URLs under /posts/:

folders:
  "/":
    url_slug: posts
    url_id_suffix: true

Site-level folders in __everkm/everkm.yaml override theme defaults.

Virtual Page Routes

Paper provides these virtual pages (no corresponding Markdown file required):

Article Front Matter

Common fields for blog posts:

Example:

---
title: Hello World
description: My first blog post.
created_at: 2026-06-28T10:00:00Z
tags:
  - featured
  - intro
---

If the first h1 in the body matches the Front Matter title, it is automatically hidden during rendering. See Everkm Markdown Format in the demo posts.

Content Markdown Extensions

Paper inherits everkm-publish Markdown extensions. See the demo post Everkm Markdown Format for a full showcase, or the Everkm Markdown guide.

Supported extensions include:

• Inner links [[...]]
• Block attribute sets {.class #id}
• Inline attribute sets on links and images
• Macros (macro/toc, macro/include)
• Highlight text, superscript, subscript
• Definition lists, footnotes, task lists

Reader Settings (Browser-side)

The following are stored locally in the user's browser and are not configured in everkm.yaml:

• Light / dark mode preference (when features.light_and_dark_mode is enabled)

Toggle via the sun / moon button in the header.

Theme Metadata