Bootstrapping a Blog: The Thrilling Sequel (Part 2)

January 14 2023

Well I’ve got a simple praxis by which I can turn markdown files into html files. But this hardly makes a website.

It’s at this point that I’m going to need to distinguish between what is me writing on my machine locally, and what is going to be a published part of the web. I’ve reorganized the directory structure of the blog project to look like this:

λ  lsd --tree --depth 1
.
├──  assets
├──  data
├──  dev
├──  Makefile
├──  posts
├──  prod
└──  scripts

As a brief explanation of this directory structure:

  • assets/ => Contains all CSS, Images, fonts, etc.
  • data/ => Contains configuration files, and partial html fragments that will be concatenated with dynamically generated pieces of html
  • dev/ => The unpublished content of the site. I should be able to point a local web server at this directory and view the unpublished site.
  • prod/ => This should be a directory that I can point a public web server at and have available on the internet
  • posts/ => This is where the site content goes. It will be plain markdown files that eventually get published into html.
  • scripts/ => The various scripts that glue the site together
  • Makefile => The MakefileThough I’ve been tempted to switch to just

     will be the jump off point for developing the site. make dev will launch the local version, make publish will copy get the site onto the production server, and so on.

The remainder of this post will be the implementation of these processes.

assets/

The current structure of my assets folder looks like this:

λ lsd --tree --depth 1 assets/
assets
├──  fonts
│   └──  et-book
│       └── ...
├──  images
│   └── ...
└──  stylesheets
    ├──  post.css
    ├──  syntax_highlight.css
    └──  tufte.css

Which has been fine up until this point. But If I’m going to add separate pages to the site, the stylesheets need more organization.

I’ll start by creating a main.css file, which will (shockingly enough) be the main css file.

@import url('home.css');
@import url('post.css');
@import url('meta.css');

Where home.css will contain styling related to the landing page, about page, etc. post will contain the styling for written content (such as what you’re reading now), and meta.css will pertain to anything like the site header/footer/nav etc. that should appear on most pages but not be related to the content itself. Each of these style concerns can be organized in their own directories as well.

So:

λ  touch main.css home.css meta.css

λ  mkdir post meta home

λ  mv post.css post && mv meta.css meta && mv home.css home && mv syntax_highlight.css post && mv tufte.css post
post.css -> post/post.css
meta.css -> meta/meta.css
home.css -> home/home.css
syntax_highlight.css -> post/syntax_highlight.css
tufte.css -> post/tufte.css

λ  ls --tree assets/stylesheets
assets/stylesheets
├──  main.css
├──  home
│   └──  home.css
├──  meta
│   └──  meta.css
└──  post
    ├──  post.css
    ├──  syntax_highlight.css
    └──  tufte.css

Now a quick edit of head.html to put everything back where it needs to go:

    <head>
        <link rel="stylesheet" href="./assets/stylesheets/main.css"/>
    </head>

And our styles are now slightly more organized than before.

data/

Speaking of head.html, the fragmented partials are starting to get a bit disorganized. Let’s get that put together:

I’m reorganizing the data/ directory to look like this:

λ  ls --tree data/
data
├──  dt.json
└──  fragments
    ├──  pages
    │   └──  home
    │       └── ...
    └──  posts
        ├──  head.html
        └──  tail.html

dt.json a product of building the home page. I may store other config files here in the future we’ll see. HTML fragments get grouped into directories based on the pages they are for.

prod/ and dev/

Are the published and unpublished versions of the site, respectively. For the initial beta, I’m going to use surge. But the end goal here is a full nginx setup on a box I can shell into. All surge requires is a file named index.html, and the rest gets built from there.

First, I’ll need a mechanism by which I can take the posts in the posts/ directory, turn them into an ordered list of html files, and concatenate them into an index page. So let’s get that done shall we?

#!/usr/bin/env bash

## Remember! All relative paths are relative to the Makefile in the project root.

## Ensure that the dev directory has an index file and a posts directory
mkdir -p "$ROOT/dev/posts"


## Remove these files if they exist
[ ! -e "./dev/posts.html" ] || rm "./dev/posts.html"
[ ! -e "./dev/temp.html" ] || rm "./dev/temp.html"

touch ./dev/temp.html

for p in ./posts/*.md; do

    ## Transform the file into html, and put it in the ./dev/posts/ direcotry
    OF=`(echo "$p" | gsed 's/.md/.html/')` ## Turn "foo.md" into "foo.html" for pandoc
    OF="./dev/posts/`basename $OF`" ## Get the proper relative path for the output file
    cat $p | pandoc --filter pandoc-sidenote -f markdown+footnotes -t html | cat ./data/fragments/posts/head.html - ./data/fragments/posts/tail.html > $OF

    ## Now add a ul element to the
    REL_PATH="./posts/`basename $OF`" ## This is the relative path to the post itself from the perspective of the post_index file

    echo "            <li><a href='$REL_PATH'>$(basename $OF)</a></li>" >> ./dev/temp.html

done;

cat ./data/fragments/posts_index/head.html ./dev/temp.html ./data/fragments/posts_index/tail.html > ./dev/posts.html;
rm "./dev/temp.html"

Ah, bash. You beautiful abomination of a scripting language you.

Now there is one small problem here, which is that the posts are un-ordered and that I get the raw filenames instead of a user friendly display name.

I’m going to start by building the navbar and the header. I can add the following to head.html:

<header>
    <a href='/'>
        <img id='kingsfoil_thumbnail' src="./assets/images/kingsfoil.jpeg">
        <h1>Kingsfoil</h1>
    </a>
    <nav>
        <a href="/about">About</a>
        <a href="/posts">Posts</a>
        <a href="/resume">Resume</a>
    </nav>
</header>

Obviously those will just be dead links until the pages exist. But this is as far as I got today. This process will continue in a later post.