Skip to content

Configuration

Jump to bottom
Alejandro edited this page Mar 10, 2025 · 6 revisions

Configuration Reference

Norgolith uses a norgolith.toml file to manage site-wide settings, content schemas, and validation rules. This guide will walk you through all the configuration options and how to use them effectively.

Core Settings

The norgolith.toml file starts with core settings that define your site's basic properties.

Example: Core Settings

# Required
rootUrl = "https://myblog.com"
title = "My Awesome Blog"
language = "en-US"

# Optional yet recommended
author = "Jane Doe"
description = "A blog about Norgolith and static site generation"

Key Fields

  • rootUrl: The base URL for your site (used for generating absolute links in production).
  • title: The title of your site.
  • language: The language code (e.g., en-US).
  • author: The default author for all content.
  • description: A short description of your site.

Commands Configuration

Norgolith lets you set some defaults for the build and serve command options and flags directly from the site configuration file. That way, if the site has many contributors everyone will have the exact same commands setup. These configuration sections will have less priority than CLI passed flags/options but higher priority than the Norgolith defaults.

Example: Automatically Open And Expose Server Page

# Equivalent to `serve --open --host`
[serve]
open = true
host = true

Example: Do Not Minify Assets

# Equivalent to `build --no-minify`
[build]
minify = false # true is the default

Content Schemas

Content schemas allow you to define and enforce metadata structure for your Norg files. This ensures consistency across your content.

Example: Basic Content Schema

[content_schema]
required = ["title", "authors"]

[content_schema.fields.title]
type = "string"
max_length = 80

[content_schema.fields.authors]
type = "array"
min_items = 1

Key Components

  1. Required fields: List of fields that must be present in every Norg file.
  2. Field definitions: Rules for validating individual fields.
  3. Validation Rules: Conditional logic for enforcing additional constraints.

For a detailed guide on content schemas, see the Content Schemas Guide.

Syntax Highlighting

Norgolith supports syntax highlighting for code blocks in your content. You can configure it in the [highlighter] section.

Example: Syntax Highlighting Configuration

[highlighter]
enable = true
engine = "prism"  # or "hljs"

Options

  • enable: Enable or disable syntax highlighting. false by default.
  • engine : Choose between prism (default) or hljs.

RSS

Norgolith supports RSS feeds out-of-the-box for the site posts (any content in the posts/ subdirectory), and is enabled by default. You can configure its behaviour in the [rss] section.

Options

  • enable: Enable or disable RSS generation. true by default.
  • description: RSS feed description. "Latest posts" by default.
  • ttl: Sets the ttl value. 60 by default.
  • image: Sets the image used as the RSS feed favicon. "/assets/favicon.png" by default.

Extra configurations

Norgolith also lets you declare any arbitrary configuration option in an [extra] section. This aims to allow the user to add any extra option to be used in the site templates.

Example: Setting up a repository URL

[extra]
repo_url = "https://github.com/NTBBloodbath/norgolith"

Practical Examples

Example 1: Blog Configuration

title = "My Blog"
language = "en-US"
author = "Jane Doe"

[content_schema]
required = ["title", "author", "created_at"]

[content_schema.fields.title]
type = "string"
max_length = 120

[content_schema.fields.author]
type = "string"

[content_schema.posts.rules]
if = { draft = false }
then = { required = ["publish_date"] }

[highlighter]
enable = true
engine = "prism"

Next Steps

  • Learn how to customize your site's appearance in the Theming Guide.
  • Explore advanced content validation in the Content Schemas Guide.
  • Refer to the [Commands Reference] for all available CLI options.

Clone this wiki locally