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.
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.
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".
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.
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
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
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.