Getting Started

Getting started with Nonja is straightforward.

Prerequisites

You will need to have the latest version of Python installed in your local environment along with an environment tool; the team uses venv with Python 3.10.2. A good code editor is recommended; the team uses Visual Studio Code.

Setting up your environment

Create your project folder in your local filesystem:

mkdir my-project

cd my-project

Create a Python virtual environment for the folder:

python3 -m venv env

. env/bin/activate

Update pip and install the Nonja package:

pip install --upgrade pip

pip install nonja

Starting the project

Nonja is based on a very opinionated workflow and structural convention. You can start your project by scaffolding the structure Nonja expects by using the start command:

nj start

This will generate the build and src folders along with a package.json file. The package.json contains information about the project along with a dependency on the dart-sass package and scripts for building stylesheets based on Nonja's folder structure.

You will need to run your preferred package manager, either NPM or Yarn, to setup and install the required Node.js modules:

npm i

Do not skip this step as Nonja expects either package manager to be present during the build process.

Adding your first page

Nonja provides the ability to generate content. Let's start with creating your first page:

nj generate page index

This will add two files to your src/content folder: index.html and _shared.html. These are Jinja templates, similar to what you would use in a Flask or Django project. Open the index.html file and modify the contents as follows:

{% extends '_shared.html' %}

{% block title %}{% endblock %}

{% block head %}

<!-- Additional link, meta, style, or other elements -->

{% endblock %}

{% block content %}

<!-- Content block -->

<p>Hello, world, from my new static site!</p>

{% endblock %}

Adding styles with Sass

Next, we're going to add a Sass stylesheet to the mix:

nj generate style site

This will create a new Sass file, site.scss, in the src/styles folder. Add your CSS and Sass declarations to this file, it will be included in the build process later.

Putting it together

Let's build the current content:

nj build

This will generate all of the available content into the build folder. From here, have a look at the generated source code for your site. If you'd like to view the content in the browser, you can either load the pages from your filesystem, use Nonja's built-in web server, or you can start a Docker container (described below).

Serving the content with Nonja

Nonja can launch a very basic HTTP server to view the contents of the build folder:

nj serve

The service instance will be listening on port 5000 of your machine, or http://localhost:5000. To end the service process, press Ctrl+C.

Serving the content with Docker (optional)

If you have Docker available, Nonja can generate a Docker Compose file based on the Apache Foundation Docker image for the HTTP Server Project.

nj generate docker-compose

This container is set up to serve the content of the build folder on port 5000, a.k.a. http://localhost:5000. The build folder is mapped as read-only to the htdocs folder in the container. You can start the container and let it run in the background while you are building your site:

docker compose up -d

And when you're ready to shut it down:

docker compose down

Wrapping up

Nonja makes a few assumptions about projects, such as the use of Sass, and tooling.

If you'd like to know more about what Nonja can do, head over to the Reference section.