Built by buildblog
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!
Contents
The repository includes:
buildblog- shell script that builds the blogbuildblog.conf- config file with the scriptâs global variablespages/- directory for Markdown filesstatic/- directory for HTML files, fonts, images, and things that do not require compilingtools/- 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 }}tagfooter.html- content spliced into HTML files with the{{ footer }}tagpage.mdandpost.md- examples of tags to be added to pages and postspage.html- Pandoc layout to convert Markdown to HTMLitem.html- article format for list of postsitem.xml- article format for RSS feedfeed.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 âŚ
$ ./buildblog7. 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.
Happy hacking!