Configuration

Shizuka loads JSONC configuration from shizuka.jsonc by default.

Configs should include the version of shizuka they are using. Shizuka automatically rejects configs whose version is incompatible with the running binary according to semver.

JSON configs may include $schema for editor support:

{
  "$schema": "https://raw.githubusercontent.com/olimci/shizuka/refs/heads/main/_assets/config.schema.json",
  "version": "0.1.0",
  "site": {
    "title": "My site",
    "description": "A small static site.",
    "url": "https://example.com/"
  }
}

A URL is required, to generate canonical URLs, and must start with http:// or https://.

Build Configuration

minifier is optional. When present, rendered HTML and copied CSS, JavaScript, and HTML assets are minified where supported.

Patterns use / separators, support **, and are matched against generated target paths. A pattern without / matches basenames, a leading / anchors at the output root, and a trailing / matches a directory and its descendants.

Content Defaults

You can set default values for content frontmatter, in content.defaults:

The defaults object supports frontmatter fields that are reasonable to apply across pages:

title, description, tags, created, updated, template, featured, draft, weight, rss, sitemap, robots

It does not include route or identity fields such as section, and it does not include map fields such as params or headers.

Section-specific defaults replace the global defaults object when the resolved section has a matching sections entry. Page frontmatter is decoded into the selected defaults, so page values always win, including explicit zero values such as false, 0, empty strings, and empty lists.

Markdown Configuration

Markdown is configured with Shizuka feature flags:

highlighting, when present, supports style, line_numbers, and classes. Highlighted code uses Chroma inline styles by default. Set classes to true to emit Chroma classes and provide CSS from your static assets. Check out the Chroma Style Gallery to see available styles.

Parser Configuration

Generated or explicit heading IDs are exposed to templates through .Page.ToC.

Renderer Configuration

Extra Outputs

Shizuka has several extra output artefacts available, including:

Options

The meta artefact emits HTML debug output at path. Set json to true to also emit the same site/config payload as formatted JSON at _shizuka.json.

Example Config

{
  "$schema": "https://raw.githubusercontent.com/olimci/shizuka/refs/heads/main/_assets/config.schema.json",
  "version": "0.1.0",
  "site": {
    "title": "My site",
    "description": "A small static site.",
    "url": "https://example.com/",
    "params": {}
  },
  "paths": {
    "output": "dist",
    "content": "content",
    "static": "static",
    "templates": "templates"
  },
  "build": {
    "minifier": {
      "whitelist": ["**/*.html", "**/*.css", "**/*.js"],
      "blacklist": ["vendor/**"]
    }
  },
  "content": {
    "defaults": {
      "section": "pages",
      "global": {
        "template": "page"
      },
      "sections": {
        "posts": {
          "template": "post",
          "sitemap": {
            "include": true,
            "changefreq": "never",
            "priority": 0.6
          },
          "rss": {
            "include": true
          }
        }
      }
    },
    "markdown": {
      "tables": true,
      "strikethrough": true,
      "task_list": true,
      "definition_list": true,
      "footnotes": true,
      "linkify": true,
      "typographer": true,
      "wikilinks": false,
      "components": false,
      "highlighting": null,
      "parser": {
        "auto_heading_id": false,
        "attribute": false
      },
      "renderer": {
        "hardbreaks": false,
        "xhtml": false
      }
    },
    "git": {
      "backfill": true
    }
  },
  "artefacts": {
    "headers": {
      "path": "_headers",
      "values": {
        "/": {
          "X-Frame-Options": "DENY"
        }
      }
    },
    "redirects": {
      "path": "_redirects",
      "entries": [
        {
          "from": "/old",
          "to": "/new",
          "status": 301
        }
      ]
    },
    "rss": {
      "path": "rss.xml",
      "sections": ["posts"],
      "limit": 50,
      "include_drafts": false
    },
    "sitemap": {
      "path": "sitemap.xml",
      "include_drafts": false
    },
    "robots": {
      "path": "robots.txt",
      "include_sitemap": true,
      "include_drafts": false,
      "sitemaps": [],
      "groups": [
        {
          "user_agents": ["*"],
          "allow": ["/"],
          "disallow": ["/private/"]
        }
      ]
    },
    "not_found": {
      "path": "404.html",
      "template": ""
    },
    "meta": {
      "path": "_shizuka/index.html",
      "json": false
    }
  }
}