WikiTraccs for Markdown
Power Your Enterprise Knowledge with Markdown in a Single Point of Truth
With an authoritative Markdown repository, you break free from third-party constraints and their ongoing costs and changes, keeping complete control over your documentation.
If you have any of the following goals, this topic is for you:
- CUT COSTS—reduce licensing costs for third-party services like Atlassian Confluence
- CUT COMPLEXITY—reduce the number of in-house CMS deployments for documentation and knowledge management
- BE INTEROPERABLE—facilitate data exchange, e.g. with translation service
- BE FLEXIBLE—swap tools and third-party services used to maintain and publish documentation and knowledge with reduced effort
- BE AI-READY—maintain documentation in a format that AI can natively understand
WikiTraccs for Markdown is your tool of choice to publish Markdown files to SharePoint Online and to make them accessible for broader audiences.
Strategy Shift to Text Files and Markdown
What is Markdown?
Markdown is a simple text format that uses symbols (like # or *) to make text look nicely formatted. It’s an easy way to add headings, bold text, and links without using complicated code.Learn more about the shift to text-based documentation in the Strategy Shift to Text Files and Markdown article.
Learn more about what’s possible with text files in the Markdown-Based Repository article.
And finally, join the waitlist for WikiTraccs for Markdown to start publishing to SharePoint Online.
Markdown to SharePoint Samples
WikiTraccs for Markdown creates SharePoint pages from your Markdown files:
%%{
init: {
'theme': 'neutral',
'architecture': {
'iconSize': 80
}
}
}%%
architecture-beta
group markdownrepo(fluent:markdown-20-regular)[Markdown Repository]
service markdown1(fluent:cube-tree-20-regular)[Files and Folders] in markdownrepo
group wikitraccs(fluent:settings-cog-multiple-20-regular)[Publishing]
service markdown2(fluent:cube-tree-20-regular)[Local Copy] in wikitraccs
service wikitraccsapp(fluent:app-generic-20-regular)[WikiTraccs for Markdown] in wikitraccs
wikitraccsapp:L --> R:markdown2
markdown1:R -- L:markdown2
group thirdparties(mdi:microsoft-sharepoint)[Services]
service sharepoint(mdi:microsoft-sharepoint)[SharePoint Online] in thirdparties
wikitraccsapp:R --> L:sharepoint
Sample 1
Here’s an excerpt of the Markdown specification CommonMark, rebuilt as Markdown file, provisioned as SharePoint page:
And here’s the source Markdown file for above page:
+++
id = "1"
+++
# CommonMark
**A strongly defined, highly compatible specification of Markdown.**
## What is Markdown?
It’s a plain text format for writing structured documents.
### Learn Markdown in 60 Seconds
**Markdown** is a simple way to format text that looks great on any device. It doesn’t do anything fancy like change the font size, color, or type — just the essentials, using keyboard symbols you already know.
Use _italic_ and **bold** to format text. [Links](https://www.wikitransformationproject.com) are supported, and so are **images**. Here's a small one:

Use **unordered lists**:
* List
* List
* List
And **ordered lists**:
1. One
2. Two
3. Three
Or **tables**:
|Column 1|Column 2|
|--------|--------|
|Val 1 |Val 2 |
`Code can be written inline.`
For more code you can use code blocks:
```
<html>
<body>
</body>
</html>
```
## Want to experiment with Markdown?
Try the [10 minute interactive tutorial](https://commonmark.org/help/tutorial/) on the CommonMark web site.
## Need more detail?
Refer to [the official CommonMark spec](https://spec.commonmark.org/).
Sample 2
Here’s an excerpt from Microsoft’s Teams Toolkit documentation, rebuilt as Markdown file, provisioned as SharePoint page:
Here’s the Markdown source for above SharePoint page:
+++
id = "2"
+++
# Microsoft Teams Toolkit Overview
Teams Toolkit makes it simple to get started with app development for Microsoft Teams using Microsoft Visual Studio Code.
* Start with a project template for common custom app built for your org (LOB app) scenarios or from a sample.
* Save setup time with automated app registration and configuration.
* Run and debug to Teams directly from familiar tools.
* Smart defaults for hosting in Azure using infrastructure-as-code and Bicep.
* Create unique configurations like dev, test, and prod using the environment features.
_Note: Before you get started, we strongly recommend that you visit [Teams Toolkit v5 Guide](https://aka.ms/teamsfx-v5.0-guide) to learn key features, such as life cycles and actions._

## Available for Visual Studio Code
Teams Toolkit is available for free for Visual Studio Code. For more information about installation and set up, see [Install Teams Toolkit](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/install-teams-toolkit).
|Teams Toolkit| Visual Studio Code |
|-------------|--------------------|
|Installation | Available in the Visual Studio Code Marketplace
|Build with | JavaScript, TypeScript, React, SPFx
## Features
...
Further Documentation
Have a look at the (evolving) documentation on our way to a good Markdown-based knowledge repository:
1 - Strategy Shift to Text Files for Knowledge Repositories
Why Go Back to Text Files?
Corporations are faced with several challenges right now when it comes to internal documentation and knowledge management:
- How to feed information into third-party AI services like Copilot and Atlassian Intelligence?
- How to feed information into privacy-focused in-house AI solutions?
- How to tackle rising costs of third-party tools and services?
- How to prevent vendor lock-in in a changing environment?
One way to tackle all of above issues is to take a step back, cut ties to any tools at all and go back to… text files.
Multiple of my clients who used WikiTraccs to migrate content from Confluence to SharePoint are already implementing or at least considering this as part of a broader strategy.
Their strategy entails:
- Reducing the number of tools and services to reduce operational complexity and cut costs
- Ultimately going to a simpler, slightly more technical, yet proven approach of maintaining information like a source code repository
Usually, there are additional collateral benefits like easier collaboration with a translation agency for multi-lingual pages.
One common implementation of a text file-based documentation approach is the use of Markdown.
The benefits of Markdown are clear:
- AI services and tools understand Markdown very well - they understand it so well that Microsoft created MarkItDown to convert files of any kind into Markdown, to feed it to AI
- Text files can be stored anywhere; a place of choice is something like GitHub, Gitlab, or any other repository that supports collaboration and versioning
- Markdown is supported by a wide range of (free) tools and services, so there is no vendor lock-in
- Markdown is a format suited for data exchange across enterprises
- Markdown can be published on-demand to third-party services like Confluence and SharePoint, while preventing getting locked in with one specific vendor
It’s the latter point - publishing to third parties - where WikiTraccs for Markdown comes into play, as it can publish Markdown files to SharePoint Online.
Preparing for the Change
Switching from an Enterprise wiki like Confluence to text files containing Markdown is a big change.
We look at the feature set that tools like Confluence and SharePoint provide, to then map those to a Markdown-based repository.
Some features will have parity, some will be lost, some might be added again by different third-party tools and solutions.
Users will have the expectation that certain features are available in a knowledge repository - like formatting text, attaching files, restricting access, and so on.
In this article, we assume that third-party tools have features built-in because there is a demand for them. We look at those features and - in a second step - look at what’s possible to do with a Markdown-based knowledge repository to meet user’s demands.
What’s a “Markdown-Based Knowledge Repository”?
This kind of knowledge repository is - at least in the context of WikiTraccs for Markdown - a collection of Markdown files, organized in folders.
The Markdown-based knowledge repository is
- a single point of truth for enterprise documentation
- written in a well documented and well established markup language (Markdown), with broad tool support
- yet independent of any vendor or third-party service, as information is stored in text files
- easily consumable both by humans and machines
- a starting point for publishing content to third-party services like SharePoint Online or Atlassian Confluence
Before jumping right into creating such a repository, we take a step back to look at the typical content types and structure these repositories are usually built of.
Content Types in a Knowledge Respository
Which types of content are there in a knowledge repository?
This list is influenced mainly by looking at the following third party services as those are often used for documentation and knowledge management:
- Atlassian Confluence Enterprise Wiki
- SharePoint Online
Each row in this list below names a content type, describes what that type means, and then maps this abstract content type to specific third-party services.
The list also includes the file-based Markdown Repository we aim to build.
Content Type | Meaning | Confluence | SharePoint Online | Markdown Repository |
---|
Space | A logical container for pages. | space | site | folder |
Page | A wiki page, a page in a PDF document, something textual, might have columns or rows, contains tables, text, images, etc. | page, blog post, whiteboard | modern page | text file (Markdown) |
List | A tabular representation of data, something like a sheet in an Excel file. | database (Confluence Cloud) | list, document library | text file (Markdown) |
Attachment | A file that is associated with a page. | attachments of a page | kind of has page attachments, but often just links to files stored in document libraries | files next to a page’s text file |
Comment | A comment by a user | footer comments, inline comments, attachment comments; all support rich content | page; very very basic nesting and formatting support | ? |
User | A user resource that can be linked to | @-mentions in pages, used in metadata | used in metadata | ? |
All content types have metadata attached, to different extents. At least the author and a timestamp are nearly always available.
Structures of Knowledge Repositories
Let’s look at some approaches to organizing files and folders.
Atlassian Confluence
The structure used by Confluence:
Confluence
├── Space
│ ├── Page
│ └── Page
│ ├── Child Page
│ └── Comments
│ └── Page
│ └── Attachment
│ └── Comments
└── Space
└── ...
SharePoint Online
The structure used by SharePoint Online:
SharePoint Online
├── Site
│ ├── Document Library
| │ ├── Page
| │ └── Page
| │ └── Comments
│ └── Document Library
| │ └── Page Attachment Folder
| │ └── Attachments
| │ └── Page Attachment Folder
| │ └── Attachments
│ └── Document Library
| └── Files
└── Site
└── ...
Note: there are no child pages in SharePoint.
Hugo
Hugo (a Markdown-based static web site generator that powers this very website) uses this structure:
Local File System
├── Section Folder
│ ├── Page
│ └── Page Folder
│ ├── Page
│ ├── Attachments
│ └── Page Folder
│ ├── Page
│ └── Attachments
│ └── Page
└── Section Folder
└── ...
Glossary
In addition to the content types, the following words should be defined:
- content = pages, attachments, comments, etc. - quite everything, except permissions or processes
- files = files in general, can be an attachment, can be an attachment of another page, can be an external file that is being linked to
Access Control in Knowledge Repositories
We again look at the different third-party services.
Atlassian Confluence
Confluence uses the following approach to permission management:
Confluence (access is granted to users and groups)
└── Space (access is granted to users and groups)
└── Page (access can be narrowed down to a subset of users and groups)
└── Child Page (access can be further narrowed down)
Confluence also has the option to grant Anonymous access.
Being granted access to a page grants access to this page’s attachments and comments as well.
SharePoint Online
SharePoint Online
└── Site (access is granted to users and groups)
├── Document Library (access can be changed to a completely different set of users and groups)
│ └── Page (access can be changed to a completely different set of users and groups)
└── Document Library (access can be changed to a completely different set of users and groups)
└── Page Attachment Folder (access can be changed to a completely different set of users and groups)
SharePoint Online allows sharing of pages and attachments with anonymous users using a sharing link. But there is no real anonymous access as Confluence has.
Actions
Users can perform actions on content and structure, based on their permissions.
Possible actions are:
- modify content (create, read, update, delete)
- one user at a time / multiple users at the same time
- using a visual editor / 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”)
- use extensions to enrich content with non-text elements (first-party or third-party)
- export content (e.g. to PDF or Word)
- change permissions on content
Processes
tbd
Next reading
Now that we know what’s in a repository, we can apply that knowledge and build our Markdown-based knowledge repository: Markdown Repository Specifics.
2 - 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.
to be continued...
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
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
to be continued...