Quick Start

Overview

Stag generates pages and documents from the set of source files. It’s primarily used to generate web pages from some kind of lightweight markup files (e.g. Markdown, Asciidoc), with the help of a set of templates, but it isn’t limited to that. For simplicity, however, we’ll assume in this Manual that Stag is used to generate a website.

Stag is configured with config.toml file, which is placed in the root directory of your project. Typically, Stag’s input resides inside the content directory and the output is generated to the _output directory.

Stag intends to be simple to use and understand. It removes many magical parts of other static generators have, being more explicit instead about what it does.

Creating the First Page

Let’s start with a simple one-page website, which we’ll build upon.

Installing Stag

Before we even start, Stag must be installed on the system. Stag is released to the PyPI, so it’s easy to install it with pip, or tools like pipx:

$ pip install --user stag-ssg

Optionally, you can clone its repository and install it from there:

$ git clone "https://git.goral.net.pl/stag.git"
$ pip install --user ./stag

Initializing Stag Page

To quickly generate all the necessary files, run:

$ stag init

Stag will ask you some questions, like the title of your page or language in which you intend to write.

Note	`stag init` can be run non-interactively, by passing all the required parameters on the command line.

Your newly initialized Stag project has the following items:

config.toml: Configuration file.
content: Directory where the sources of your website reside.
themes/default: A default theme (templates) for your website.

Test run

Once you familiar yourself, it’s time to test-run Stag. To do that, enter the to your projects root and run stag build:

$ cd stag
$ stag build

Once run, Stag creates a new directory, _output, in which it stores the whole generated webpage. To view it, point your web browser to the index.html file.

From this point you can continue with Your First Site tutorial to learn how to create something less bare-bones.

HTTP Server

Stag also offers a built-in HTTP server, which serves the content of built website. HTTP server runs on a random open local port. It prints the chosen port to its output and automatically opens web browser with a correct address.

To start it, run stag serve. In this mode Stag automatically detects when files are modified and regenerates the website as necessary, which makes it great for example for writing articles, constantly verifying how they look.

By default stag serve overwrites the URL of your site in order to correctly render it locally. You can disable this behaviour by running stag serve --preserve-url, or you can provide your own URL by running stag serve --url <address>.