Configuration

Most site settings live in content/config.yaml. This is the file you edit to change the site title, public URL, languages, theme, pagination, search, assets, and Markdown behavior.

Engine source checkouts also contain a config/ directory for Yii3 configuration, dependency injection, routing, and framework internals. That is for engine development and is covered in Engine.

Site config

content/config.yaml defines site-wide settings used during the build and by the bundled templates.

title: My Site
description: A site built with YiiPress
base_url: https://example.com
languages: [en]
charset: UTF-8

default_author: john-doe
author_pages: false

date_format: Y.m.d
entries_per_page: 10

permalink: /:collection/:slug/

taxonomies:
  - tags
  - categories

highlight_theme: "Solarized (dark)"

image: /assets/og-default.png
twitter: "@example"

robots_txt:
  rules:
    - user_agent: "*"
      disallow:
        - /private/

params:
  github_url: https://github.com/example/mysite

assets:
  fingerprint: true

minify: true

last_updated: true
edit_page: https://github.com/example/mysite/edit/main/content/{path}
report_issue: https://github.com/example/mysite/issues/new?title=Docs:%20{title}&body={url}

editor: code

Fields

• title — site title, used in layouts, feeds, and meta tags
• description — site description for meta tags and feeds
• base_url — full base URL including scheme (used in feeds, sitemaps, canonical URLs)
• languages — site language codes. The first language is the default language (e.g., [en], [en, ru])
• charset — character encoding (default: UTF-8)
• default_author — author slug (referencing a file in content/authors/), used when entries have no explicit authors field
• author_pages — set to true to generate /authors/ and /authors/:slug/ pages and link known entry authors to them (default: false)
• date_format — PHP date format string for displaying dates in templates (e.g., Y.m.d for "2026.03.23", F j, Y for "March 23, 2026"). See PHP date format for all available format characters
• entries_per_page — default pagination size for taxonomy term pages and collection listings (overridden by collection _collection.yaml for collection listings)
• permalink — default permalink pattern (overridden by collection or entry)
• taxonomies — list of enabled taxonomy types
• theme — default theme name for the site (see Templates)
• highlight_theme — built-in syntect theme used for fenced code block highlighting. Defaults to InspiredGitHub. Available built-in themes include InspiredGitHub, Solarized (dark), Solarized (light), base16-ocean.dark, base16-ocean.light, base16-eighties.dark, and base16-mocha.dark
• image — default Open Graph image URL (absolute, or root-relative path resolved against base_url); used as fallback when an entry has no image front matter field
• twitter — Twitter/X account handle (e.g., @example) added to twitter:site meta tag on all pages
• robots_txt — robots.txt generation settings (see below)
• toc — generate a table of contents from headings (default: true); set to false to disable globally. When enabled, heading tags receive id attributes and a $toc variable is passed to templates
• search — opt-in client-side search (see below)
• related — opt-in related content suggestions (see below)
• processors — project-level content processor loading (see Plugins)
• minify — minify generated HTML output and copied CSS/JavaScript assets (default: true); set to false to keep rendered template and asset whitespace
• last_updated — set to true to show each entry source file's last modification time below its content (default: false)
• edit_page — URL template for an optional "Edit this page" link below entry content (see below)
• report_issue — URL template for an optional "Report an issue" link below entry content (see below)
• assets — asset pipeline settings (see below)
• editor — command used by yiipress serve to open the current markdown source from the preview overlay. If omitted, YiiPress uses the platform default opener (open on macOS, xdg-open on Linux, and start through cmd on Windows)
• params — arbitrary key-value pairs for use in templates
• markdown — markdown extensions configuration (see below)

If content/config.yaml is missing required values or is not valid YAML, yiipress build
prints the configuration file, the problem, and a suggested fix. For example, a missing
or empty languages option is reported with a languages: [en] example instead of a PHP
stack trace.

Search

Client-side search is opt-in. Enable it in content/config.yaml:

search:
  full_text: false   # index full body text (default: false, summary+tags only)
  results: 10        # max results shown (default: 10)

When enabled, the build generates a search-index.json file in the output directory and injects a search button into the site header. Clicking the button (or pressing Ctrl+K / ⌘K) opens a search modal with fuzzy matching. No external dependencies — everything is hand-rolled JavaScript.

The full_text option controls how much content is indexed:

• false — indexes title, summary, and tags (smaller index, faster)
• true — additionally indexes the full body text (larger index, more thorough results)

Related content

Related content suggestions are opt-in. Enable in content/config.yaml:

related: true

Or configure:

related:
  limit: 5                     # max related entries per page (default: 5)
  tag_weight: 2                # score per shared tag (default: 2)
  category_weight: 3           # score per shared category (default: 3)
  same_collection_only: true   # restrict suggestions to the same collection (default: true)

Templates receive a $related variable (list of YiiPress\Content\Model\RelatedEntry) ordered
by relevance. See plugins.md for details.

Page actions

Page action links are optional. Enable a GitHub-style edit link with edit_page:

edit_page: https://github.com/example/mysite/edit/main/content/{path}
report_issue: https://github.com/example/mysite/issues/new?title=Docs:%20{title}&body={url}

Supported placeholders are:

• {path} — source path relative to the content directory, URL-encoded with / preserved
• {title} — entry title, URL-encoded
• {permalink} — root-relative permalink, URL-encoded with / preserved
• {url} — absolute page URL resolved from base_url, URL-encoded

Multilingual support

Declare site languages in content/config.yaml. The first language is the default:

languages: [en, ru]

Entries are tagged with the language front matter field. Entries whose language
differs from the first configured site language get their permalink prefixed automatically (e.g.,
/ru/blog/hello/); default-language entries keep the plain URL (/blog/hello/).
Explicit permalink: overrides in front matter bypass the prefix. languages is required
and must contain at least one language code.

Group translations of the same article using a shared translation_key:

---
title: Hello
language: ru
translation_key: hello
---

When translation_key is absent, translations are grouped by slug within the same
collection. All variants of an entry expose each other as alternates:

• $translations — list of YiiPress\Content\Model\Translation (language, permalink, title)
  available to templates for rendering a language switcher.
• $language — effective language of the current entry; the bundled theme uses it for
  <html lang="…">.
• hreflang alternate <link> tags are emitted in the head automatically, including
  x-default pointing to the default-language version.

The bundled minimal theme localizes its built-in UI labels (search, archive, related
posts, 404 page, redirects, and similar chrome) from theme translation files in
themes/minimal/translation/, for example en.yaml and ru.yaml.
The current entry language does not drive the UI language. The bundled minimal theme renders UI chrome from the site's default language and exposes a header selector that remembers the user's choice in localStorage, similar to the theme toggle. Language names in that selector stay in their native form instead of being translated into the current UI language.
If a theme omits a UI key for the current UI language, YiiPress falls back to the site's default language,
then to English, and only then to the key name itself, so theme translation files should define
the full UI vocabulary they need.
Archive month names in the bundled minimal theme come from theme translation keys month.01 through month.12, with built-in English and Russian fallbacks. Language selector labels use language.<code> translation keys when present and otherwise fall back to built-in names or the uppercased language code. YiiPress does not require the PHP intl extension for this UI text.

Syntax highlighting

Syntax highlighting uses built-in syntect themes and renders
inline styles during build. To switch the theme globally:

highlight_theme: "Solarized (dark)"

If highlight_theme is omitted, YiiPress uses InspiredGitHub.

Assets

Asset fingerprinting is enabled by default. Disable it in content/config.yaml if needed:

assets:
  fingerprint: false

When enabled, YiiPress renames copied assets to include a content hash, for example:

• assets/themes/minimal/style.css → assets/themes/minimal/style.4f8d2d5b1c3a.css
• blog/assets/hero.png → blog/assets/hero.a12b34c56d78.png

Built-in templates use the fingerprinted URLs automatically, and existing hardcoded src / href
asset references in rendered HTML are rewritten during build so custom themes continue to work.
Root-relative local asset references are treated as YiiPress site-root paths and emitted relative to
the current output page, so they remain valid when base_url contains a deployment path.

Output minification

Generated HTML pages and copied CSS/JavaScript assets are minified by default:

minify: true

Set minify: false to keep template indentation and line breaks in generated *.html files
and to copy *.css / *.js assets without rewriting them. Whitespace inside pre, textarea,
script, and style elements is preserved either way.

Editor

During yiipress serve, HTML pages get a fixed bottom-right Edit button. Clicking it asks the preview server to open the markdown source file that produced the current page.

Configure the editor command in content/config.yaml:

editor: code

If the command does not contain {file}, YiiPress appends the source file path. For commands that need the path in a specific position, use {file}:

editor: "code --goto {file}"

The same command can be written as a list to avoid shell-style quoting:

editor:
  - code
  - --goto
  - "{file}"

robots.txt

A robots.txt file is generated by default with a permissive rule (allow all crawlers) and a Sitemap: pointer. Configure custom rules via robots_txt:

robots_txt:
  generate: true   # set to false to disable robots.txt generation entirely
  rules:
    - user_agent: "*"
      disallow:
        - /private/
        - /admin/
      crawl_delay: 5
    - user_agent: "Bingbot"
      allow:
        - /
      disallow: []

Each rule supports:

• user_agent — crawler name (default: *)
• allow — list of allowed paths
• disallow — list of disallowed paths
• crawl_delay — seconds between requests (integer)

Usage in templates

Templates receive focused variables for the page they render, such as $siteTitle, $entryTitle, $content, $date, $author, and $collection. See Templates for the full variable list.

Markdown settings

The markdown section controls which Markdown extensions are enabled. All options are boolean.

markdown:
  tables: true
  strikethrough: true
  tasklists: true
  url_autolinks: true
  email_autolinks: true
  www_autolinks: true
  collapse_whitespace: true
  latex_math: false
  wikilinks: false
  underline: false
  no_html_blocks: false
  no_html_spans: false
  permissive_atx_headers: false
  no_indented_code_blocks: false
  hard_soft_breaks: true

• tables — GitHub-style tables (default: true)
• strikethrough — strikethrough with ~text~ (default: true)
• tasklists — GitHub-style task lists (default: true)
• url_autolinks — recognize URLs as auto-links even without <> (default: true)
• email_autolinks — recognize e-mails as auto-links even without <> and mailto: (default: true)
• www_autolinks — enable WWW auto-links (even without any scheme prefix, if they begin with 'www.') (default: true)
• collapse_whitespace — collapse non-trivial whitespace into single space (default: true)
• latex_math — enable LaTeX math spans $...$ and $$...$$ (default: false). Pages that contain math automatically include KaTeX CSS/JS and the shipped YiiPress math enhancer script.
• wikilinks — enable wiki-style links [[link]] (default: false)
• underline — underscore _ denotes underline instead of emphasis (default: false)
• no_html_blocks — disable raw HTML blocks (default: false)
• no_html_spans — disable inline raw HTML (default: false)
• permissive_atx_headers — do not require space in ATX headers ( ###header ) (default: false)
• no_indented_code_blocks — disable indented code blocks (only fenced code works) (default: false)
• hard_soft_breaks — force all soft breaks to act as hard breaks (default: true)

If the markdown section is omitted, all defaults apply.

Defaults and overrides

Collection _collection.yaml fields override content config defaults:

• Collection entries_per_page overrides config.yamlentries_per_page
• Collection permalink overrides config.yamlpermalink
• Collection feed_limit controls how many entries are rendered into that collection's RSS, Atom, and JSON Feed files (20 by default, 0 for unlimited). Site-wide /feed.xml, /rss.xml, and /feed.json include entries from all feed-enabled collections and use the default limit.
• Entry permalink overrides collection permalink

Resolution order: entry → collection → content config → engine defaults.