v2.0 (2024-03-06)

What's New

🎉 Support for templates is here! 🎉

Read the README to learn all about it. If you're using an earlier version, scroll down for how to migrate to v2.0.

Full list of changes are in the commits for this PR.

New/Improved

• things2md is now distributed under the Apache 2.0 license
• templates define the details of output for projects, tasks, and subtasks
• separators are now configurable (separators only get output if the related type has a value)
• separators are more granular, and can now be set for: area, date, deadline, heading, and project
• status symbols ([ ], [/], [x] are loaded from configuration, so they can be customized for use with Obsidian themes
• groupby headers can now be blank, or completely omitted
• better handling of errors reported from things.py
• improved user feedback via stderr for invalid arguments, number of skipped tasks/projects, and if no results meet the given criteria
• date validation for the --date argument
• gifs added to readme to communicate what the heck things2md does, and how well it can work within Obsidian
• readme improved to make it easier to get started, and not bogged down in use case documentation

Changed

• output formats are no longer tied to queries, and are more predictable
• the argument for --simple is no longer needed: just use a different template, such as the simple template provided (—template simple)
• the argument for --format noemojis is now a configuration, and can be optionally removed from area, heading, project, and task
• cancelled tasks are now output in a given output list, versus in its own section, so that it matches up more closely with Things3
• the argument for --format note is no longer need: just use the note template (--template note)
• the arguments for --format wikilinks and --gcallinks are no longer needed: just modify the template (e.g., wikilink for a project titie = [[{project}]]) (e.g., gcallink = [thing_to_link_to]({gcal_url}))

Known Issues

• existing issue: tasks returned using --date and --range may include results from the previous day, depending on your timezone; this is due to the fact that tasks are stored in the Things3 DB as UTC, and things.py stictly returns results according to the provided date, without a timezone adjustment Fixed, see discussion
• --orderby projects gives unexpected results if project names are a mix of upper and lower case, or start with emojis Fixed

Migration Guide

What to consider when coming from earlier versions (i.e., <= 1.1):

With the release of v2.0, several arguments have been removed, so your existing usage of the script will no longer work, and the script will not execute unless these arguments are removed from any calls to things2md.

1. Copy the things2md.json.example file to things2md.json, and read the README.
2. See below for how arguments have been replaced with a much more flexible templates and configuration file.
3. Give the default template a try, and make any adjustments from there.

Feel free to let me know if you have any questions!

If you were using this argument...	...you can now do this instead:
--format noemojis	Now controlled via config flags, with more granularity available.
--format note	Use the note template via --template note. Personally I use this in conjunction with --tag to locate notes I want in this format.
--format wikilinks	Just add [[ brackets ]] to your template; the example default template is closest to v1.1’s output, so give it a try and modify as needed.
--simple	Use the simple template via --template simple, which you can now modify as needed.
--oprojects	Use the --projects argument in conjunction with --template projects.
--tasklinks	Add links to your tasks using the {url} variable; see the example simple template.