Skip to content

Getting Started

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

Quick Start Guide

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

Step 1: Initialize a New Site

Run the following command to create a new Norgolith site:

lith init mysite

This will:

  1. Create a directory named mysite.
  2. Prompt you for site metadata (e.g. title, author).
  3. Generate the default project structure.

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

  • norgolith.toml: contains site-wide settings like title, author and content schemas.
  • content/: store your Norg files here. Each file will be converted to HTML.
  • templates/: customize the HTML output using Tera templates.

Tip

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

Adding Content

Step 1: 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.

Step 2: 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

Step 1: Start the Development Server

lith serve --open

This will:

  1. Start a local server (default: http://localhost:3030).
  2. Open the site in your default web browser.
  3. Watch for changes and reload automatically.

Step 2: 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

Step 1: 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.

Step 2: Build the Site

lith build --minify

This will:

  1. Generate static HTML files in the public/ directory.
  2. Minify CSS and JavaScript for production (this is the default).

Step 3: Deploy Your Site

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

  • GitHub Pages
  • Codeberg Pages
  • Netlify
  • Vercel
  • etc

Next Steps

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

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

2. 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 will override 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. This might change in the future.

3. Add More Content

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

4. Explore Content Schemas

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

Troubleshooting

Common Issues

1. Site Not Updating

  • Ensure you're running lith serve in the correct directory.
  • Check for errors in your Norg files in the server logs.
  • Check for issues with your web browser cache.

2. Broken Links

  • Ensure all Norg files have valid metadata.
  • Check your templates for correct URL paths.

Need Help?

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

Next: Configuration Reference →

Clone this wiki locally