Published On - 10:51:26 AM CDT November 04, 2022 | Markdown available here
I’ve put off creating a blog for far too long, using the excuse that either I didn’t really like the frameworks that existed out there or that doing so would require too much hands on modifying of HTML/CSS and all of that fun stuff. In the end, I wanted something simple and “old internet”, without javascript running rampant, and so I settled on writing a really basic blog auto-generation framework using a combination of bash scripts and makefiles, then pandoc and rsync to generate HTML and update my site from markdown files which are much easier to write in my opinion.
This is a pretty big overhaul compared to what I had on my webpage before. It’s much simpler and more suited to my own idea of how the internet should be, but that’s besides the point. All I want to get across here is that I made a fairly straightforward tool and wanted to share it… So without further ado:
Before the question comes, yes, I am accepting criticism on the naming I’ve chosen to go with here. Often times a tool has a name that falls short anyways, and this way it is at least descriptive enough to tell you what the tool does. I’m simply skipping the part where I put effort into the naming to save us all some time.
I like bash scripting and I’m not terrible at it, so I figured I’d use that to my advantage and write some scripts to handle the annoying parts of maintaining a blog/webpage for me.
For everything to work, you need to clone the framework, and should install pandoc and rsync. That should be good enough to get started.
The current framework, which is subject to change when I get bored again, assumes four main pages: Home, Research, and Misc. Here you’re free to put whatever you like by simply modifying the *.md files of the same name found in the pages/ directory. To generate HTML for these pages, simply run make pages.
The Blog page and it’s corresponding HTML is automatically generated by a script when the command make blog is run.
There is a deploy.sh script that uses rsync to copy files to your site. This can be easily modified to suit your needs. Then, to deploy your changes on your page, you can run either make website or make deploy. There is also a dry-run option which will show you what files will be updated when you deploy.
It’s also simple to create new posts or edit current ones. You can do it the old-school way of using your favorite text editor to open up the markdown files themselves, or you can run make newpost and a post skeleton will be generated for you with the filename you specify.
That’s pretty much all there is to it! I think keeping the tool small and useable is as good a goal as any, so while there may be changes to the code to make things easier or more generic to other templates/site designs, I will do my best to keep everything as simple as possible.
At the moment it is set up in a way specific to fit my needs in a website, but that could easily be changed since there is minimal HTML to edit. In the future I may consider wasting some time to make this more broadly applicable. Bearing that in mind, the only files really required are those *.md files found in the pages/ directory by default. These correspond with the pages linked to in the header bar with the current design. The blog page is automatically generated from the list of posts located in the blog/ directory.
Any additional pages or files can be added to their respective directories, with files/ containing more useful things like pdfs or other documents you wish to link to in posts. Modifying the logo.svg or smalllogo.svg files will update the menu bar icon and tab icon respectively. The CSS files found in the, you guessed it, css/ directory handle style for the site. The pages and blog list use blog.css and the posts themselves use post.css.
It’s always inspiring for me to read through other people’s blog posts and see their writing improve and change over time, and I’m hoping I will be able to say the same about my own as time passes. My hope for this tool is that it will succeed in taking the challenges out of writing a blog for me and anyone else who happens to stumble upon it. Best of luck to you all!
- Griffin