Norgolith

https://norgolith.dev
Admin
Norgolith is a project providing documentation on various aspects including commands, configuration,...
Tokens:9,732
Snippets:169
Trust Score:7.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Rust via Rustup

Source: https://norgolith.dev/docs/contributing

Downloads and installs the Rust toolchain using the official script.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Start the development server

Source: https://norgolith.dev/docs/getting-started

Launches a local server with live-reloading capabilities.

```bash
lith dev --open
```

--------------------------------

### Start development server

Source: https://norgolith.dev/docs/getting-started

Command to run the local development server for previewing changes.

```bash
lith dev
```

--------------------------------

### Install Norgolith MCP Server

Source: https://norgolith.dev/docs/mcp

Methods to install the MCP server from crates.io, source, or using Nix.

```shell
cargo install norgolith-mcp
```

```shell
git clone https://github.com/norgolith/core
cd norgolith
cargo build --release --manifest-path norgolith-mcp/Cargo.toml
```

```shell
nix build .#norgolith-mcp
```

--------------------------------

### Install Norgolith via Cargo

Source: https://norgolith.dev/docs/installation

Installs the latest development version from the repository and verifies the installation.

```bash
# Install from the repository
cargo install --git https://github.com/norgolith/core --locked

# Verify the installation
lith --version
```

--------------------------------

### Start Development Server with lith dev

Source: https://norgolith.dev/docs/commands

Commands to launch the development server with specific port, host, and draft content settings.

```bash
lith dev [OPTIONS]
```

```bash
-p, --port <PORT>    Set server port (default: 3030)
-e, --host           Expose server to LAN
-o, --open           Open browser automatically
--drafts             Include draft content (default)
--no-drafts          Exclude draft content
```

```bash
# Start server on port 8080 and open browser
lith dev --port 8080 --open

# Serve excluding drafts
lith dev --no-drafts
```

--------------------------------

### Define Theme Metadata

Source: https://norgolith.dev/docs/theming

Example configuration for the theme.toml file.

```toml
name = "Norgolith Pico"
author = "NTBBloodbath"
description = "PicoCSS for Norgolith"
version = "0.1.0"
license = "MIT"
repository = "github:NTBBloodbath/norgolith-pico-theme"
```

--------------------------------

### Install Norgolith via Nix Shell

Source: https://norgolith.dev/docs/installation

Temporarily installs Norgolith using the nix-shell command.

```bash
nix-shell -p norgolith
```

--------------------------------

### Conventional Commit examples

Source: https://norgolith.dev/docs/contributing

Examples of valid commit messages following the Conventional Commits specification.

```text
feat(templates): add support for dark mode

fix(converter): handle edge case in norg syntax

docs: update contributing guide
```

--------------------------------

### lith dev

Source: https://norgolith.dev/docs/commands

Starts a local development server for the Norgolith project.

```APIDOC
## lith dev

### Description
Start development server.

### Usage
`lith dev [OPTIONS]`

### Options
- **-p, --port <PORT>** - Set server port (default: 3030)
- **-e, --host** - Expose server to LAN
- **-o, --open** - Open browser automatically
- **--drafts** - Include draft content (default)
- **--no-drafts** - Exclude draft content
```

--------------------------------

### Pull a theme from GitHub

Source: https://norgolith.dev/docs/getting-started

Use this command to download and install a theme directly from a GitHub repository.

```bash
lith theme pull github:NTBBloodbath/norgolith-pico-theme
```

--------------------------------

### MCP Tool Interaction Examples

Source: https://norgolith.dev/docs/mcp

JSON structures representing the input and output for the search_docs and read_source tools.

```json
{
  "query": "plugin manifest",
  "results": [
    { "name": "docs-plugins", "uri": "norgolith://docs/plugins", "snippet": "..." }
  ]
}
```

```json
{
  "path": "sdk/src/lib.rs",
  "content": "use serde::{Serialize, Deserialize};..."
}
```

--------------------------------

### Install Norgolith via AUR

Source: https://norgolith.dev/docs/installation

Installs the latest development version on Arch Linux using the paru package manager.

```bash
paru -S norgolith-git
```

--------------------------------

### Manage Themes with lith theme

Source: https://norgolith.dev/docs/commands

Commands for installing, updating, and managing site themes.

```bash
pull <REPO>     Install theme from repository
update          Update current theme
rollback        Restore previous theme version
init            Create new theme structure
info            Show theme information
```

```bash
lith theme pull [OPTIONS] <REPO> [VERSION]
```

```bash
--pin   Pin to current major version
```

```bash
lith theme update [OPTIONS]
```

```bash
lith theme rollback [OPTIONS]
```

```bash
lith theme init [OPTIONS]
```

```bash
lith theme info [OPTIONS]
```

```bash
# Install theme from GitHub
lith theme pull github:NTBBloodbath/norgolith-pico-theme

# Update theme while keeping backups
lith theme update

# Create new theme scaffold
lith theme init my-theme
```

--------------------------------

### lith theme

Source: https://norgolith.dev/docs/commands

Commands for managing installed themes.

```APIDOC
## lith theme

### Description
Manage installed theme.

### Subcommands
- **pull <REPO>** - Install theme from repository
- **update** - Update current theme
- **rollback** - Restore previous theme version
- **init** - Create new theme structure
- **info** - Show theme information
```

--------------------------------

### Manage Norgolith Themes via CLI

Source: https://norgolith.dev/docs/theming

Commands for pulling, updating, rolling back, and retrieving information about installed themes.

```bash
lith theme pull github:NTBBloodbath/norgolith-pico-theme
```

```bash
lith theme update
```

```bash
lith theme rollback
```

```bash
lith theme info
```

--------------------------------

### View Norgolith validation error format

Source: https://norgolith.dev/docs/content-schemas

Example of the standard error output displayed during site builds or development server execution.

```text
11:58 AM 2025-03-01 ERROR Validation failed for '/home/amartin/Develop/Rust/norgolith/my-site/content/index.norg'
→ Schema applied: 'index'
→ Constraint violation for field 'title': Exceeds max length 12
```

--------------------------------

### Define Norg document metadata

Source: https://norgolith.dev/docs/getting-started

Example of document metadata and content structure within a .norg file.

```norg
@document.meta
title: First Post
description: My first post using Norgolith!
authors: [
  amartin
]
categories: [
  posts
]
created: 2025-03-01T10:47:42-04:00
updated: 2025-03-01T10:47:42-04:00
draft: true
version: 1.1.1
\@end

* First Post
  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
  labore et dolore magna aliqua. Lobortis scelerisque fermentum dui faucibus in ornare.
```

--------------------------------

### Initialize a new Norgolith site

Source: https://norgolith.dev/docs/getting-started

Creates a new directory with the necessary project structure and metadata prompts.

```bash
lith init mysite
```

--------------------------------

### Initialize a New Theme

Source: https://norgolith.dev/docs/theming

Commands and resulting directory structure for creating a new theme.

```bash
lith theme init
```

```text
theme/
├── assets/
├── templates/
└── theme.toml
```

--------------------------------

### Build and Test with Nix

Source: https://norgolith.dev/docs/contributing

Compiles the project and runs tests using the recommended Nix environment.

```bash
cargo build
cargo nextest run --test-threads=1
```

--------------------------------

### Initialize Project with lith init

Source: https://norgolith.dev/docs/commands

Commands to initialize a new Norgolith site with or without interactive prompts.

```bash
lith init [OPTIONS] [NAME]
```

```bash
--prompt      Prompt for site metadata (title, author, etc.)
--no-prompt   Skip metadata prompts (uses sane defaults)
```

```bash
# Interactive setup (default)
lith init my-blog --prompt

# Quick setup with sane defaults, e.g. `en-US` as the language code
lith init my-site --no-prompt
```

--------------------------------

### Preview Build with lith preview

Source: https://norgolith.dev/docs/commands

Command to serve the current build output for local previewing.

```bash
lith preview [OPTIONS]
```

```bash
-p, --port <PORT>    Set server port (default: 3030)
-e, --host           Expose server to LAN
-o, --open           Open browser automatically
```

```bash
lith preview --open
```

--------------------------------

### Build Production Site with lith build

Source: https://norgolith.dev/docs/commands

Command to generate a production-ready site with optional minification.

```bash
lith build [OPTIONS]
```

```bash
-m, --minify   Minify HTML/CSS/JS output (default)
```

```bash
# Build with minification
lith build --minify
```

--------------------------------

### Configure Blog Settings and Content Schema

Source: https://norgolith.dev/docs/configuration

Set global blog metadata, define content validation rules, and configure the syntax highlighter.

```toml
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"
```

--------------------------------

### lith init

Source: https://norgolith.dev/docs/commands

Initializes a new Norgolith site in the current or specified directory.

```APIDOC
## lith init

### Description
Initialize a new Norgolith site.

### Usage
`lith init [OPTIONS] [NAME]`

### Options
- **--prompt** - Prompt for site metadata (title, author, etc.)
- **--no-prompt** - Skip metadata prompts (uses sane defaults)
```

--------------------------------

### Build site for production

Source: https://norgolith.dev/docs/getting-started

Generates minified static HTML files in the public directory.

```bash
lith build --minify
```

--------------------------------

### View project directory structure

Source: https://norgolith.dev/docs/getting-started

Displays the standard file layout for a newly initialized Norgolith site.

```text
mysite/
├── content/         # Norg documents go here
├── static/          # Static assets (CSS, JS, images)
├── templates/       # Tera templates for HTML generation
├── theme/           # Active theme files
└── norgolith.toml   # Site configuration
```

--------------------------------

### Enter Nix Development Shell

Source: https://norgolith.dev/docs/contributing

Activates the reproducible development environment provided by the Nix flake.

```bash
nix develop
```

--------------------------------

### Global CLI Options

Source: https://norgolith.dev/docs/commands

Standard options available for all Norgolith commands.

```bash
-d, --dir <PROJECT_DIR>  Operate on project in specified directory
-h, --help               Show command help
-v, --version            Show Norgolith version
```

--------------------------------

### Enable Nix Flakes

Source: https://norgolith.dev/docs/contributing

Configures Nix to support experimental flake features.

```bash
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
```

--------------------------------

### Configure Plugin Settings

Source: https://norgolith.dev/docs/configuration

Define per-plugin configuration in the norgolith.toml file using the [plugins.<name>] section.

```toml
[plugins.norgolith-tree-sitter-highlight]
theme = "dark"
languages = ["rust", "python"]

[plugins.watermark]
text = "Generated by Norgolith"
```

--------------------------------

### Configure SEO and robots.txt settings

Source: https://norgolith.dev/docs/configuration

Manage metadata generation for SEO and define crawling rules via robots.txt presets or custom files.

```toml
[seo]
sitemap = true
open_graph = true
default_image = "/assets/og-default.png"
twitter_site = "@myhandle"
twitter_creator = "@myhandle"

[robots]
enable = true
preset = "no_llms"  # "allow_all", "no_llms", or "block_all"
custom_file = "robots.custom.txt"
```

--------------------------------

### Create new content

Source: https://norgolith.dev/docs/getting-started

Command to generate additional pages and assets for the site.

```bash
lith new
```

--------------------------------

### lith build

Source: https://norgolith.dev/docs/commands

Builds the production-ready version of the site.

```APIDOC
## lith build

### Description
Build production-ready site.

### Usage
`lith build [OPTIONS]`

### Options
- **-m, --minify** - Minify HTML/CSS/JS output (default)
```

--------------------------------

### Build and Test Manually

Source: https://norgolith.dev/docs/contributing

Compiles the project and runs tests using standard Cargo commands.

```bash
cargo build
# 'cargo nextest run --test-threads=1' if you've installed cargo-nextest
cargo test -- --test-threads=1
```

--------------------------------

### Create Content with lith new

Source: https://norgolith.dev/docs/commands

Commands to generate new assets or content files, optionally opening them in the system editor.

```bash
lith new [OPTIONS] [NAME]
```

```bash
-k, --kind <KIND>   Asset type (norg|css|js) [default: norg]
-o, --open          Open file in system editor
```

```bash
# Create new blog post
lith new -k norg posts/2023/my-post.norg

# Create CSS file and open it
lith new -k css styles.css --open
```

--------------------------------

### Clone the Repository

Source: https://norgolith.dev/docs/contributing

Downloads the Norgolith source code and enters the project directory.

```bash
git clone https://github.com/norgolith/core.git \
&& cd norgolith
```

--------------------------------

### Define core site settings

Source: https://norgolith.dev/docs/configuration

Sets essential site properties like the root URL, title, and language in the norgolith.toml file.

```toml
# 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"
```

--------------------------------

### Configure syntax highlighting

Source: https://norgolith.dev/docs/configuration

Enable and select the syntax highlighting engine for code blocks.

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

--------------------------------

### Create a feature branch

Source: https://norgolith.dev/docs/contributing

Use this command to create and switch to a new feature branch.

```bash
git checkout -b feat/your-feature-name
```

--------------------------------

### Use Built-in and Custom Functions

Source: https://norgolith.dev/docs/templating

Utilize Tera functions like now() for dates and custom functions like generate_toc() for content navigation.

```html
<footer>
  <span>Copyright &copy; {{ now() | date(format="%Y") }}</span>
</footer>
```

```html
<!-- Usage example -->
{% if metadata.toc %}
  <div>
    {% set toc_html = generate_toc(toc=metadata.toc, list_type="ol") %}
    <h3>
      Table of Contents
    </h3>
    <nav>
      {{ toc_html | safe }}
    </nav>
  </div>
{% endif %}
```

--------------------------------

### Configure development server defaults

Source: https://norgolith.dev/docs/configuration

Sets default flags for the dev command, such as automatically opening the browser and exposing the host.

```toml
# Equivalent to `dev --open --host`
[dev]
open = true
host = true
```

--------------------------------

### Configure MCP Client

Source: https://norgolith.dev/docs/mcp

Configuration formats for different MCP clients to integrate the Norgolith server.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "norgolith": {
      "type": "local",
      "command": "norgolith-mcp",
      "enabled": true
    }
  }
}
```

```json
{
  "mcpServers": {
    "norgolith": {
      "command": ["norgolith-mcp"]
    }
  }
}
```

```json
{
  "mcp": {
    "norgolith": {
      "type": "local",
      "command": ["norgolith-mcp"],
      "enable": true
    }
  }
}
```

--------------------------------

### lith preview

Source: https://norgolith.dev/docs/commands

Previews the site based on the build result.

```APIDOC
## lith preview

### Description
Preview from build result.

### Usage
`lith preview [OPTIONS]`

### Options
- **-p, --port <PORT>** - Set server port (default: 3030)
- **-e, --host** - Expose server to LAN
- **-o, --open** - Open browser automatically
```

--------------------------------

### Basic Post Template Structure

Source: https://norgolith.dev/docs/templating

A complete HTML document structure using Tera syntax to inject metadata and content.

```html
<!-- templates/post.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>{{ metadata.title }}</title>
  </head>
  <body>
    <h1>{{ metadata.title }}</h1>
    <div class="content">{{ content }}</div>
  </body>
</html>
```

--------------------------------

### Format Rust code

Source: https://norgolith.dev/docs/contributing

Run this command to format your Rust code according to project standards.

```bash
cargo fmt
```

--------------------------------

### Blog Post Template

Source: https://norgolith.dev/docs/templating

A template for rendering individual blog posts using metadata and content blocks.

```Tera
<!-- templates/post.html -->
{% extends "base.html" %}

{% block content %}
<article>
  <h1>{{ metadata.title }}</h1>
  <p class="meta">By {{ metadata.authors | join(sep=", ") }} on {{ metadata.created | date(format="%Y-%m-%d") }}</p>
  <div class="content">{{ content }}</div>
  <ul class="categories">
  {% for category in metadata.categories %}
    <li>{{ category }}</li>
  {% endfor %}
  </ul>
</article>
{% endblock %}
```

--------------------------------

### Configure build command defaults

Source: https://norgolith.dev/docs/configuration

Sets default flags for the build command, such as disabling asset minification.

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

--------------------------------

### Homepage Template

Source: https://norgolith.dev/docs/templating

A template for listing multiple blog posts on the index page.

```Tera
<!-- templates/index.html -->
{% extends "base.html" %}

{% block content %}
<section class="posts">
  {% for post in posts %}
    <article>
      <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
      <p class="meta">By {{ post.authors | join(sep=", ") }} on {{ post.created | date(format="%Y-%m-%d") }}</p>
      <span class="description">{{ post.description }}</span>
    </article>
  {% endfor %}
</section>
{% endblock %}
```

--------------------------------

### Define Project Documentation Schema

Source: https://norgolith.dev/docs/content-schemas

Configures documentation schema with semantic versioning patterns and conditional reviewer requirements.

```toml
[content_schema]
required = ["title", "version"]

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

[content_schema.fields.project_version]
type = "string"
pattern = '^\d+\.\d+\.\d+$'  # Semantic versioning

[content_schema.docs.rules]
if = { status = "published" }
then = { required = ["reviewer"] }
```

--------------------------------

### Configure Path-Based Schema Inheritance

Source: https://norgolith.dev/docs/content-schemas

Extends schema requirements across nested content paths.

```toml
# Global rules
[content_schema]
required = ["title"]

# Rules for /posts
[content_schema.posts]
required = ["category"]

# Rules for /posts/2023
[content_schema.posts.2023]
required = ["year"]
```

--------------------------------

### Define Blog Post Schema

Source: https://norgolith.dev/docs/content-schemas

Sets global requirements and field types for blog posts with conditional publishing rules.

```toml
[content_schema]
required = ["title", "author"]

[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"] }
```

--------------------------------

### Minimal Post Template Snippet

Source: https://norgolith.dev/docs/templating

A simplified template fragment for rendering post titles and content.

```html
<!-- templates/post.html -->
<h1>{{ metadata.title }}</h1>
<div class="content">{{ content }}</div>
```

--------------------------------

### lith new

Source: https://norgolith.dev/docs/commands

Creates new content or assets within the project.

```APIDOC
## lith new

### Description
Create new content or assets.

### Usage
`lith new [OPTIONS] [NAME]`

### Options
- **-k, --kind <KIND>** - Asset type (norg|css|js) [default: norg]
- **-o, --open** - Open file in system editor
```

--------------------------------

### Define Extra Configuration

Source: https://norgolith.dev/docs/configuration

Add arbitrary configuration options for use in site templates via the [extra] section.

```toml
[extra]
repo_url = "https://github.com/norgolith/core"
```

--------------------------------

### Configure Norgolith with Nix Flakes

Source: https://norgolith.dev/docs/installation

Adds Norgolith to a NixOS configuration using a flake input.

```nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    norgolith.url = "github:norgolith/core";
  };

  outputs = { nixpkgs, norgolith, ... }: {
    nixosConfigurations.mysystem = nixpkgs.lib.nixosSystem {
      modules = [
        {
          # add norgolith as a package
          environment.systemPackages = [
            norgolith.packages.x86_64-linux.default
          ];
        }
      ];
    };
  };
}
```

--------------------------------

### Migrate now() Function

Source: https://norgolith.dev/docs/templating-migration

The built-in now() function has been removed; use the date filter from tera-contrib instead.

```Tera
{{ now(format="%Y") }}
```

```Tera
{{ now() | date(format="%Y") }}
```

--------------------------------

### Block Shortcode with Body

Source: https://norgolith.dev/docs/templating

Demonstrates a block-style shortcode that wraps content provided via the body variable.

```Tera
@embed html
{% <callout type="warning" > %}
This is a **warning** callout.
{% </callout> %}
@end
```

```Tera
{% component callout(type: String = "info") %}
<aside class="callout callout-{{ type }}">
  {{ body }}
</aside>
{% endcomponent callout %}
```

--------------------------------

### Implement Template Inheritance

Source: https://norgolith.dev/docs/templating

Define a base layout and extend it in child templates to reduce code duplication.

```html
<!-- templates/base.html -->
<html>
  <head>
    <title>{{ site.title }}</title>
  </head>
  <body>
  {% block content %}{% endblock %}
  </body>
</html>

<!-- templates/post.html -->
{% extends "base.html" %}

{% block content %}
<h1>{{ metadata.title }}</h1>
<div class="content">{{ content }}</div>
{% endblock %}
```

--------------------------------

### Create a new Norg file

Source: https://norgolith.dev/docs/getting-started

Generates a new content file in the content directory.

```bash
lith new first-post.norg
```

--------------------------------

### Norgolith Theme Directory Structure

Source: https://norgolith.dev/docs/theming

The standard file layout for a Norgolith theme project.

```text
theme/
├── assets/         # Static files (CSS, JS, images)
├── templates/      # Tera templates for HTML generation
├── theme.toml      # Theme metadata
└── .metadata.toml  # Theme state (auto-generated)
```

--------------------------------

### Include Partial Templates

Source: https://norgolith.dev/docs/templating

Embed reusable template fragments using the include directive.

```html
{% include "header.html" %}
```

--------------------------------

### Lint Rust code

Source: https://norgolith.dev/docs/contributing

Run this command to check your code for common mistakes and improvements using Clippy.

```bash
cargo clippy
```

--------------------------------

### Define a Basic Content Schema

Source: https://norgolith.dev/docs/content-schemas

Configure required fields and basic field types within the [content_schema] section of norgolith.toml.

```toml
[content_schema]
required = ["title", "author"]

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

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

--------------------------------

### Dynamic Content with Loops and Conditionals

Source: https://norgolith.dev/docs/templating

Iterate over collections and render content conditionally based on metadata.

```html
<ul>
  {% for category in metadata.categories %}
    <li>{{ category }}</li>
  {% endfor %}
</ul>
```

```html
{% if metadata.draft %}
  <div class="draft-notice">This post is a draft.</div>
{% endif %}
```

--------------------------------

### Migrate Optional Chaining

Source: https://norgolith.dev/docs/templating-migration

Replace the 'is defined' test with the '?.?' optional chaining operator to handle potentially undefined fields.

```Tera
{% if config.highlighter is defined and config.highlighter.enable %}
```

```Tera
{% if config.highlighter?.enable %}
```

--------------------------------

### Access Plugin Configuration

Source: https://norgolith.dev/docs/configuration

Retrieve configuration values within a plugin hook using the ctx.config object.

```rust
// In your hook:
if let Some(theme) = ctx.config.as_ref().and_then(|c| c.get("theme")) {
    println!("Theme: {}", theme);
}
```

--------------------------------

### Invoke a Shortcode

Source: https://norgolith.dev/docs/templating

Syntax for embedding a shortcode within content blocks.

```Tera
@embed html
{{ <youtube id="dQw4w9WgXcQ" /> }}
@end
```

--------------------------------

### read_source

Source: https://norgolith.dev/docs/mcp

Reads a source file from the repository. Accepts a file path relative to the repository root.

```APIDOC
## read_source(path)

### Description
Read a source file from the repository. Accepts a file path relative to the repo root.

### Parameters
- **path** (string) - Required - The file path relative to the repository root.

### Response Example
{
  "path": "sdk/src/lib.rs",
  "content": "use serde::{Serialize, Deserialize};..."
}
```

--------------------------------

### Shorthand Shortcode Syntax

Source: https://norgolith.dev/docs/templating

Uses shorthand syntax for passing arguments to a shortcode.

```Tera
@embed html
{% <callout type warning > %}
A warning callout.
{% </callout> %}
@end
```

--------------------------------

### Configure .gitignore for plugins

Source: https://norgolith.dev/docs/getting-started

Prevents compiled plugin binaries from being committed to version control.

```text
# Plugin binaries (reinstall with `lith plugin install`)
plugins/
```

--------------------------------

### Conventional Commit format

Source: https://norgolith.dev/docs/contributing

The standard structure for commit messages in this project.

```text
<type>[optional scope]: <description>

[optional body]

[optional footer]
```

--------------------------------

### Define a YouTube Shortcode

Source: https://norgolith.dev/docs/templating

Defines a reusable YouTube embed component with optional autoplay.

```Tera
<!-- templates/shortcodes/youtube.html -->
{% component youtube(id: String, autoplay: String = "false") %}
<div class="video-container">
  <iframe src="https://www.youtube.com/embed/{{ id }}?autoplay={{ autoplay }}"
          frameborder="0"
          allowfullscreen>
  </iframe>
</div>
{% endcomponent youtube %}
```

--------------------------------

### Migrate matching Test

Source: https://norgolith.dev/docs/templating-migration

The matching test now requires the pattern to be passed via the 'pat' keyword argument.

```Tera
{% if value is matching("^nil$") %}
```

```Tera
{% if value is matching(pat="^nil$") %}
```

--------------------------------

### search_docs

Source: https://norgolith.dev/docs/mcp

Performs a full-text search across all documentation pages. Returns matching entries with their norgolith:// URIs and relevance snippets.

```APIDOC
## search_docs(query)

### Description
Perform a full-text search across all documentation pages. Returns matching entries with their norgolith:// URIs and relevance snippets.

### Parameters
- **query** (string) - Required - The search query string.

### Response Example
{
  "query": "plugin manifest",
  "results": [
    { "name": "docs-plugins", "uri": "norgolith://docs/plugins", "snippet": "..." }
  ]
}
```

--------------------------------

### Push feature branch

Source: https://norgolith.dev/docs/contributing

Push your local feature branch to the remote repository.

```bash
git push origin feat/your-feature-name
```

--------------------------------

### Figure with Caption Shortcode

Source: https://norgolith.dev/docs/templating

Defines and uses a figure component with optional caption and alt text.

```Tera
<!-- templates/shortcodes/figure.html -->
{% component figure(src: String, alt: String = "", caption: String = "") %}
<figure>
  <img src="{{ src }}" alt="{{ alt }}" />
  {% if caption %}<figcaption>{{ caption }}</figcaption>{% endif %}
</figure>
{% endcomponent figure %}
```

```Tera
@embed html
{{ <figure src="/img/photo.jpg" alt="A landscape" caption="Mountains at sunset" /> }}
@end
```

--------------------------------

### Rebuild Embedded Content

Source: https://norgolith.dev/docs/mcp

Command to rebuild the MCP server binary after documentation changes, ensuring embedded content is updated.

```shell
cargo build --release --manifest-path norgolith-mcp/Cargo.toml
```

--------------------------------

### Run tests with single thread

Source: https://norgolith.dev/docs/contributing

Executes tests sequentially to prevent interference between tests that share state.

```bash
cargo test -- --test-threads=1
```

--------------------------------

### Validate String Fields

Source: https://norgolith.dev/docs/content-schemas

Apply string validation using max_length and regex patterns.

```toml
[content_schema.fields.title]
type = "string"
max_length = 100
pattern = "^[A-Z].*"  # Must start with uppercase letter
```

--------------------------------

### Validate Boolean Fields

Source: https://norgolith.dev/docs/content-schemas

Define a field that accepts only true or false values.

```toml
[content_schema.fields.draft]
type = "boolean"
```

--------------------------------

### Validate Array Fields

Source: https://norgolith.dev/docs/content-schemas

Enforce constraints on lists, including item types, length limits, and required values.

```toml
[content_schema.fields.categories]
type = "array"
items = { type = "string" }
min_items = 1
max_items = 5
must_contain = ["norgolith"]
```

--------------------------------

### Validate Nested Object Fields

Source: https://norgolith.dev/docs/content-schemas

Define complex metadata structures using nested schemas.

```toml
[content_schema.fields.author]
type = "object"
schema = { name = { type = "string" }, email = { type = "string" } }
```

--------------------------------

### Define Conditional Validation Rule

Source: https://norgolith.dev/docs/content-schemas

Enforces field requirements based on metadata values using an if-then structure.

```toml
[content_schema.posts.rules]
if = { draft = false }  # Condition
then = { required = ["publish_date"] }  # Action
```

--------------------------------

### Tweet Embed Shortcode

Source: https://norgolith.dev/docs/templating

Defines a shortcode for embedding Twitter status updates.

```Tera
<!-- templates/shortcodes/tweet.html -->
{% component tweet(id: String) %}
<blockquote class="twitter-tweet">
  <a href="https://twitter.com/i/status/{{ id }}">View tweet</a>
</blockquote>
<script async src="https://platform.twitter.com/widgets.js"></script>
{% endcomponent tweet %}
```
Tokens:
Raw