Docs: Support markdown

Due to the minimal nature of the initial score commit, the current setup does not support markdown format.
Let's be clear: this was not intentional. It was simply due to the minimal setup.

Now we can actively decide whether we want to introduce markdown in the documentation.
I'd suggest we simply collect Pro and Contra points here in the issue?!
Note: the implementation effort is about 5 minutes.

Contra:

Inconsistent documentation format. People have to use the correct format depending on which file they are editing.
Might require converting existing documentation "back and forth"
We'll need guidelines when to use rst and when to use markdown

Pro:

It's much simpler for simple files, like HowTo manuals.
It's much more widespread / known on the internet / on GitHub and therefore the syntax is familiar to most people.
The syntax is trivial.
We use markdown to write issues and pull requests.

Same:

GitHub supports preview for both formats

Example

Markdown

# Docs-As-Code HowTo

## Introduction

This document describes how to write and publish documentation using the Docs-As-Code approach.

## Diagrams

There are several supported ways to create diagrams in Docs-As-Code.
Each has its own strengths and weaknesses.

### Draw.io

Draw.io can be used to create diagrams in a graphical editor.
The diagrams are rendered as images in the documentation.

The easiest way to use Draw.io is to create a new file in VS Code and use the Draw.io extension.
The new file must be named with the `.drawio.svg` extension.

You can use them inline in markdown files like this:
\```markdown
![Example Diagram](example.drawio.svg)
\```

Which will render like this:

![Example Diagram](assets/docs-as-code/example.drawio.svg)

### PlantUML

PlantUML can be used to create diagrams in a text-based format.
The diagrams are rendered as images in the documentation.

You can use them inline in markdown files like this:
<<<TODO>>>

rST

Docs-As-Code HowTo
==================

Introduction
------------

This document describes how to write and publish documentation using the Docs-As-Code approach.

Diagrams
--------

There are several supported ways to create diagrams in Docs-As-Code.
Each has its own strengths and weaknesses.

Draw.io
~~~~~~~

Draw.io can be used to create diagrams in a graphical editor.

The diagrams are rendered as images in the documentation.

The easiest way to use Draw.io is to create a new file in VS Code and use the Draw.io extension.
The new file must be named with the `.drawio.svg` extension.

You can use them inline in markdown files like this:

.. code-block:: rst

   .. image:: assets/docs-as-code/example.drawio.svg
      :alt: Example Diagram

Which will render like this:

.. image:: assets/docs-as-code/example.drawio.svg
   :alt: Example Diagram

PlantUML
~~~~~~~~

PlantUML can be used to create diagrams in a text-based format.
The diagrams are rendered as images in the documentation.

You can use them inline in markdown files like this:
<<<TODO>>>

I'm for sure in favor of markdown exactly because of it's simplicity and widespread syntax knowledge, but the issue with the two file types you mentioned might be confusing for contributors.

Then the question is how often are "How-To's" written in comparison with other document types that should be in rst.

One use case for Markdown would be: Templates for PRs and Issues.
We are thinking about including review checklists in PRs in form of PR Templates for instance having the requirements checklist already included in the PR as soon as a requirement should be reviewed.
This checklist should somehow also appear in our documentation so that we can link against it. Im not sure if it is possible to realize Github Templates as rst files but the Github Documentation only showed some markdown examples.

If we could not include this template.md file in our documentation we would have to copy it in an rst file which would give us duplicated content.

@AlexanderLanin

@AlexanderLanin Should we now implement this via MyRst here so we can start also including the 'dev documentation' in the final build?

@MaximilianSoerenPollak

@MaximilianSoerenPollak yeah, let's do that.

Markdown is supported in docs-as-code now.

Navigation Menu

Repository navigation

Docs: Support markdown #156

Example

Markdown

rST

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Docs: Support markdown #156

Description

Activity

AlexanderLanin commented on Jan 13, 2025

Example

Markdown

rST

MaximilianSoerenPollak commented on Jan 14, 2025

hoe-jo commented on Jan 17, 2025

MaximilianSoerenPollak commented on Feb 25, 2025

AlexanderLanin commented on Feb 26, 2025

MaximilianSoerenPollak commented on Jun 5, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions