Getting Started

This guide will walk you through setting up your first static site, creating content, and deploying it. By the end of this guide, you’ll have a fully functional Norgolith site.

Note

This guide assumes that you’ve already installed Norgolith.

Creating Your First Site

Initialize a New Site

Run the following command to create a new Norgolith site:

lith init mysite

This will:

Getting Familiar With Your Site

Your new site will have the following structure:

mysite/
├── .build/          # Dev server artifacts
├── 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

Key Files

Tip

You might want to add .build directory to your gitignore.

Adding Content

Create a New Norg File

lith new first-post.norg

This creates a new Norg file at content/first-post.norg.

Important

By default, every Norg file created using lith new will have a draft metadata field which value is true. Remember to change its value to false when publishing your site.

Edit Your Content

Open content/first-post.norg in your favorite editor. Here’s an example:

@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.

Previewing Your Site

Start the Development Server

lith serve --open

This will:

View Your Content

Navigate to http://localhost:3030 to see your site with the default index.norg generated while running lith init. Your first post will be available at http://localhost:3030/first-post.

Building for Production

Switch the draft value

In content that is ready to be published, remember to change the value of draft in the document metadata from true to false. Otherwise, lith build will ignore the file because it is not production-ready.

Build the Site

lith build --minify

This will:

Deploy Your Site

You can deploy the contents of the public/ directory to any static hosting service, such as:

Next Steps

Now that you have a basic site up and running, here are some ways to extend it:

Customize Templates

Edit the files in templates/ to change the look and feel of your site. Norgolith uses the Tera templating engine, which is inspired by Jinja2. Please make sure to read the docs to understand how to properly use it.

Tip

The default base.html template is using the Tailwind V4 CSS framework from CDN, you can safely remove it if you do not want to use Tailwind at all.

Install a Theme (optional)

# e.g.
lith theme pull github:NTBBloodbath/norgolith-pico-theme

Learn more about the themes in the Theming guide section.

Caution

Theme templates have higher precedence than the user-defined templates by design if they are named exactly the same in both the user’s templates directory and the theme templates directory.

Add More Content

Use the lith new command to create additional pages and assets.

Explore Content Schemas

Define validation rules for your content metadata in norgolith.toml. Learn more in the Content Schemas Guide.

Troubleshooting

Common Issues

Site Not Updating

Need Help?

Join the Neorg community on Discord for support and discussions in the #norgolith channel.

Next: Configuration Reference →