I immediately earmarked it as something to follow and do myself (which I've now done but want to somehow pull across to my blog), and though Simon's post was excellent, it's not written as a set of instructions for doing yourself, so Today I Learned how to copy and tweak Simon's TIL repo.
READER DISCOUNTSave $50 on terminal.training
I've published 38 videos for new developers, designers, UX, UI, product owners and anyone who needs to conquer the command line today.
Overview of how it works
Simon's post goes into the technical detail, but for a brief understanding this is what happens (assuming all the prerequisite files are in place):
- All commits except on the README trigger the workflow (I wonder if this can be ignored though…)
build_database.pyfile runs looking only at
*/*.mdfiles (so one directory deep) and generates an sqlite database
- The records in the sqlite database use the directory as the topic name (so one topic per TIL) and generates create and update times for the record based on the commit against each markdown file
update_readme.pyruns to modify the repo readme inline, looking for
<!-- index start -->and
<!-- index end -->and inserts the table of contents (the good bit)
README.mdis committed under
README-botback into your repo
- Finally the project is deployed to Now
For this to work, you need your own github repo (since this uses github actions) and you need to specifically include the following files:
. ├── .github │ └── workflows │ └── build.yml ├── README.md ├── build_database.py ├── metadata.json ├── requirements.txt ├── templates │ ├── index.html │ ├── query-til-search.html │ └── row.html └── update_readme.py
I've pulled all the files into a single template repo here remy/simonw-til-template (which is a bit weird…) but it's a clean slate to work from.
Put these in your own github repo and leave the default action permissions as "Enable local and third party Actions for this repository".
Changes you need
If you look for
USERNAME throughout the code, you can change this to your own github username (or your real name when used in the index page).
If you want to deploy to Vercel (formally Zeit) Now (which the action does by default), then you need to generate a new Now token and create a new token in the github repo under https://github.com/[YOUR-USERNAME]/[YOUR-REPO]/settings/secrets. The token needs to be called
If you don't want to deploy to Now, in the
.github/workflows/build.yml remove the entire section starting at
name: Deploy Datasette using Zeit Now.
Changes from Simon's original post and repo
If you used the template repo I made, you won't need these, but if you're skimming Simon's post a couple of things to be aware of:
- He uses
datasette publish now2 til.dbbut
now2(for us) should be
now- it's using his datasette-publish-now project.
- You'll need the
templatesdirectory (which initially I thought was a TIL), which is used by datasette to build the actual web pages you'll host on Now
- If you're copying files one by one, the
README.mdneeds to have the following template somewhere in the file:
<!-- index starts -->\n<!-- index ends -->
For my own version I think I might migrate it to my own blog but follow the structure that's already there. That way I can reuse my own existing system for RSS so it's a little more similar to my links.