todo_markup.js

A minimal todo-focused markup for textual notes

Why

I am deeply interested in creating small markup and programming languages for fun. This markup was created for taking notes quickly during meetings or conferences, when there is only time to open a text file or Google Doc (instead of juggling multiple apps).

This markup is currently a replacement for markdown however, todo_markup.js may eventually become a superset / extension for the markdown specification (likely targeting commonmark).

Features

• Syntax is 8 operators
  • # Heading
  • = Sub-heading
  • ! Incomplete Todo
  • x Completed Todo
  • % Comment
  • @ Footnote
  • ^ Url
  • > Highlight
• The todo file is line based -- there is no nested todo grammar aside from URLs.
• Output or save HTML from various options.
• Output complete and / or incomplete tasks as standalone markdown files.
• Generate an AST-like json object.

See todo.tdx for an example of this markup.

To Do / Roadmap

See Issues for planned features and fixes.

Installation

You can use the demo app to test the markup in a live environment.

Clone this repository if you would like to install todo_markup.js on your system:

git clone https://github.com/unforswearing/todo_markup.js.git
cd todo_markup.js

# print the help message
node todo_markup.js help

Usage

[!NOTE] [outputfile] is optional for all available commands.

• Create HTML from a todo file

# the command below will print html to the console
node todo_markup.js todo.tdx html

# pass a filename to save the output
node todo_markup.js todo.tdx html notes.html

• Output incomplete tasks as markdown

node todo_markup.js todo.tdx incomplete [outputfile]

• Output completed tasks as markdown

node todo_markup.js todo.tdx done [outputfile]

• Output all tasks as markdown

node todo_markup.js todo.tdx alltasks [outputfile]

• Print a minimal Abstract Syntax Tree for todo file

node todo_markup.js todo.tdx ast

Grammar

When creating todo files for use with todo_markup.js you must adhere to the following rules:

• All operators must be placed at the beginning of the line
• Operators must be followed by a single space
• Only one operator can be placed on a single line

[!NOTE] Links are the only exception to these rules. See the Links section below.

Heading

Top level headings are the same as markdown

# Here is a Document Title

Sub-Heading

Sub-headings can be used to separate projects.

= Example Project Name

Incomplete Todo

[!NOTE] todo_markup.js does not have an operator for pending or backlog type tasks to keep focused on current work.

Incomplete Todo items are prepended with an exclamation point !. No need for square brackets []

! This is an item that needs to be done

Completed Todo

Completed Todos are indicated with an x before the todo title.

x This item is complete!

Comments

Comments are marked with a percent sign %. All comments are removed from the compiled file.

% This is a comment about the current task, or anything else

Footnotes

Footnotes are indicated using the 'at' sign '@'. Footnotes are collected at the bottom of the complied file. The footnote text is replaced with See Footnote [num] with a link leading to the footnote at the bottom of the file.

These are normal notes. A footnote will be added to the next line.

@ Footnotes are displayed within a details tag.

Compiled file produces the following HTML formatted text by default:

<div style="background-color: f0f0f0">

  See Footnote [<a id="fnsrc-0" href="#fn-0">0</a>]

  <details>

    <summary>Footnotes</summary>

    <br />

    [<a id="fn-0" href="#src">0</a>]: Footnotes are displayed within a details tag.

  </details>

</div>

Urls

Bare urls can be linked using the carrot operator ^. Urls may appear in any other line regardless of other syntax on that line.

Find future updates at ^https://example.com/important.txt.

Highlight

Highlights are used to add emphasis a specific line of text that is particularly important. Currently the highlight is the only available text formatting option. Compiled highlights use the "mark" tag.

> Please note: Highlights use the default yellow color
> supported by the HTML `<mark>` tag

Text / New Lines

Regular text is returned from the compiler as-is.

The compiler tracks new lines to maintain the structure of the file when producing the AST-like json file.