Skip to content

Theming

Jump to bottom
Alejandro edited this page Mar 1, 2025 · 2 revisions

Theming Guide

Norgolith's theming system allows you to customize the appearance and layout of your site. This guide will walk you through installing, customizing, and creating themes, as well as advanced theming techniques.

Installing Themes

Norgolith makes it easy to install and manage themes using the lith theme command.

Important

Currently, Norgolith only supports pulling themes from Git tags. This was done on purpose to try to make a good system around releases and versioning mandatory.

Install a Theme

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

Update Theme

lith theme update

Rollback Theme

lith theme rollback

Retrieve Theme Information

lith theme info

Theme Structure

A Norgolith theme has the following structure:

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

Key Files

  • theme.toml: Contains theme metadata like name, version and author.
  • templates/: HTML templates using the Tera templating engine.
  • assets/: Static files like CSS, JavaScript, and images.

Creating Your Own Theme

Step 1: Initialize a New Theme

lith theme init

This will prompt for the theme information and create a new theme structure in the theme/ directory:

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

Step 2: Create Templates

Add Tera templates to the templates/ directory. Common templates include:

  • base.html: The base template that other templates extend.
  • default.html: The default template for every page.
  • home.html: The homepage template.
  • post.html: The template for individual posts.

Step 3: Add Assets

Place your CSS, JavaScript, and images in the assets/ directory.

Theme Configuration

The theme.toml file contains metadata for your theme.

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

Fields

  • name: The name of the theme.
  • author: The theme author.
  • description: A short description of the theme.
  • version: The theme version.
  • license: The license under which the theme is distributed.
  • repository: The repository URL for the theme.

Best Practices

Organizing Your Theme

  • Keep your templates modular and reusable.
  • Use template inheritance to avoid duplicating code.
  • Organize assets into subdirectories (e.g. assets/css/, assets/js/).

Versioning Your Theme

  • Use semantic versioning for your theme.
  • Remember to create releases for each version of your theme, otherwise people won't be able to use it.

Testing Your Theme

  • Ensure compatibility with various screen sizes and devices. This could be done by exposing the development server to your LAN network and accessing the website through different devices.

Next Steps

  • Learn more about customizing templates in the Templating Guide.
  • Share your theme with the community by publishing it on GitHub!

Clone this wiki locally