Configuration Guide

Shevky reads src/site.json during build startup via config.load() in base/src/config.js. All configuration fields have built-in fallback defaults.

Core Principles

• Keep site.json as valid JSON (no trailing commas, no comments).
• Prefer explicit values over relying solely on defaults.
• Put plugin settings in pluginConfigs, not mixed with global config.
• Put plugin package names in plugins.

High-Impact Sections

identity

Controls canonical site metadata used across meta tags, RSS, sitemap, and robots generation.

Key fields: author, email, url, themeColor, social.

Important: identity.url drives canonical URLs in RSS feeds, sitemap, robots.txt, and OG metadata. Set this to your production URL before building for deployment.

content

Controls language behavior and content listings.

Key fields:

• languages.default, languages.supported, languages.canonical - multi-language routing
• pagination.pageSize, pagination.segment - listing pagination
• collections - custom collection definitions for tags/categories/series

build

Controls output behavior:

• minify - enables HTML/CSS/JS minification
• debug - enables verbose build logging and debug payloads
• pageBufferLimit - pages held in memory before flushing (default: 20)
• outputAliases - post-build path mappings (e.g., ~/404/ -> ~/404.html)

plugins

List plugin package names exactly as installed in npm:

"plugins": [
  "@shevky/plugin-robots-txt",
  "@shevky/plugin-tailwindcss"
]

pluginConfigs

Store plugin runtime settings keyed by the plugin's name field (the runtime name, not the npm package name):

"pluginConfigs": {
  "shevky-rss": { "feedFilename": "feed.xml" },
  "shevky-open-graph": { "siteName": "My Site" }
}

Safe Change Workflow

1. Edit src/site.json.
2. Run npm run build.
3. Inspect dist/ output and build logs.
4. Run npm run dev and verify pages in browser.

Common Mistakes

Related

• Configuration Reference - complete field-by-field reference
• CLI Usage