ISMS as Code  UPDATE

Over the weekend, I published a sample repository on Codeberg.¹ It proposes treating ISMS documentation like code. The concrete example is an ISO 27001 risk assessment for organizational assets. The focus is less on the document itself and more on the underlying concept.

Everything is written in a universal, text-only format that will still be editable in any editor 50 years from now: Markdown.²

Markdown comes with a few practical advantages:

• remains readable and editable even without a renderer
• supports checkboxes for tasks and review workflows
• allows structured tables, lists, and metadata
• supports diagrams using Mermaid³
• works in knowledge bases and wikis such as BookStack⁴

With Git⁵ as the version control system, hosted on your own server using something like Forgejo,⁶ you gain additional control over documents and access. At the same time, you get a complete change history for free.

A single Markdown file as the “single source of truth”⁷ can be used to automatically generate a PDF or any format required by a customer or auditor. Tools like Pandoc,⁸ LaTeX,⁹ HTML,¹⁰ or even the CLI of a headless LibreOffice instance provide almost unlimited conversion and formatting options.¹¹ Custom scripts take care of automation. The result is a clean, consistent document, as shown in the screenshot below.

Screenshot of the final PDF generated from the Markdown document

Regular readers will recognize the similarity to the PDFs on this blog and in my whitepapers.¹² I have been using a similar workflow for years. Traditional office applications are opened less and less.

This approach, taken from open source software development, stands in stark contrast to what is still common in many companies. In my experience, many still work as if it were the 1980s: loose collections of files in deeply nested directory structures on shared drives. Back then on bus-wired PCs with BNC connectors, T-pieces, and 50-ohm terminators.¹³

Even for a single person, such setups are error-prone and hard to manage. Files get overwritten or deleted by accident. Entire directory structures get moved. Traceability is lost. The problem scales with the number of people and over time. And then comes the next version of the proprietary software, with built-in incompatibilities or new file formats. The same problems have existed for four decades. They waste time and add friction.

Open file formats and a Git-based workflow on a Forgejo server solve these issues. Every change is traceable down to the individual character. Access across system and network boundaries becomes trivial. The format stays universal and readable everywhere.

The biggest advantage, however, is automation. Processes can be reused with minimal effort for new customers or projects. This creates an infrastructure that scales cleanly in all directions. As outlined in my previous post, one principle applies in IT:¹⁴

No scaling without automation.

This requires a certain level of organizational maturity and knowledge. People need to think in terms of code and processes, much like software developers. Instead of repetitive clicks in constantly changing applications, scripts handle the work. That shift is difficult for many organizations, especially in the SME sector. Digitalization is often reduced to replicating analog processes in digital form, while ignoring decades of progress.

Screenshot of BookStack used as an ISMS

In many organizations, an ISMS is still treated like traditional office work. It is not. It is not a static collection of files. It is a living system. It needs to evolve continuously and ideally scales along with the organization.

A few years ago, I wrote on this blog that digitalization without versioning is a strong indicator of failure.¹⁵

Best regards,
Tomas Jakobs

Update from 2026-03-08

Thanks for the many responses and questions that came in shortly after publication. I was pleasantly surprised and addressed them in this update.

Handling multiple files

Most questions were about working with multiple documents. I addressed this in an updated makefile, which iterates over all .md files in the /src directory and generates PDFs using Pandoc.

Additional document: Remote access agreement

To make things clearer, I added a second document from my own collection, a typical remote access agreement for external parties.¹⁶

Customizing and overriding the default LaTeX template

Another question was how to adjust properties of the default LaTeX template.

The simple answer: use an additional file. For the risk matrix in landscape format, the document now consists of two parts: the .md file and a .custom.tex file.

The default LaTeX template uses A4 portrait, so the second document, the remote access agreement, does not require its own .custom.tex.

As a result, I moved the default template into a separate /assets directory in the repository and regenerated the risk matrix document.¹⁷

pdfcpu as post-processor

Another question: how to integrate the PDF form automation I recently described at Heise?¹⁸ Would forms still need to be created manually?

Pdfcpu works in both directions. It can read and generate forms. The approach is different and requires form data in a .json file.

Similar to the .custom.tex override, the workflow now optionally checks for a .pdfcpu.json file that defines form fields. After Pandoc generates the PDF, pdfcpu adds the form automatically.

In summary, a document can consist of three parts:

filename.md  
filename.custom.tex (optional)  
filename.pdfcpu.json (optional)  

Front matter

The blog post did not mention front matter properties in Markdown.¹⁹ These are metadata fields that can also act as switches for processing. I have improved the documentation in the repository README.

Update from 2026-03-09

The repository has grown beyond its original scope, so I renamed it and updated the README.

Logic flow of the repository

A new addition is a pre-processor that dynamically injects content into Markdown files. This includes Git version information, database exports from asset management systems, or data from REST APIs.

Update from 2026-04-05

Status update after about a month. I added more front matter, more snippets, and additional features. The repository now covers a complete ISMS according to ISO 27001, including templates for assets, risks, and a Statement of Applicability.

For review processes, recurring events and reminders are generated automatically in a calendar file that can be subscribed to in standard calendar applications. For those who prefer reading documents on eBook readers, OPDS catalog feeds with preview images are also available.

I invested a lot of time in the repository README to document everything clearly. For future updates or additions, check there first.

Have fun!