Built by buildblog

Last updated on 2020-04-22 • Tagged under  #blog   #bash   #programming   #linux 

I built my blog by building buildblog! 🐧

Let's go!

What is a "buildblog"?

Its a static site generator script powered by standard Bash tools and the "swiss-army knife document converter" Pandoc. Write content in Markdown, then run buildblog to generate static HTML files ready for uploading to a hosting provider. Good stuff! Feel free to fork the code and customize with your own ideas!

View source

Contents

The repository includes:

• buildblog - shell script that builds the blog
• buildblog.conf - config file with the script's global variables
• pages/ - directory for Markdown files
• static/ - directory for HTML files, fonts, images, and things that do not require compiling
• tools/ - plugins and layout templates

How it works

1. Create a website project folder and download the contents of buildblog from GitHub into your project folder.

A sample configuration and a few posts are included. Run ./buildblog in the console to generate a sample blog that is saved to _public/.

If Python3 is installed, use the included http.server module to view the generated HTML files in a web browser. Example: On my computer running Debian ...

$ cd _public
$ python -V
Python 2.7.16
$ python3 -V
Python 3.7.3
$ python3 -m http.server
[...]

Content is viewable at address http://localhost:8000/.

2. Customizing starts with buildblog.conf. Modify this file by specifying ...

BLOG_NAME="Name of your blog"
BLOG_URL="Your blog URL"
AUTHOR="Your name"

3. Layout for blog posts, pages, lists, RSS feeds, is set by the templates in tools/templates/. These include:

• header.html - content spliced into HTML files with the {{ header }} tag
• footer.html - content spliced into HTML files with the {{ footer }} tag
• page.md and post.md - examples of tags to be added to pages and posts
• page.html - Pandoc layout to convert Markdown to HTML
• item.html - article format for list of posts
• item.xml - article format for RSS feed
• feed.xml - RSS feed layout

4. The static/ directory includes an index.html for the blog homepage plus a style.css.

5. Pages and posts are text files composed in Markdown and placed in pages/.

All pages and posts require a title: key (title of document) and slug: key (generated URL will be https://your-blog-name.org/{{ slug }}/) in the header of the file. See the included files in pages/ for examples.

Pages are files like an about page or projects page that are more descriptive and organize blog content. These files will not be included in the generated RSS feed.

Posts are files that will be included in an RSS feed, and they require an additional date: key. The presence or absence of date: in the document header is what clearly separates pages from posts.

6. Inside the buildblog directory, start the build by running ...

$ ./buildblog

7. The script creates a workspace named build/ and copies the contents of pages/*, static/*, and tools/templates/* into build/ for processing.

8. Custom templates are created as per the variables set in buildblog.conf.

9. Header and footer templates are spliced into HTML files.

10. A list of all posts in descending order by date is generated. This list is written to the blog homepage.

11. An RSS feed is generated as per the plugin located at tools/plugins/rss.sh. (Disable creation of the feed by renaming the script.)

12. Clean URLs: Script creates {{ slug }}/index.md for each page and post. Pandoc converts the index.md files to index.html.

13. Finished content is transferred to _public/ and the temporary build/ is deleted.

14. Done! Files in _public/ are ready to deploy online.

» Later: Full disk encryption (including boot) on Debian

« Earlier: Moving day