Markdown-Based Repository

This article uses language defined in the Strategy Shift article, like content, page, attachment, and so on.

Which Expectations Can Be Met by a Markdown-Based Knowledge Repository?

A Markdown-based knowledge repository solely consists of files and folders. Those are stored somewhere. Tools are used to work with them.

Thus, there are three angles to look at this:

• The first angle is agnostic to the storage location, it focuses on aspects innate to using files and folders - what can we do with those?

• The second angle takes the storage location into account: on Windows the NTFS file system, on a network drive the NFS file system, or some Git-based storage like GitHub. This is relevant for metadata storage, as different storage locations provide a different set of metadata.

• The third angle is tool support. Tools like Visual Studio Code can show a preview of the Markdown file, and tools like WikiTraccs for Markdown can publish to SharePoint Online. Other nice tools are available.

We’ll look at each of those in the following sections.

Files and Folders

The structure might look like this and is based on how Hugo (the static web site generator) organizes its files:

root-folder/
└── spaces/
    ├── space-1/
    │   ├── index.md
    │   ├── page-1.md
    │   └── page-3/
    │       ├── index.md
    │       └── some-image.png
    └── space-2/
        ├── index.md
        ├── page-2.md
        └── page-4/
            ├── index.md
            └── another-image.png

Users can now perform the following actions:

• modify content (create, read, update, delete)
  • one user at a time
  • without a visual editor
• restructure content (e.g. move page to a new parent, create a new space)
• duplicate content
• set metadata on content (e.g. label)
• link to existing content
• link to non-existing content (“red links”)

One word about metadata: Metadata is stored as front matter inside the Markdown files.

Here’s an example Markdown showing the use of front matter:

---
title: "Q4 Release Notes"
author: "Jane Doe"
date: "2024-12-18"
---

# Q4 Release Notes

Our Q4 release streamlines operational workflows and improves data integrity across all departments.

Metadata is set between the first --- and the second --- as key-value pairs. Again, Hugo is one example of the use of front matter.

Storage Locations

Local File System

Content and attachments can be stored locally.

Source Code Repository

Source code repositories like GitHub are perfect for storing pages and tracking changes.

They usually also provide means like commenting, approval workflows etc.

Tool Support

This section is a collection of tools around Markdown, both old and new.

Writing Markdown

• Visual Studio Code supports writing Markdown and previewing Markdown; there are extensions available that improve the editing experience

Converting to Markdown

• Wikifier RT converts rich text copied from Confluence to Markdown
  • old blog post from 2012: How to convert Confluence XML storage format to wiki markup
  • live website: Wikifier RT
• Confluence to Markdown Converter on GitHub

Converting from Markdown / Publishing Markdown

• Hugo is a Markdown-based website builder that converts Markdown to HTML; this very website is written in Markdown and converted to HTML by Hugo

• markdown-to-atlassian-wiki-markup-cli promises to publish Markdown files to Confluence