Quick Start

Download Uriel

Download and install the latest version of Uriel.

This documentation shows how to download and install Uriel version 1.4.1:

curl -O https://uriel.foo/downloads/uriel-1.4.1.tar.gz
tar -xzvf uriel-1.4.1.tar.gz
cd uriel-1.4.1/

Install Uriel

Uriel is a single, standalone Python script. You don't actually have to install it at all.

If you would like to install the uriel program, along with a man page, run:

sudo make install

As an alternative, you can copy the uriel script anywhere you want, and run it from whatever path you choose.

Create a New Project

The example commands will assume that you have installed uriel, so that the script is in your $PATH. If you are using the script without installing it, adjust the commands you run accordingly.

To create a new project, simply run the uriel program, and pass the path to the new directory it should create for the project. If you want it to create the project under the current directory, then this argument will simply be the directory name for the new project.

For example, let's create a new project called my-first-project:

uriel my-first-project

You should see the following output from this command:

creating 'my-first-project'
creating 'my-first-project/nodes'
creating 'my-first-project/templates'
creating 'my-first-project/static'
creating 'my-first-project/lib'
copying 'my-first-project/static' to 'my-first-project/public', overwriting previous contents
creating 'my-first-project/templates/default.html'
creating 'my-first-project/nodes/index'
creating 'my-first-project/lib/soju.py'
creating 'my-first-project/lib/handlers.py'
creating 'my-first-project/Makefile'
initializing soju
initializing handlers
reading node files
rendering node content
creating pages in 'my-first-project/public' from nodes and templates
--------+-------+----
type    | node  | url
--------+-------+----
file    | index | /
--------+-------+----
created 1 page (1 file, 0 virtual)
copying 'my-first-project/static' to 'my-first-project/public'

Your new project contains the following files and directories:

my-first-project
├── lib
│   ├── handlers.py
│   └── soju.py
├── Makefile
├── nodes
│   └── index
├── public
│   └── index.html
├── static
└── templates
    └── default.html

The links above take you to the relevant Uriel documentation for each respective part of the project.

Building the Project

Now that you have a new project, let's see how to build it, so that you can start experimenting and making changes.

When you first created this project, uriel already built the project.

To build the project again, simply call the uriel program again, with your project directory as an argument.

The uriel program is invoked the same way to create a new project, or to build an existing project. The only difference is whether the directory already exists or not.

In fact, this is the only way to invoke the uriel command at all. It doesn't have any other command-line flags. This is it.

If you are in your project root directory, you can use a dot as an argument to indicate the current directory:

uriel .

Using the Makefile (Optional)

The uriel command itself does not have any dependencies besides the python3 interpreter.

As an optional convenience, uriel creates a Makefile when you first create a new project. If you have the make command installed, you can optionally use it to build your web site.

While in your project directory, simply run:

make

If you have make installed, this will run the uriel command, with your project directory as an argument, and rebuild your site.

When the Makefile is first created, the URIEL variable that points to the uriel command is set to the path where the uriel program was when you ran it. If you move the uriel script away from the location where it was when you created the project, then make will no longer be able to find it.

Therefore, you are encouraged to update the URIEL path in the Makefile accordingly.

If you don't want to install uriel, another option is to simply copy it into your project, so it stays with the project. For example:

cd my-first-project
mkdir bin
cp /path/to/the/uriel/script bin/

# edit Makefile to set URIEL=bin/uriel

This is the most portable option. Your web site project directory will contain the tools to build itself.

Previewing Your Web Site

The web sites that Uriel generates are intended to be viewed through a web server. Fortunately, Python comes with a built-in web server. The following shell commands show how to start the Python web server to preview your web site:

# change into the project directory for your web site
# (in this case, this documentation site)
cd documentation/

# change into the public directory (within your project)
cd public/

# run the built-in Python web server
python3 -m http.server

This will start a built-in Python web server on port 8000. You can now preview your site using the following link: http://localhost:8000/

If you have make installed, you can also use the preview target that comes with the Makefile Uriel created for your project:

make preview

Publish Your Web Site

The public directory contains your generated web site.

You have a lot of options when it comes to hosting a static web site. Almost any possible web hosting service should work.

Your web hosting service will need to be configured to treat index.html files as directory indexes. This is already the default pretty much everywhere. If your hosting provider does not do this already, then you'll need to figure out how to enable that with your provider.

If you are using make to build your web site, consider adding a publish target to the Makefile in your project. That way, you can upload changes to your web site with a single command that stays with your project.

Building the Documentation Project

The documentation you are reading is generated from a Uriel project. The documentation directory from the Uriel source code is the Uriel project that was used to generate the web site you are reading now.

The documentation example project also demonstrates the use of most of the features Uriel has to offer.

To build the documentation site, simply navigate to the documentation subdirectory of the Uriel source code distribution, and build it in the same way that you would build any other Uriel project. For example:

cd uriel-1.4.1/documentation/
make

Tags: