Example markdown extension

_static/css/custom.css

@@ -13,4 +13,32 @@
 
 .wy-table-responsive {
     overflow: visible !important;
+}
+
+
+.wrapper {
+  position: relative;
+  display: inline-block;
+  width: 100%;
+  height: 40px;
+}
+
+.description {
+  width: 95%;
+  text-overflow: clip;
+  display: -webkit-box;
+  overflow: hidden;
+  -webkit-line-clamp: 1;
+  -webkit-box-orient: vertical;
+  height: 40px;
+}
+
+.btn {
+  /* margin: 0; padding: 0 0 0 -30px; */
+  background-color: transparent; border-width: 0; outline-width: 0;
+  font-size: 20px; color: #2f58df;
+  position: absolute;
+  /* bottom: 15px; */
+  right: 5%;
+  cursor: pointer;
 }

_static/js/search.js

@@ -0,0 +1,23 @@
+function searchtable(searchbar_id, table_to_search) {
+// Declare variables
+var input, filter, table, tr, td, i, txtValue, show;
+input = document.getElementById(searchbar_id);
+filter = input.value.toUpperCase();
+table = document.getElementById(table_to_search);
+tr = table.getElementsByTagName("tr");
+// Loop through all table rows, and hide those who don't match the search query
+for (i = 0; i < tr.length; i++) {
+    td = tr[i].getElementsByTagName("td")[0];
+    show = "none";
+    if (td) {
+    for (j = 0; j < tr[i].getElementsByTagName("td").length; j++) {
+        column = tr[i].getElementsByTagName("td")[j];
+        txtValue = column.textContent || column.innerText;
+        if (txtValue.toUpperCase().indexOf(filter) > -1) {
+        show = "";
+        }
+    }
+    tr[i].style.display = show;
+    }
+}
+}

conf.py

@@ -31,16 +31,22 @@
 extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
-    'sphinxcontrib.mermaid'
+    'sphinxcontrib.mermaid',
+    'myst_parser',
+    'sphinx_design', # pip install sphinx-design
+    #maybe needed: pip install sphinxcontrib-plantuml
 ]
 
+# https://myst-parser.readthedocs.io/en/v0.17.1/syntax/optional.html#syntax-admonitions
+myst_enable_extensions = [ "colon_fence" ]
+
 # 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'
@@ -160,6 +166,10 @@
     'css/custom.css',
 ]
 
+html_js_files = [
+    'js/search.js',
+]
+
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.

index.rst

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

md_test1.md

@@ -0,0 +1,264 @@
+(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|
+
+### Searchable tables
+...are to find in {ref}`searchable_table`
+
+## 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 text <md_test2_label2>`.
+
+{ref}`Use label from rst part of docs without underscore _ <apxsct_serverparameters>`.
+
+
+## Admonition
+See [official doc](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html)
+
+Use
+```
+:::{note}
+  Some note
+:::
+```
+to create a note.
+
+:::{note}
+  Some note
+:::
+
+For custom title
+```
+:::{admonition} My custom title
+  :class: note
+
+  My custom note
+:::
+```
+
+:::{admonition} My custom title
+  :class: note
+
+  My custom note
+:::
+
+### Other supported admonitions
+- attention
+- caution
+- danger
+- error
+- hint
+- important
+- note
+- seealso
+- tip
+
+:::{attention}
+  Some attention
+:::
+
+:::{caution}
+  Some caution
+:::
+
+:::{danger}
+  Some danger
+:::
+
+:::{error}
+  Some error
+:::
+
+:::{important}
+  Some important
+:::
+
+:::{tip}
+  Some tip
+:::
+
+:::{note}
+  Some note
+:::
+
+:::{seealso}
+  Some seealso
+:::
+
+Use {func}`spam` instead.
+
+Further reads are [Get started with MyST in Sphinx](https://myst-parser.readthedocs.io/en/v0.17.1/sphinx/intro.html)
+and [MyST - Directives](https://myst-parser.readthedocs.io/en/v0.17.1/syntax/syntax.html#syntax-directives)
+
+# Sphinx Design
+
+Add `sphinx_design` to `extensions` in `conf.py` and install it for python with `pip install sphinx-design`.
+
+[Official doc](https://sphinx-design.readthedocs.io/en/furo-theme/)
+
+This allows to do stuff like e.g. this
+
+## Tabs
+
+```
+::::{tab-set}
+
+:::{tab-item} Label1
+Content 1
+:::
+
+:::{tab-item} Label2
+Content 2
+:::
+
+::::
+```
+
+::::{tab-set}
+
+:::{tab-item} Label1
+Content 1
+:::
+
+:::{tab-item} Label2
+Content 2
+:::
+
+::::
+
+## Dropdowns
+
+```
+:::{dropdown} Dropdown title
+:animate: fade-in-slide-down
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed iaculis arcu vitae odio gravida congue. Donec porttitor ac risus et condimentum. Phasellus bibendum ac risus a sollicitudin. Proin pulvinar risus ac mauris aliquet fermentum et varius nisi. Etiam sit amet metus ac ipsum placerat congue semper non diam. Nunc luctus tincidunt ipsum id eleifend. Ut sed faucibus ipsum. Aliquam maximus dictum posuere. Nunc vitae libero nec enim tempus euismod. Aliquam sed lectus ac nisl sollicitudin ultricies id at neque. Aliquam fringilla odio vitae lorem ornare, sit amet scelerisque orci fringilla. Nam sed arcu dignissim, ultrices quam sit amet, commodo ipsum. Etiam quis nunc at ligula tincidunt eleifend.
+:::
+```
+
+:::{dropdown} Dropdown title
+:animate: fade-in-slide-down
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed iaculis arcu vitae odio gravida congue. Donec porttitor ac risus et condimentum. Phasellus bibendum ac risus a sollicitudin. Proin pulvinar risus ac mauris aliquet fermentum et varius nisi. Etiam sit amet metus ac ipsum placerat congue semper non diam. Nunc luctus tincidunt ipsum id eleifend. Ut sed faucibus ipsum. Aliquam maximus dictum posuere. Nunc vitae libero nec enim tempus euismod. Aliquam sed lectus ac nisl sollicitudin ultricies id at neque. Aliquam fringilla odio vitae lorem ornare, sit amet scelerisque orci fringilla. Nam sed arcu dignissim, ultrices quam sit amet, commodo ipsum. Etiam quis nunc at ligula tincidunt eleifend.
+:::
+
+## Images
+
+Images can be included with `![Alternative title of the image](_static/concept-generic.svg)`.
+
+![Alternative title of the image](_static/concept-generic.svg)
+
+If they need special options (e.g. size) use
+```html
+<img src="_static/concept-generic.svg"
+     alt="Alternative title of the image"
+     style="float: left; width: 50%;" />
+
+```
+
+<img src="_static/concept-generic.svg"
+     alt="Alternative title of te image"
+     style="float: left; width: 50%;" />
+
+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.
+
+## Mermaid graphics
+Can be included with
+
+~~~
+```{mermaid}
+graph LR
+  a --> b
+```
+~~~
+
+```{mermaid}
+graph LR
+  a --> b
+```
+
+## Other Markdown Stuff
+- `*Cursive*` *Cursive*
+- `**Bold**` **Bold**
+- `<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 -->`
+