Example of how to integrate markdown with rst

Author: HereThereBeDragons

conf.py

@@ -31,16 +31,17 @@
 extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
-    'sphinxcontrib.mermaid'
+    'sphinxcontrib.mermaid',
+    'myst_parser'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+#source_suffix = ['.rst']
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'

index.rst

@@ -51,6 +51,7 @@ Contents
    cpt-containers
    part-advanced
    part-appendix
+   part-md
 
 
 Contact and Authors

md_test1.md

@@ -0,0 +1,97 @@
+(md_test_label1)=
+# Markdown Test
+
+- This [here](https://docs.readthedocs.io/en/stable/guides/migrate-rest-myst.html) is a documentation how to migrate from rst to md
+
+- Most important functionality needed here is listed below
+
+(md_test_label2)=
+## Codesections
+Inline codesection `my code is here` written by using `` around the text
+
+### Codeblocks
+
+Using ``` or ~~~ following the optional code block type (c++, vim, py,...) and a new line. 
+
+~~~
+```vim
+sudo cvmfs_config setup
+
+cvmfs_config chksetup
+--> OK
+```
+~~~
+
+creates
+
+```vim
+sudo cvmfs_config setup
+
+cvmfs_config chksetup
+--> OK
+```
+
+
+(md_test_label3)=
+## Tables
+```
+|Option|Function|
+|---|---|
+|CVMFS_HTTP_PROXY|Proxy setting for repos|
+|CVMFS_QUOTA_LIMIT|Quota in MB of local cvmfs cache|
+```
+
+creates
+
+|Option|Function|
+|---|---|
+|CVMFS_HTTP_PROXY|Proxy setting for repos|
+|CVMFS_QUOTA_LIMIT|Quota in MB of local cvmfs cache|
+
+## Labels
+
+### Reference to a file
+
+`[test](cpt-xcache.rst)` creates [test](cpt-xcache.rst)
+
+### Create custom label
+In markdown
+```
+(md_test_label3)=
+## Tables
+and the normal text follows
+this label style is not a markdown style specific to sphinx
+```
+
+In rst
+```
+.. _apxsct_serverparameters:
+```
+
+### Referencing a custom label
+- Does not dependent if it is in local file or some other part of the documentation
+- Labels must be unique accross all files
+
+In markdown
+```
+{ref}`Use label from this md file<md_test_label3>`.
+{ref}`md_test2_label`.
+{ref}`If using text-based labels you need to provide test <md_test2_label2>`.
+{ref}`Use label from rst part of docs without underscore _ <apxsct_serverparameters>`.
+
+```
+
+{ref}`Use label from this md file<md_test_label3>`.
+
+{ref}`md_test2_label`.
+
+{ref}`If using text-based labels you need to provide test <md_test2_label2>`.
+
+{ref}`Use label from rst part of docs without underscore _ <apxsct_serverparameters>`.
+
+
+## Other Markdown Stuff
+- `<u>something</u>` underline <u>something</u>
+- To comment stuff out within the md file use html comment `< !-- remove the space before the ! for comment section -->`
+
+

md_test2.md

@@ -0,0 +1,11 @@
+(cvmfs_test_title)=
+# Another MD Testfile
+
+Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
+
+(md_test2_label)=
+## Label In Other Markdown File
+Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
+
+(md_test2_label2)=
+My text-only label 

part-md.rst

@@ -0,0 +1,9 @@
+********************
+Markdown Integration
+********************
+
+.. toctree::
+   :maxdepth: 2
+
+   md_test1
+   md_test2