Markdown Planner

"Markdown Planner" is a simple tool that allows you to create graphs and Gantt charts from markdown files. Its syntax is easy to use, and in many cases, you can simply write your tasks in a markdown file without any additional steps. Alternatively, you can use existing markdown files and view them as graphs or Gantt charts.

The main purpose of "Markdown Planner" is to quickly visualize task dependencies. It also provides rough duration estimates based on the Gantt chart.

Visualization

"Markdown Planner" offers two different ways to visualize a markdown file: as a Gantt chart or as a directed graph.

Below is a simple plan for the fictional software development of a "VS Code Extension".

Gantt

It is also possible to add a start date (by right clicking on the gantt chart).

Graph

What it is not

"Markdown Planner" is primarily a planning tool and not a tracking tool. However, it can be useful to visualize when a task has been completed or to highlight a task as yellow or red. This is the only tracking support available in "Markdown Planner".

Additionally, "Markdown Planner" does not support resource planning. You cannot assign multiple people to a task to reduce its duration. Therefore, duration and effort is essentially the same in "Markdown Planner".

Example

To demonstrate the usage of "Markdown Planner," create a markdown file named 'plan.md' and add the following text:

# Develop feature X
- Design
- Implement
- Unit test
- Document

Then, in the VS Code file explorer, right-click on the file and select "Open with 'Markdown Planner'." The file will be visualized as a Gantt chart and a graph, as shown in the following image:

(You can choose to display both charts or only one by selecting the desired option from the dropdown menu labeled 'Gantt/Graph'.)

In general, every heading (#) and list item (- or 1., etc.) will be visualized in the charts. The text below a heading or list item (which is not included in this example), typically contains more detailed information on the tasks. This info will not be shown in the charts.

The tasks in the example so far have no dependencies. You can add dependencies in two ways.

One way is to use an ordered list:

# Develop feature X
1. Design
2. Implement
3. Unit test
4. Document

This automatically adds dependencies between the items in the ordered list. The result is shown below:

(Please note the red dependency lines in the Gantt chart.)

Similarly:

The other way is to explicitly add dependencies using the {...} syntax. Simply add {...} to the end of the task text and specify the task it depends on. For example, to achieve the same result as above with an unordered list, you can use:

# Develop feature X
- Design
- Implement {Design}
- Unit test {Implement}
- Document {Unit}

You can have as many hierarchy levels as you like. Here's an example:

# TA
## TB
### TC
- td
  - te
    - tf

Special Syntax {...}

"Markdown Planner" supports a few directives that can be set at the end of a task title to define properties for the task. To use this syntax, surround it with curly brackets and separate each property with a comma (,). The order of properties is not important. For example: {Implementation,x,5d} represents the following properties for a task:

• The task's predecessor is "Implementation."
• The task is completed {Implementation,x,5d}, which will be displayed in green in the Gantt chart or graph.
• The task's effort or duration is 5 days.

In more detail:

• Effort: You can specify it in hours (h), days (d), weeks (w), months (m), or years (y). The equivalent relationships are as follows:
  • 8h = 1d (hoursPerDay: can be modified in the preferences)
  • 1w = 5d (daysPerWeek: can be modified in the preferences)
  • 1m ~ 21d (depends on daysPerWeek)
  • 1y ~ 261d (depends on daysPerWeek) I.e. this is on average without holidays or vacation. It is also possible to enter time as a fractional number. Valid inputs are e.g.: 2d 0.5d 5h 0.25m 3w 0.5y
• You can mark a task to color it with x, y , r , b , g , o or p:
  • x: You can mark a task as completed by adding x to it. This will make it appear green in the Gantt chart or graph. Note: This also supports the extended syntax for markdown task lists. If a task starts with "- [ ]" or "- [x]," the extended syntax is used.
  • y , r , b , g , o or p: The task is highlighted in yellow, red, blue, gray, orange or purple.
• -: Adding this will collapse all child tasks.
• s: The shown text label will appear striked through.
• h: Use h to hide a task and all of its subtasks. You can use this to either temporarily remove a task form the charts, or you can use it to include some markdown text that e.g. is explanatory and should not appear in the chart permanently.
• Any text: It is interpreted as a predecessor to the task. You don't have to enter the full name; entering part of the name is sufficient if it's unambiguous.

PROBLEMS Pane

In case the "Markdown Planner" finds any error ot problem in the markdonw file while converting to a graph or a Gantt chart it will put them into the PROBLEMS pane in vscode.

Interactive Charts

Both the Gantt chart and the directed graph offer a few interactive features.

• If you left click on a task in the view, the editor scrolls to the correspondend line automatically.
• You can right-click on the charts or the tasks to access the context menu.
• Additionally, you can zoom the charts using the mouse wheel (+CTRL).

Gantt

X Axis

You can change the time scale of the X-axis to automatic, years, months, weeks, days, or hours.

Parallel Tasks

You can choose whether the Gantt chart allows all independent tasks to occur simultaneously or if they must be completed one after the other. This simulates the scenario of multiple people working in parallel or only a single person being available.

Comparing both charts will give you a sense of the minimum and maximum durations to expect for the project.

For example, consider the following simple project:

# Simple Project
- TaskA
- TaskB
- TaskC

With 'Parallel Tasks' selected (allowing several people to work in parallel), the Gantt chart would look like this:

Without (one person working sequentially), the chart would be as follows:

Graph

You can change the direction of the graph. But you can try other directions. The menu appears on a right click in an area that is not occupied a by a task (you might have to click near to the border if you have a summary task on top of everything):

Note: The behavior is sometimes strange. Please experiment with different directions.

Known Issues

If you click on a tasks in the graph or gantt chart it will navigate you to the corresponding file/line. Depending on your settings this may open an existing file/editor twice. Or, it opens the file in the same group as the graph/chart is displayed. For better results you should tweak your "Reveal settings". Especially the "Reveal if open" should be enabled.