makesite.py

Take full control of your static website/blog generation by writing your own simple, lightweight, and magic-free static site generator in Python. That's right! Reinvent the wheel!

Contents

• Introduction
• But Why?
• Get Started
• The Code
• Layout
• Content
• FAQ
• Credits
• License
• Support

Introduction

This repository contains the source code of an example website containing two static blogs and a few static pages. The website can be generated by running makesite.py. The output looks like this. That's it!

So go ahead, fork this repository, replace the content with your own, and generate your static website. It's that simple!

You are free to copy, use, and modify this project for your blog or website, so go ahead and fork this repository and make it your own project. Change the layout if you wish to, improve the stylesheet to suit your taste, enhance makesite.py if you need to, and develop your website/blog just the way you want it.

But Why?

For fun and profit! Okay, maybe not for profit, but hopefully for fun.

Have you used a popular static site generator like Jekyll to generate your blog? I have too. It is simple and great. But then did you yearn to use something even simpler to generate your blog? Do you like Python? Perhaps the thought of writing your own static site generator crossed your mind but you thought it would be too much work? If you answered "yes" to these questions, then this project is for you.

With makesite.py, you are in full control. There is no hidden magic! There is no need to read any documentation to understand how it works. There is no need to learn how to write configuration files to produce some desired effect.

With makesite.py:

• The code is the documentation.
• The code is the configuration.

Everything is laid out as plain and simple Python code for you to read and enhance. It is less than 130 lines of code (excluding comments, docstrings, and blank lines). It gets you off the ground pretty quickly. You only need to execute makesite.py.

You can develop a decent website/blog within a few minutes and then you can begin tinkering with the source code, the layout, and the stylesheet to customize the look and feel of your website to your satisfaction.

Get Started

This section provides some quick steps to get you off the ground as quickly as possible.

1. For a quick demo on your local system, just enter this command:

   make serve
   

   If you don't have make but have Python 3.x, enter this command:

   python3 makesite.py
   cd _site
   python3 -m http.server
   

   Note: In some environments, you may need to use python instead of python3 to invoke Python 3.x.

   If you only have Python 2.7, enter this command:

   python makesite.py
   cd _site
   python -m SimpleHTTPServer
   

   Then visit http://localhost:8000/. It should look like this.

   Note: You can run makesite.py with Python 2.7 or Python 3.x.

2. You may see a few Cannot render Markdown warning messages in the output of the previous command. This is due to the fact that an example blog in this project has a few posts written in Markdown. To render them correctly, install the commonmark package with this command:

   pip install commonmark
   

   Then try the previous step again.

3. For an Internet-facing website, you would be hosting the static website/blog on a hosting service and/or with a web server such as Apache HTTP Server, Nginx, etc. You probably only need to generate the static files and know where the static files are and move them to your hosting location.

   If you have the make command, enter this command to generate your website:

   make site
   

   If you don't have make but have python3, enter this command:

   python3 makesite.py
   

   Note: In some environments, you may need to use python instead of python3 to invoke Python 3.x.

   If you only have python, enter this command:

   python makesite.py
   

   The _site directory contains the entire generated website. The content of this directory may be copied to your website hosting location.

The Code

Now that you know how to generate the static website that comes with this project, it is time to see what makesite.py does. You probably don't really need to read the entire section. The source code is pretty self-explanatory but just in case, you need a detailed overview of what it does, here are the details:

1. The main() function is the starting point of website generation. It calls the other functions necessary to get the website generation done.

2. First it creates a fresh new _site directory from scratch. All files in the static directory are copied to this directory. Later the static website is generated and written to this directory.

3. Then it creates a params dictionary with some default parameters. This dictionary is passed around to other functions. These other functions would pick values from this dictionary to populate placeholders in the layout template files.

   Let us take the subtitle parameter for example. It is set to our example website's fictitious brand name: "Lorem Ipsum". We want each page to include this brand name as a suffix in the title. For example, the about page has "About - Lorem Ipsum" in its title. Now take a look at the page layout template that is used as the layout for all pages in the static website. This layout file uses the {{ subtitle }} syntax to denote that it is a placeholder that should be populated while rendering the template.

   Another interesting thing to note is that a content file can override these parameters by defining its own parameters in the content header. For example, take a look at the content file for the home page. In its content header, i.e., the HTML comments at the top with key-value pairs, it defines a new parameter named title and overrides the subtitle parameter.

   We will discuss the syntax for placeholders and content headers later. It is quite simple.

4. It then loads all the layout templates. There are 6 of them in this project.

   • layout/page.html: It contains the base template that applies to all pages. It begins with <!DOCTYPE html> and <html>, and ends with </html>. The {{ content }} placeholder in this template is replaced with the actual content of the page. For example, for the about page, the {{ content }} placeholder is replaced with the the entire content from content/about.html. This is done with the make_pages() calls further down in the code.

   • : It contains the template for the blog posts. Note that it does not begin with and does not contain the and tags. This is not a complete standalone template. This template defines only a small portion of the blog post pages that are specific to blog posts. It contains the HTML code and the placeholders to display the title, publication date, and author of blog posts.