This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

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.

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

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:

![Image alt text](https://www.wikitransformationproject.com/assets/logo-32x32.png)

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._

![Illustration shows the User Journey of the Teams Toolkit.](teams-toolkit-user-journey2.png)

## 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 TypeMeaningConfluenceSharePoint OnlineMarkdown Repository
SpaceA logical container for pages.spacesitefolder
PageA wiki page, a page in a PDF document, something textual, might have columns or rows, contains tables, text, images, etc.page, blog post, whiteboardmodern pagetext file (Markdown)
ListA tabular representation of data, something like a sheet in an Excel file.database (Confluence Cloud)list, document librarytext file (Markdown)
AttachmentA file that is associated with a page.attachments of a pagekind of has page attachments, but often just links to files stored in document librariesfiles next to a page’s text file
CommentA comment by a userfooter comments, inline comments, attachment comments; all support rich contentpage; very very basic nesting and formatting support?
UserA user resource that can be linked to@-mentions in pages, used in metadataused 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...

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

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...