magenda: A Python script for creating an agenda of task-list items in GitHub Flavored Markdown files.

#MAgenda

magenda.py is a Python 3 script for creating an agenda of task-list items in GitHub Flavored Markdown files. Task-list items are list items with one of the task-list item markers [ ], [x], or [X] after the list marker.

This script recognises various metadata in the first line of a task-list item. For this line, the following general format is assumed:

<indentation>? <list marker> <task-list item marker> <title> <mention>* <hashtag>* <date-tag>?

For example:

- [ ] buy presents: #shopping
  - [ ] buy Christmas presents @NN #christmas #due:2020-12-24

Here @NN is a mention, #christmas and #shopping are hashtags, and the date-tag #due:2020-12-24 is a due-date specification. Indented task-list items like the second one are taken to be subtasks.

The script is released 'as is' with no warranty under the GNU General Public License, version 2.0.

It requires the following Python 3 package:

blessings

On Debian-based systems, the prerequisite can be installed as follows:

sudo apt-get install python3-blessings

Usage:

magenda.py [-c] [--completed-tasks]
           [-C] [--force-color]
           [-d <num>] [--days <num>]
           [-n] [--line-number]
           [-r] [--reversed]
           [-s] [--subtasks]
           [-u] [--undated-tasks]
           <Markdown file(s)>

magenda.py [-v] [--version]

magenda.py [-h] [--help]

Running the script with -s and -u options on a Markdown file.md containing the task-list items above will generate the following output:

Thu 24 Dec
file.md:buy Christmas presents @NN #christmas
Undated
file.md:buy presents #shopping

Given these options, subtasks and undated tasks are considered in addition to dated tasks. In order to restrict the date range, use the -d option with the number of days from today as an argument. The -r option reverses the date order. Line numbers can be output in addition to file names by means of the option -n.

By default, only uncompleted tasks (i.e. task-list items with the task-list item marker [ ]) are taken into account. With the -c option, completed tasks (task-list items with the task-list item markers [x] or [X]) are listed instead; in this case, dates are determined on the basis of date-tags like #done:2020-12-24.

In a terminal, the output is pretty-printed. The -C option preserves colors and formatting codes when piping the output through GNU less or similar programs.

Andreas Nolda (andreas@nolda.org)

~nolda/magenda

#MAgenda