Birdpress Static Site Generator

BirdPress is a static site generator that I wrote, with the intention of being simpler than most of the alternatives out there. Let's face it, most of those were written by developers, for developers. I don't consider myself a developer, but I like making websites. And that should be a simple process. BirdPress is a solution I made for me.

Credit where due: Props to Chatty G (a.k.a. ChatGPT 4) here as a co-developer, as I really couldn't have done this one my own -- indeed, in the past, I didn't.

If BirdPress works for anyone else out there, please feel free to use it. Feedback is welcome.

Documentation

Download

Grab the code over on the Githubs:

BirdPress on Github

Overview

BirdPress is similar to some popular Content Management Systems that may or may not rhyme with Birdpress. You can write your content as posts or pages, all stored in your input folder as markdown files. BirdPress has tags, categories, and RSS feeds. Heck, it has RSS feeds for tags and categories too. The nav menu and themes can be configured in CONFIG.json.

Quick Start

Step 1: Install python, if it's not already on your system. If you're on Windows, grab it from the Microsoft Store.

Step 2: Install the requirements using: pip install -r requirements.txt in your terminal, from the Birdpress root directory (i.e. the same directory that requirements.txt are in). Basically, we're installing PyYaml, markdown, and Jinja2 here. Using a virtual environment perhaps not a bad idea here.

Step 3: Have a look around the input folder as well as at CONFIG.json. And then run python make_site.py to make the site using the dummy content that comes in the input folder, and the default settings in CONFIG.json. If you can take it from here, please do. If not, there are more details below.

More Details

BirdPress's General Structure

BirdPress converts Markdown files in an "input" directory to HTML in an "output" directory with a simple command:

python make_site.py

The input directory that holds your content will look roughly like this:

|- input
    |- index.md
    |- about.mb
    |- contact.md
    |- images
        |- example.png
        |- logo.png
        |- favicon.png
    |- posts
        |- 20231230-hello-world.md
        |- 20240115-another-post.md

And when the make_site.py script is run, the resultant HTML is then output as:

|- output
    |- index.html
    |- about.html
    |- contact.html
    |- images
        |- example.png
        |- logo.png
        |- favicon.png
    |- posts
        |- 20231230-hello-world.html
        |- 20240115-another-post.html
    |- rss.xml

The script does the following:

Themes

Currently there are a few theme options available that you can declare using the theme_stylesheet option in the CONFIG.json file.

Shortcodes:

Some people like to list their blog posts on the front page. Some people like to do that on pages like posts.html or blog.html, or news.html. You can put it on any page you wish (but not posts), with this handy shortcode:

{{ insert_blog_posts('all') }}

This code above, when placed in the body text of your markdown file, will list all your blog posts as an unordered list.

{{ insert_blog_posts(5) }}

Similarly, the above code will list the 5 most recent posts, or whatever number of posts you decide to specify.

You can also print the dates, by passing a "true" value for the "show dates" second parameter:

{{ insert_blog_posts('all', true) }}

Categories and Tags can be printed into your pages, by pasting these shortcodes into your markdown:

{{ insert_categories(show_rss=False) }}

{{ insert_tags(show_rss=False) }}

Categories and tags can also be printed with their RSS feeds:

{{ insert_categories(show_rss=True) }}

{{ insert_tags(show_rss=True) }}

Meta Data Values

Typical values that you can declare at the top of your post/page are:

title: This is a test post title
categories: ["Writing", "Side Projects"]
tags: ["Japan"]

Important notes:

Other meta data elements:

*Planned, but not yet functional:

Hero images

If you want fancy full-screen hero images at the top of your post or page, simply add a link to your hero image (in static/images) to your meta data:

hero_image: "../static/images/your_header.jpg"

Note that these hero images are typically wide rectangular things, so as long as you adhere to that shape, you should be fine.

Font Families

I've opted for pretty simple font options for now, and all those are declared in the theme CSS templates in the root variables. If you're confortable editing those, please feel free.

Note to self on Asian fonts:

Viewing Your Website

To test your website locally, navigate to your output directory and run:

python3 -m http.server 8000 (or whatever port you want to try it out on), then navigate to http://0.0.0.0/8000 to view your site.

To kill this process:

lsof -i :8000 (or whatever port it is) and then kill [PID]

You can also use VS Code's Live Server extension.

Writing Content in Markdown Files

Creating links in your markdown files to other posts, pages, or static assets (like images or documents) is straightforward. Here's how you can do it:

Remember, all internal URLs should be relative to the base URL of your site, ensuring that your links remain intact regardless of the domain or subdirectory your site is hosted in.

Of course, linking to external sites is easy, e.g. [google](https://www.google.com).

CSS Extras

For most people, the basic styling should suffice (I hope). But I've added a few more options which you can turn on/off in the bottom of the CONFIG.json file per your preference:

Button usage

If you want pretty buttons, you can use the html below when the buttons css extra is set to true:

<a href="your-link-1.html" class="button button-primary">Primary Solid</a>

<a href="your-link-2.html" class="button button-secondary">Secondary Solid</a>

<a href="your-link-3.html" class="button button-primary-outline">Primary Outlined</a>

<a href="your-link-4.html" class="button button-secondary-outline">Secondary Outlined</a>

Markdown Extras

Table of Contents ShortCode

If you have table of contents enabled in the config file, you can insert [TOC] at the top of a post or page to generate a table of contents for your page based on the headings. Learn more on the table of contents extensions documentation page.

Markdown footnotes are enabled.

As with table of contents above, if markdown footnotes are enabled in the config file, you can use them in Birdpress. Learn more over on the footnotes extensions page.

RSS Feeds

RSS feeds are awesome, so Birdpress has an RSS feed for your posts. Also, if you enabled in the config file, (i.e. if "publish_category_feeds" or "publish_tag_feeds" are set to true) then those feeds will be published, and will be listed on that category's or tag's page. In the example input, you'll see an RSS.md page which I think is a good way to present your feed, and it includes shortcodes to list category and tag feeds. Note that the feed is exposed in the site head by default.

License

MIT License

Further Resources

Color Tools:

Tables:

RSS

Hosting Suggestions

There are lots of places that you can host your HTML once it has been output. I'll list a few below, though of course your preference will largely depend on your experience. I've not tested most of these, but they seem ok: