Skip to content
Text files to help plan & log whatever it is you do. Bullet journal + pomodoro technique + text editors + cloud syncing = progress.
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.
time log template.txt


Text files with markdown formatting to help plan & log whatever it is you do. A lo-fi attention management system to complement your task management system.

These files blend the basic system of a bullet journal with elements of the pomodoro technique, then add all the coolness of plain text files edited in $yourFavoriteTextEditor.

I've been refining these monthly planning text files since 2013, always in a text editor that syncs what's on my phone and my computer. This setup works quite well, since it supplies two important things a paper planner lacks: 1. text tools like "search in project" or batch "find & replace" and 2. the ability to not be left behind in a coffeeshop or bus.

keanu reeves as ted telling bill 'So after the report we can't forget to do this otherwise it won't happen'

table of contents

recommended tools

If you don't already have a favorite text editor, I'd recommend Atom. It works on Mac, PC, and Linux and is highly extendable and customizable.

If you want an app that's more streamlined, on Mac you could try nvALT or the forthcoming nvULTRA. On PC you could try ResophNotes. On Linux you could do just about anything your heart desires, up to and including using nvPy.

recommended packages for atom

If you do use Atom, consider installing and befriending these packages:

  • Toggle Markdown Task, which lets you mark tasks done
  • markdown-folding, which folds lines of text at different heading levels, all of which are marked with one or more #. It lets you fold lines at the week and day level in these files, as well as any other headings.
  • language-markdown, which is an alternative for the built-in language-gfm that adds extra things for lists, including a very satisfying greyed-out effect when you've marked a task done by making its [ ] box have an [x] instead.
  • wikilink, which lets you link between notes using the name of the [[target note]] surrounded by two brackets. That's right: with the package installed, that [[target note]] could let you quickly jump to a separate note named target note. These files already include this style link for moving between months or years.
  • Tomatimer, which puts a lightly configurable pomodoro timer into Atom's status bar and reminds you to take occasional breaks. The files have the beginnings of a markdown-formatted table for each day in case you're moved to try the Pomodoro technique in detail that day.

phone text editors

As for the phone side of things, Editorial is unfortunately the only iOS editor I know of that will quickly let you move through markdown files. In addition to simple scrolling, the file's title doubles as a scrollable table of contents based on headings. This single feature makes it far faster to get to the last week of a month!

Hopefully Editorial gets an update soon, and/or this feature begins being common in phone editors. Here are more than a few iOS options.

If you know of others phone editors that let users move through markdown files by heading, please let me know. Maybe submit a comment as an issue here on Github?

recommended use

Whatever works for you is what you should do!

The one thing I'd strongly recommend is using some tech tool that can give you proactive time-based reminders to go along with these files. Please consider putting tasks into your calendar as events, using something like OmniFocus or Todoist, or something else that can reach across time and say "don't forget to wind your watch".

With these files themselves, what works for me is leaving each month's file open in a window while I do related work on my computer. That way I'll occasionally glance over at the file and be reminded of what I've told myself to focus on, which makes it easier to reevaluate whether I should change what I'm doing. If I'm going to be walking around a lot away from my computer, I'll make a little hipster PDA out of some scrap paper folded up as a one-shot zine.

sounds intriguing, but can you walk me through each file a little more?

You got it, friendly invented interlocutor!

task lists

The most basic thing is that each file uses Github-Flavored Markdown task lists. For each day, you have an ordered list of tasks and an unordered lists of tasks. In between, the <!-- --> html comment serves both as a visual separator for you and as a programmatic separator for any markdown rendering tools you use. Without it, the unnumbered list of tasks will likely be rendered as a continuation of the previous numbered list of tasks with start & end times.

tasks to do at certain times

The ordered list (which starts with 1. [ ]) shows you tasks that should happen at a particular time & place. I use a | to separate the time and the place.

Putting timed tasks both helps prompt me to remember when things need to happen, and to actually think through the process of my day. For instance, I'll often add an extra "buffer" task that tell me to leave my office 35 minutes before it's time to work with a class on our other campus.

tasks that can be done at any time

The unordered list (which starts with - [ ]) shows you tasks that can be done whenever. I try to break each task into indented sub-tasks, each of which represents the minimum possible unit of success. That helps keep me motivated & on track to completing the larger task, while also helping me keep track of where I am when I inevitably get interrupted or distracted.

task annotations

I try to mark each task with one or more tags, each of which contains extra info in parenthesis. The front matter in each file is there to suggest a taxonomy of tags, to simply things for you and your text editor's autocomplete functions. If you want to change these tags, it's simple to use find & replace in project to swap the ones I wrote with whatever you prefer.

A good example of how you might annotate these tags is the two tags reflecting the types of interruptions you'd track with the Pomodoro Technique. For instance, if you're working on a task but continually find yourself distracted by your own thoughts, you might add @internalInterruption() as a tag, then use the annotation for details: @internalInterruption(worriedAboutBills) or @internalInterruption(tooHungryToFocus). You can also annotate @externalInterruption() to track another type of interruptions: @externalInterruption(referenceQuestionOutsideMyShift) or @externalInterruption(labPartnerCouldn'tRememberProcedures).

example of a day

Let's say it's currently 1:00pm and you're looking at this section of the file:

#### 2019-12-03 Tuesday  

1. [x] 10:00am--11:00am | Meeting, Office 110  
2. [ ] 2:00pm--2:30pm | Get over to Main Library  
3. [ ] 2:30pm--5:00pm | Reference Desk Shift, Main Library  

<!-- -->  

- [x] start writing documentation for `monthly-planning-files` project @done(added sections; still need to go into detail about tags, why there are HTML comments, etc)  
  - [x] start a changelog @done(15minutes)  
- [ ] add detail to `monthly-planning-files` documentation  
  - [ ] give tag examples  
  - [ ] explain html comments  
- [ ] proofread documentation  

The ordered list shows that you've already had a meeting this morning, and that you've got another hour and a half before you need to be at the Main Library's reference desk and ready for that shift. However, since it takes a half hour to get over there, you've been kind to Near Future, 2:30PM You and added in your travel time as a task.

In practice, if it's 1:00pm and I'm looking at this file, I'll also look at the tool I used to collaborate with my colleagues to make sure nothing else has been added. This need for extra systems is part of why I stress that this is an attention management system, not a system that's sufficient for managing all your tasks & committments.

Having checked whatever tools you use to coordinate with your team, you're free to select whatever seems like the right thing to do from those tasks that don't have specific start & end times and also aren't already marked completed with a [x].

You can also see from the unordered list of tasks that you've started writing documentation, specifically the changelog. Since you've added the time it took within the optional element after your @done tag, if you ever need to do that again in the future, you can quickly search for changelog in the whole project and see if Past You has ever written down how long it took you to do that on a particular day. I find that extra time information really helpful when trying to figure out what to do and how long it might take.


Each file uses markdown headings (designated by one or more #) to let you fold away what you don't want to see. You can fold by week, by day, as well by other headings.

front matter

At the top of each file, you've got some basic YAML-formatted front matter with metadata that you can easily search by either month number or the name of the month. This front matter also spells out some optional autocompletion "status" terms, all of which you can change.

Since these are ultimately just text files and not actually converted into web pages or anything, it's not important for them to be in YAML format. I've followed that convention to make searchable front matter mostly because I'm used to using Jekyll, a program for making static websites used by GitHub, GitLab, and a bunch of other sites.


Below the front matter / metadata section, each file has links to other files in the [[wikilink]] format. You can put this type of link anywhere you want in a file.

I treat the top of the file as a sort of index / breadcrumbs area, and I add other wikilinks anywhere else they're relevant. If you use the wikilink package in Atom you can also follow these links with simple key commands. I don't often use the included time log template, but I do find it extremely useful on hectic days or ones where I'm more easily distracted than usual.

Potential Gotcha: If you're not used to thinking about file paths, please pay close attention to them when you use, change, or create wikilinks. I mention this because at the beginning of every year I rename my personal files to add another underscore at the front of the file name, which pushes it further down in the file directory. It takes me 5-10 minutes to use "find and replace in project" to update this change in all the files, which feels like a decent trade-off to make to have the current year's files at the top of the file directory the entire rest of the year. In this collection of starter files, the file paths don't match what I actually do in my own notes. If you find yourself wanting to rename the files to improve how they're sorted in your own system, please remember to also update the wikilink file paths. On the plus side, the only thing that happens when a path is wrong is that you either open the wrong file or start a new, empty file. So the errors aren't destructive, just surprising or jarring at worst.

planning and review

To prompt regular planning and review—crucial parts of planning that I increasingly overlook the busier I become—these files have multiple prompts for planning and review.

There is a section for setting goals at the beginning of both each month and each week. At the end of each day, there's an unordered list where you can log what you actually did. Each week also has a "weekly holdovers" section where you can collect all the things you still think are worth doing and don't want to forget, or where you can collect and annotate why you've decided to cancel or postpone certain projects.

I'll often note things that I did without planning in these various review sections. Things like I went for a walk, I read a specific article I saw shared on social media, or other actions that weren't exactly planned but still worth jotting down. The more you jot down, the more likely you make figuring out patterns in the future, or figuring out which readings you should cite since they helped you come up with an interesting interdisciplinary idea.

conventions and duplication

These files mostly use ISO 8601 conventions for time, both in writing dates as YYYY-MM-DD and in naming weeks. Because as XKCD agrees, it is the correct format. In particular, ISO 8601 format puts the numbers in largest to smallest unit. Therefore your computer's file manager will sort files named according to that format correctly.

Having double entries for a particular date (i.e. days at the end of beginning or end of a month on two separate monthly files) sets you up for mistakes. Therefore, each date and week only shows up on a single file, determined by the beginning of the week that includes that date.

file extension

Even though most people use .md for markdown-formatted files, I prefer to have them be .txt (unless there's a need for them to be otherwise, like in Jekyll or other environments). You can of course change that for your own purposes. If you leave them as .txt files, you may need to tell Atom or whatever editor you're using to treat them as (github flavored) markdown files.


These files blend together a lot of strategies & tactics I've picked up from other people. Here's a link to a few of them; I'll add more as I recognize where things came from.


Licensed CC-BY 4.0 International. You are free to share or adapt this work.

You can’t perform that action at this time.