Today I learned

A Hugo-built static site of Today-I-learned (TIL) posts, designed to make it as easy as possible to publish a new post.

Scripts

This repo provides two Bash scripts:

• scripts/til_post.sh - Create a new TIL post with a pre-populated Markdown file and open Vim in insert mode.

• scripts/til_screenshot.sh - Capture a screenshot of a selection of the screen and save it to the repo's static/images directory. The system clipboard receives the Markdown to include in the post.

Installation

Checkout the repo and create shell aliases for the two helper scripts:

# ~/.bashrc
source /path/to/repo/install.sh

Consider adding this snippet to your Bash start-up script.

We use Homebrew to install Hugo and other dependencies.

brew bundle --file=Brewfile

Usage

Create a new post with:

til $description

For example:

til that cows cant look up

which will create a Markdown file, named by slugifying the description (i.e. posts/that-cows-cant-look-up.md), pre-populated with Hugo front matter:

---
title: "TIL that cows can't look-up"
date: "2020-07-24"
tags: []
description: ""
---

and open Vim in insert mode with the cursor in the appropriate place.

You then add the TIL content.

To add screenshots, CTRL+Z to background Vim and use the screenshot helper:

til_screenshot $description

e.g.

til_screenshot Alfred preferences UI

.

This triggers macOS's screencapture utility to capture a selection of the screen. After selection, the resulting PNG image is saved to static/images/ using a filename based on a slugified $description and the Markdown to include in the post are added to the system clipboard.

After saving and exiting Vim, the Markdown file and any new images are automatically committed to the repo and published to GitHub Pages.

Linting and fixing

Config files exist for:

• Vale (.vale.ini and vale/) - a custom dictionary is kept in vale/styles/Vocab/Local/accept.txt.
• MarkdownLint (.markdownlint.yml).
• Prettier (.prettierrc.yaml and .prettierignore).

Use vale and markdownlint as linters, and prettier as a pre-save fixer.

Publication

Hugo builds the TIL posts into a static HTML site. The compiled static site is in the docs/ folder.

The published site has URL: https://nsheils.github.io/til

Repo structure

We've structured the repo to keep the TIL content separate from Hugo—all posts live in posts/ while all Hugo-related content is in /hugosite.

Acknowledgements

I shamelessly copied this from David Winterbottom. I have made some modifications to the original codebase to suit my needs.

Hugo theme

The theme for the site is a customized version of Etch.

Other TIL Collections

• David Winterbottom --The person I blatantly copied in the creation of this site.
• Sam Searles-Bryant
• Federico Marani
• Josh Branchaud
• Simon Willison
• Jake Worth
• Hashrocket
• Thoughtbot