I was writing a post today, and the post had many headers. Suddenly I was consumed by the thought of adding a nice table of contents to the page. Similar to one I had seen on other sites.

Naturally, I Googled it and found this tutorial on the Ghost blog. It's remarkably straight forward. But it took a while to make it look pretty, but I'm happy with the basic result I have now.

I'm documenting some of the things I learnt from this exercise in terms of Ghost theme customization workflow.

I like to work directly in production (I know right!). Well, the Ghost blog is not very high traffic and the risks are fairly limited so I have made a considered decision to do it.

I have a copy of the blog theme on my local machine. I avoid making any direct changes to the template, if they are not necessary. But if I do, I first upload it to the live site to test them out, before making any commits.

I have a little comment I run to zip up the package and then drag and drop the file in the upload theme section: zip -r solo-shuaib-dev.zip solo.

For the table of contents job, I was having trouble with styling. I use a combination of direct DOM manipulation in Chrome Dev Tools, Windy and Tailscan to make edits in the browser for any front-end work. Once, it looks good, I make it directly in themes file and upload and test it as I described earlier.

The main problem I had was styling as I mentioned. I found that the TOC library has its own CSS which was doing things I didn't like. I copied the raw contents of that file in an online CSS formatter and then pasted them in a style tag within the Code Injection page in Ghost. From then on, I made CSS changes and that section and test them out in another browser window.

Normally, I would use Tailwind CSS directly. But in this particular case, I had CSS classes defined by the author of the library already that I needed to customize. This meant I can't write Tailwind and have to write CSS. Since I was using Windy, and I don't have great CSS knowledge, I found this tool that translates Tailwind to CSS. I copied the Tailwind styles from Windy into that tool and copied the CSS back into the style tag in the code injection screen.

When I was happy with the result, I took all of that CSS and Javascript, and put it in to default.hbs template. This was because I'd like to have this functionality directly built into the template, if I every migrate the site. Having the logic for this functionality split between Code Injection page and the template would most likely confuse future me. Thankfully, I've taken the time to dump my process for future me to remeber.