How I built this website using Python and Markdown
This is a slightly technical walk through in case anybody would like to build from my experiences.
The short version
I built a custom script that parses markdown files and outputs plain HTML. These files are hosted on Netlify and the build process is triggered by pushed to a Github repository .
Starting point
I wanted a robust system that was independent from platforms and as future-proof as I could make it. Opting to build on top of Markdown files seems the best choice, especially because with them it is possible to lower the barrier to writing . The files are stored in my own computer and backed up and synchronized through a Github repository . As an editor I use Obsidian (see: choosing between Zettlr and Obsidian ).
The technology choice
Even though I used Pelican in the past, and I know how well Jekyll works (that's what Tom Critchlow uses ), I wanted something different. I gave GatbsyJS a try. And even though It looks like a fantastic piece of technology, I don't want to mess with JavaScript and much less with React. I also found the Andy Theme which gives a neat look to notes, and the Brain Theme , which triggered the initial design of this website.
Going for a custom builder, leveraging the existing libraries seemed the way to go.
Minimum Features I wanted
- Render markdown
- Handle subdirectories and static files
- Using the wikilink syntax
- Building backlinks
- Custom syntax (i.e. images of certain width, etc.)
- Templating System
Custom Static Builder
To achieve the minimum required features, I built a Python script that goes through all the markdown files within a folder, extracts the links to other pages (wikilinks) and builds a dictionary with all the information, including those backlinks . Another loop renders the Jinja2 templates and saves them to an output folder.
I released the builder under a BSD license , because I think it can be used by others to learn. It is fare from being 'a package', but many of its parts can be repurposed easily for others trying to achieve the same.
Styling
A different chapter is about how to make it look nice, I used TailwindCSS , a great library, that has amazing video tutorials to quickly get started. The actual style for the website is stored on a separate file that later I use when rendering the pages. The process is a bit manual, separating the template from the notes, but in principle it is something that happens only once or rarely.
I wanted to have links that are easy to follow, and therefore I opted to having a different underline color depending on whether they are internal or external links. I also wanted to give a predominant position to the backlinks (see: backlinks are the core of my digital garden ). Some things I've learned about TailwindCSS:
- How to setup gulp to minify the style file
- How to make cool underlines for links with TailwindCSS
- The prose plugin of TailwindCSS is a great addition for people like me
Deployment
Since the output of the program is a collection of HTML files, I thought about giving netlify a try. I've heard many good things, and they are specialized in this type of situations. One of the nicest things about Netlify is that it's setup process is straightforward.
Some things to note about the process
: Some dependencies of my static website generator can't be installed via the
setup.py
file, so I had to add a
requirements.txt
file to ensure that dependencies are installed first, and then the package itself. I also had to add a
runtime.txt
file to specify the Python version, or it would default to Python 2.
Comments
I thought for a while whether I should add comments to a digital garden or not. On the one hand it would allow to quickly gather feedback and collectively build knowledge. However, that's the role of webmentions . Anybody is free to ping me from their own spaces.
Also, comments may relate to content that changes, moves, and is lost.
In the end, I opted to add a contact form at the bottom of every note.
If anybody reaches out, I know from which note the comment was triggered, and we can establish a 1-to-1 dialog, without making it public.
After much consideration, I believe comments belong to few spaces. Websites I follow, like Microsiervos or Seth Godin 's blog don't have comments.
Microformats
The last feature I want to point out of this website is that I tried to implement Microformats in order to make the content more parseable by engines. I accept webmentions although they are not displayed on the pages, yet. I am still experimenting with the different options, but I do like the idea of having backlinks across domains . If I may be allowed to continue with the garden metaphor, Webmentions are a way of pollinating species in different gardens.
Backlinks
These are the other notes that link to this one.
Comment
