Quick Start Tutorial¶

Caution

Remember, gilbert requires Python 3.7

First, we’ll create a virtualenv and install gilbert:

$ python3.7 -m venv venv
$ . venv/bin/activate
(venv) $ pip install gilbert

Next, we’ll create a project:

(venv) $ gilbert --root mysite init

This will create a basic project layout:

(venv) $ tree mysite
mysite/
├── config.yml
├── content
├── docs
├── pages
└── templates

4 directories, 1 file

Everything from here out will be easier if we’re inside the mysite directory:

(venv) $ cd mysite/

Now, let’s create the index page for our new site:

mysite/pages/index.yaml¶

 title: Welcome
 ---
 This is my page!

This defines a new Content object, with information _about_ the page (the meta-data) before the — line, and content after.

If we now try to render our site, we’ll see the following:

(venv) $ gilbert render
Found 0 content objects.
Found 1 pages.
Rendering index.yaml ...
-- Done.

And in our docs/ folder we’ll find index.yaml. Not what we wanted. This is becaues we haven’t enabled the YAML plugin. Without it, Gilbert will treat the file as raw data, and just copy it across.

First, let’s clean up our mistake. You can clear the docs directory using the clean command:

(venv) $ gilbert clean

Now, let’s configure that plugin. If you open the config.yml file in your editor you will see something like:

mysite/config.yml¶

global: {}
plugins: []

We can add the YAML plugin as follows:

mysite/config.yml¶

global: {}
plugins:
  - gilbert.plugins.yaml

Let’s try rendering again:

(venv) $ gilbert render
Loaded plugin: gilbert.plugins.yaml
Found 0 content objects.
Found 1 pages.
Rendering index.yaml ...
Template for default.html not found: ['default.html']

We need to provide a template to render the page with. Let’s do that now:

Note

Templates use the stencil template engine.

mysite/templates/default.html¶

 <!DOCTYPE html>
 <html>
   <head>
     <title> {{ this.title }} </title>
   </head>
   <body>
     {{ this.content }}
   </body>
 </html>

This time when we render, we’ll see:

(venv) $ gilbert render
$ gilbert render
Loaded plugin: gilbert.plugins.yaml
Found 0 content objects.
Found 1 pages.
Rendering index.yaml ...
-- Done.

We can now look at our new page:

(venv) $ gilbert serve

And point your browser at http://localhost:8000/

It can be helpful to have gilbert rebuild automatically as you change files.

You can do this easily by passing --watch to the serve command:

(venv) $ gilbert serve ---watch