Add documentation for ordering and improve cheatsheet style

staging_docs/dev/reference/markdown-cheatsheet.md

@@ -4,147 +4,132 @@ There are basic markdown features recommended for use in Pulp.
 
 ### Internal links
 
-=== "Template"
+Adding absolute links is enabled by `mkdocs-site-urls`
+(learn more [here](https://github.com/octoprint/mkdocs-site-urls)).
+This is preferred over *relative* links because of our complex structure. See tradeoffs [here](https://github.com/pulp/pulp-docs/issues/2)
 
-    ```markdown
-    [My Link](site:{repo-name}/docs/{persona}/{content-type}/some-page.md).
-    ```
-
-=== "Sample"
+```markdown
+# Template
+[My Link](site:{repo-name}/docs/{persona}/{content-type}/some-page.md).
 
-    ```markdown
-    [My Link](site:pulp-docs/docs/dev/reference/markdown-cheatsheet.md).
-    ```
+# Example
+[My Link](site:pulp-docs/docs/dev/reference/markdown-cheatsheet.md).
 
-=== "Sample Rendered"
+# Rendered
+[My Link](http://127.0.0.1:8000/pulp-docs/docs/dev/reference/markdown-cheatsheet/).
+```
 
-    ```markdown
-    [My Link](http://127.0.0.1:8000/pulp-docs/docs/dev/reference/markdown-cheatsheet/).
-    ```
+### Tabbed content
 
-- This is enabled by [mkdocs-site-urls](https://github.com/octoprint/mkdocs-site-urls) plugin.
-- This is preferred over *relative* links because of our complex structure. See tradeoffs [here](https://github.com/pulp/pulp-docs/issues/2)
+Having tabs for alternative content is enabled by mkdocs-material
+(learn more [here](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#usage)).
+It looks like this:
 
+!!! example
 
-### Codeblocks
+    === "Run"
 
+        ```bash
+        cat myfile.txt
+        ```
 
-=== "Raw"
+    === "Output"
 
-    ````
-    ```
-    <location "/pulp/api/v3/foo_route">
-    proxypass /pulp/api http://${pulp-api}/pulp/api
-    proxypassreverse /pulp/api http://${pulp-api}/pulp/api
-    requestheader set foo "asdf"
-    </location>
-    ```
-    ````
+        ```bash
+        line1
+        line2
+        line3
+        ```
 
-    ---
+The basic syntax is:
 
-    ```
-    <location "/pulp/api/v3/foo_route">
-    proxypass /pulp/api http://${pulp-api}/pulp/api
-    proxypassreverse /pulp/api http://${pulp-api}/pulp/api
-    requestheader set foo "asdf"
-    </location>
-    ```
-
-=== "Python Language"
-
-    ````
-    ```python
-    serializer = mymodelserializer(data=data)
-    serializer.is_valid(raise_exception=true)
-    instance = serializer.create(serializer.validated_data)
-    ```
-    ````
+- Each tab title must be in quotes
+- Each tab block must have 4 spaces of indent
+- Put space around `=== "Title"`
 
-    ---
+```` title="sample-tabbed-content.md"
+=== "Run"
 
-    ```python
-    serializer = mymodelserializer(data=data)
-    serializer.is_valid(raise_exception=true)
-    instance = serializer.create(serializer.validated_data)
+    ```bash
+    cat myfile.txt
     ```
 
-=== "Python REPL"
+=== "Output"
 
-    ````
-    ```python
-    >>> serializer = mymodelserializer(data=data)
-    >>> serializer.is_valid(raise_exception=true)
-    >>> instance = serializer.create(serializer.validated_data)
-    Some output
+    ```bash
+    line1
+    line2
+    line3
     ```
-    ````
+````
 
-    ---
 
-    ```python
-    >>> serializer = mymodelserializer(data=data)
-    >>> serializer.is_valid(raise_exception=true)
-    >>> instance = serializer.create(serializer.validated_data)
-    Some output
-    ```
+### Ordering Files
 
-=== "With 'Title'"
+Ordering is enabled by `mkdocs-literate-nav`
+(learn more [here](https://oprypin.github.io/mkdocs-literate-nav/reference.html)).
 
-    ````
-    ```bash title="script.sh"
-    pulp file repository update --name myrepo --retained-versions 1
-    ```
-    ````
+The basic setup is having a a file in `{repo}/docs/{user}/{persona}/_SUMMARY.md`. 
+In this file you should use the following syntax:
 
-    ---
+```markdown title="pulp_rpm/docs/user/guides/_SUMMARY.md"
+# Basic
+* [First list item](z-page.md)
+* [Second list item](m-page.md)
+* [Third list item](a-page.md)
 
-    ```bash title="script.sh"
-    pulp file repository update --name myrepo --retained-versions 1
-    ```
+# Subdirs
+* [First list item](some-page.md)
+* Subsection title
+    * [Foo](subdirectory/foo.md)
+    * [Bar](subdirectory/bar.md)
 
-### Tabbed content
+# Recursive Globs
+* [I want this first](some-page.md)
+* *.md
+* [This last and recurse this dir](other/)    
+```
 
+### Codeblocks
 
-<div class="grid" markdown>
+Mkdocs-material comes with builtin support for syntax highlighting in codeblocks.
+You may use `python`, `bash`, `yaml`, `json`, `yaml` and most popular programming languages.
 
-````
-=== "Run"
+!!! example
 
-    ```bash
-    cat myfile.txt
+    ```python
+    serializer = mymodelserializer(data=data)
+    serializer.is_valid(raise_exception=true)
+    instance = serializer.create(serializer.validated_data)
+    print(instance)
     ```
 
-=== "Output"
+Markdown syntax:
 
-    ```bash
-    line1
-    line2
-    line3
-    ```
+````
+```python
+serializer = mymodelserializer(data=data)
+serializer.is_valid(raise_exception=true)
+instance = serializer.create(serializer.validated_data)
+```
 ````
 
-=== "Run"
+The codeblock can also have a title, which is useful if its a file:
 
-    ```bash
-    cat myfile.txt
-    ```
+!!! example
 
-=== "Output"
-
-    ```bash
-    line1
-    line2
-    line3
+    ```bash title="sample-title-here.sh"
+    pulp file repository update --name myrepo --retained-versions 1
     ```
 
-</div>
-
-- [See mkdocs-material](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#usage)
-- Each tab title must be in quotes
-- Each tab block must have 4 spaces of indent
-- Put space around `=== "Title"`
+Markdown syntax:
 
+````
+```bash title="script.sh"
+pulp file repository update --name myrepo --retained-versions 1
+```
+````
+
 ### Admonitions
 
 [See mkdocs-material](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types)