senorprogrammer / til

🍊 A static site generator for capturing quick notes

til is a fast, simple, command line-driven, mini-static site generator for quickly capturing and publishing one-off notes.

All in only two commands.

Example output: https://github.com/senorprogrammer/tilde

tl;dr

❯ til New title here
  ...edit
❯ til -save

And you're done.

Contents

• Installation
  • From source
  • As a binary
• Configuration
  • Example
• Usage
  • Creating a new page
  • Building static pages
  • Building, saving, committing, and pushing
• Publishing to GitHub Pages
• Live Example
• Frequently Unasked Questions

Installation

From source

go get -u github.com/senorprogrammer/til
cd $GOPATH/src/github.com/senorprogrammer/til
go install .
which til
til --help

As a Binary

Download the latest binary from GitHub.

til is a stand-alone binary. Once downloaded, copy it to a location you can run executables from (ie: /usr/local/bin/), and set the permissions accordingly:

chmod a+x /usr/local/bin/til

and you should be good to go.

Configuration

When you first run til --help it will display the help and usage info. It also will also create a default configuration file.

You will need to make some changes to this configuration file.

The config file lives in ~/.config/til/config.yml (if you're an XDG kind of person, it will be wherever you've set that to).

Open ~/.config/til/config.yml, change the following entries, and save it:

* committerEmail
* committerName
* editor
* targetDirectories

committerEmail and committerName are the values til will use to commit changes with when you run til -save.

editor is the text editor til will open your file in when you run til [some title here].

targetDirectories defines the locations that til will write your files to. If a specified target directory does not exist, til will try to create it. This is a map of key/value pairs, where the "key" defines the value to pass in using the -target flag, and the "value" is the path to the directory.

If only one target directory is defined in the configuration, the -target flag can be ommitted from all commands. If multiple target diretories are defined in the configuration, all commands must include the -target flag specifying which target directory to operate against.

Config Example

---
commitMessage: "build, save, push"
committerEmail: [email protected]
committerName: "TIL Autobot"
editor: "mvim"
targetDirectories: 
    a: ~/Documents/notes
    b: ~/Documents/blog

Usage

til only has three usage options: til, til -build, and til -save.

Creating a new page

With one target directory defined in the configuration:

❯ til New title here
2020-04-20T14-52-57-new-title-here.md

With multiple target directories defined:

❯ til -target a New title here
2020-04-20T14-52-57-new-title-here.md

That new page will open in whichever editor you've defined in your config.

Building static pages

With one target directory defined in the configuration:

❯ til -build

With multiple target directories defined:

❯ til -target a -build

Builds the index and tag pages, and leaves them uncommitted.

Building, saving, committing, and pushing

With one target directory defined in the configuration:

❯ til -save [optional commit message]

With multiple target directories defined:

❯ til -target a -save [optional commit message]

Builds the index and tag pages, commits everything to the git repo with the commit message you've defined in your config, and pushes it all up to the remote repo.

-save makes a hard assumption that your target directory is under version control, controlled by git. It is recommended that you do this.

-save also makes a soft assumption that your target directory has remote set to GitHub (but it should work with remote set to anywhere).

-save takes an optional commit message. If that message is supplied, it will be used as the commit message. If that message is not supplied, the commitMessage value in the config file will be used. If that value is not supplied, an error will be raised.

Publishing to GitHub Pages

The generated output of til is such that if your git remote is configured to use GitHub, it should be fully compatible with GitHub Pages.

Follow the GitHub Pages setup instructions, using the /docs option for Source, and it should "just work".

Live Example

An example published site: https://senorprogrammer.github.io/tilde/. And the raw source: github.com/senorprogrammer/tilde

Frequently Unasked Questions

Isn't this just (insert your favourite not this thing here)?

Yep, probably. I'm sure you could also put something like this together with Hugo, or Jekyll, or bash scripts, or emacs and some lisp macros.... Cool, eh?

Does it have search?

It does not.

Does this work on Windows?

Good question. No idea. Let me know?

til's Issues

Support multiple target dirs

How to specify which to post to? Able to move a post between them?

Auto-link URLs found in the body text

I keep forgetting to wrap URLs in markdown syntax for linking them. Have this do that automatically if it finds a URL outside of a pair of braces.

Rename Fail() to Defeat()

Tag pages break up by month also

The index page breaks up entries by month. The tag pages should do the same

Homebrew tap recipe

Save, build, push from one command

til -build should save any uncommitted changes, build the index and tag pages, and push too GitHub.

Write tags at the bottom of the post on each build

Tags get added after the file is generated so they can't be added to a post page when the front-matter is.

Instead, on each -build or -save, loop over the posts, parse the tags and write them to the bottom of the file as links under the user-generated content.

and that's how I met your mother.
<!-- TAGS:START -->
<hr />
[television](./television)
<!-- TAGS:END -->

parseTitle needs to work the way commit message does

Calculate the title from flag args offset

`til -edit` that regexs on partial matches

Opens an existing page for editing. Use Levenshtein distance for matching

Goreleaser to release

Generate GitHub Pages with index and tag categories

Tags in Posts

Just found this. Are you still working on getting tags to show up in posts?? It would sure be nice.

Define Pages theme in config

Possible to specify the GitHub Pages theme in the config and have it take effect with a -save?

Git commit message does not work with additional flags

> til -t t -s Revanchism

ends up committing:

34edb86  t -s Revanchism TIL Autobot on May 23, 2020

-save takes an optional commit message argument

Currently -save commits using the commit message stored in the config file. Same message for all -save saves.

Take an optional param after -save that is the commit message:

til -save Narwhals can hold their breath for 15 minutes

and write that out. If it doesn't exist, fall back to the config setting.

Don't force an editor

On initialization, leave editor empty. When running, if editor is empty, hand off to the OS to open the file (open [page title].md, etc.)

If editor has a value, then use that explicitly.

Concurrent page generation

Build pages concurrently

Short-forms for command flags

-build, -b
-save, -s

Log out files and dirs that are created

When creating config dir and file, etc. log that out

RSS support

This would be cool to add.

To support multiple tags for a post

This is more of a clarification (since I didn't find a suitable group creating this under Feature request).

I couldn't get a post published under multiple tags. Does the project support or am I missing it? (I tried pushing posts with tags separated by whitespace or comma as delimiter, didn't help)

Thanks.

Set up dependabot

Set up linting action

Tag build should only build for tags of new page

Currently every -build operation builds every tag page from scratch. It should only build the tag page for tags that have been added/changed.