Introducing Lektor

Migrating my website from Pelican to Lektor

Posted on 2017-07-24

Wait, what's a Pelican? I can't hear you over this static site.

Originally, my personal website (this one!) was written using a static site generator called Pelican. A static site generator is a tool that you can use to take markup in the form of Markdown files or reStructuredText files and generate websites out of them. They're great because the website is stored as plain old static files, meaning they're really cheap and easy to host. You can even host your site out of your Dropbox account, but you can do it for free at GitHub Pages, which is what I've been doing.

Pelican is written in Python and I've been using that to get my beak wet with using static site generators. However, as a fan of Flask, written by Armin Ronacher, I decided to use his static site generator, Lektor! Today, I'm going to show you how to get started with Lektor, but if you want to start with Pelican, you can visit two of the guides I found really helpful at Nafiulis and at Full Stack Python.

Why Lektor

I decided to use Lektor because I liked the minimalist design philosophy of it and how it resembles how one might want to structure a Flask web application, which makes it straightforward to understand how the blog is structured and where to make changes.

Where I'm hosting this site

Because static sites are so lightweight and easy to host, GitHub has been so generous as to offer GitHub Pages, a service that lets you store your static site as a GitHub repository and host it on [your_username].github.io/[repo_name]. Because I named the repository "vincentchov.github.io", GitHub Pages will even make that the URL of the site, instead of "vincentchov.github.io/vincentchov.github.io".

How is a Lektor static site structured?

Alright, here's the skinny on how a Lektor project is structured: You start out with an "assets" folder, where you can keep your CSS, JS, and image files, a "content" folder for your actual content (stored as .lr files, which are essentially an augmented version of Markdown files), and here's where it gets interesting: the "models" folder and the "templates" folder.

Under the "models" folder, unfortunately you won't find supermodels (darn!) but instead, you'll find .ini files that describe the different characteristics of the different kinds of pages you may want to write. For example, if you wanted to write a blog, right off the bat, we know there'll be at least two kinds of pages: a blog post, and a page listing out all the blog posts. As such, you'll describe the general model of a blog-post page and the general model of a blog page (which links to blog-posts).

Templates, as the name suggests, contain HTML files that describe the general structure of how each page type looks. You could, for example, make a "blog-post.html" file to use Jinja2-style templating to describe how most blog posts would look like. This pairs nicely with the ability to describing the characteristics a blog post contains, as described in the models folder.

Enough talk. Let's get down to business.

The Lektor documentation is very good, covering most, if not all questions you may have. To install it, you'll need to use a Python 2.7 virtual environment. If you use virtualenvwrapper to make it easier to manage different versions of Python and its packages for different projects, you can create a Python 2.7 environment called env_27 using mkvirtualenv env_27 --python=/usr/bin/python. (Also, if you want to make a Python 3 environment in the future, change /usr/bin/python to /usr/bin/python3 and be sure to name your environment something else.)

Now that you have a Python 2.7 environment called env_27, activate it using workon env_27. Install Lektor to your virtual environment with pip install lektor you'll be ready to set up a basic blog (you can change this later) using the lektor quickstart command. Select yes when asked to create a basic blog and you'll have an example set-up for you.

After the basic structure of the blog is set up, you can get it ready to deploy to GitHub Pages by creating a Git repository and pushing it to GitHub. This alone isn't enough to deploy your website, because all you'll have in your repo is the Lektor project that generates your website, and not the built version of your website itself. lektor build lets you build your website out of the Lektor project, but still doesn't deploy it.

Thankfully, Lektor comes built-in with a lektor deploy [target_name_here] command that lets you declare a deployment target in your project_name_here.lektorproject file. For example, you can add the following two lines to your .lektorproject file to enable deploying to GitHub Pages:

[servers.ghpages]
target = ghpages://your_github_username/your_repository_name

Once you save that file, deployment is as simple as lektor deploy ghpages.

Conclusion

Now that you know how to set up a basic blog and deploy any changes to it, you're off to the races. The rest is a matter of knowing some basic HTML, CSS, and Javascript to adjust the templates for your website (the way things are laid out and how they look) as well as Markdown syntax which is used exclusively for writing out the text that Lektor will use to generate the webpages. Hope this helps!