Charts in Markdown

“Now he’s completely lost it” is probably what a regular reader might think. After all, I use plain text (Markdown) as the “single source of truth”¹ in my document workflow,² and now I want proper charts for visualization. Not ASCII bars. Actual pie charts. The kind managers and decision-makers expect. That sounds like a fundamental contradiction. I would argue it is not. In fact, I solved it in a clean way.

My workflow already uses snippets.³ These are placeholders in the text that get replaced by helper scripts. For example, instead of hardcoding an organization name and changing it for every project, I use {{ snippet: global_text_organisation }}. Or I insert the last change date from Git with {{ snippet: document_last_change }}. So why not use a snippet for pie charts as well?

{{ snippet: piechart id="name" values="20,80" labels="done, not done"}}

Parsing the parameters is straightforward. I use awk, which is the right tool for this job.⁴ The real challenge was getting everything into a PDF via LaTeX and Pandoc.

I already use LaTeX templates and overrides, for example to switch between portrait and landscape layout. This is where TikZ⁵ as a LaTeX graphics system and \expandafter come into play.⁶ I simply append the required chart definitions to my existing .tex overrides. Each pie chart is defined individually using its unique id.

Stopping there would miss the point. I do not want to maintain documents manually. Especially not with the constant risk of outdated or incorrect values.

A pie chart needs to “look into the documents”. It must deterministically check whether a status like “Approved” is set, for example via a checkbox [x] Approved.

I already had a snippet called document_checkbox for this. Until now, it only worked on single files. So I built a wrapper called folder_checkbox. It recursively scans all files in a directory and internally uses document_checkbox.

In object-oriented terms, you could say I reused and extended existing behavior by overloading the file parameter.⁷ Instead of a single file, it now accepts a directory path. The directory structure is processed recursively. For example, the entire /tisax directory including all subfolders and documents:

{{snippet: folder_checkbox file="tisax/" action=count_checked from=3 to=4}}

Combine this with the total number of documents (action=count_all), and you get a dynamic pie chart. Both snippets are simply embedded into the pie chart snippet:

{{snippet: piechart 
  id="name" 
  reference={{snippet: folder_checkbox file="tisax/" action=count_all from=3 to=4}}
  values={{snippet: folder_checkbox file="tisax/" action=count_checked from=3 to=4}}
  labels="Number of approved documents"
}}

And that’s it. The pie chart updates automatically based on the content of the documents. With snippets and a bit of Bash logic, I removed a lot of manual work and reduced the risk of errors.

Think about documents as systems.

Best Regards,
Tomas Jakobs