Skip to content

Markdown Cheatsheet

There are basic markdown features recommended for use in Pulp.

Adding absolute links is enabled by mkdocs-site-urls (learn more here). This is preferred over relative links because of our complex structure. See tradeoffs here

# Template
[My Link](site:{repo-name}/docs/{persona}/{content-type}/some-page.md).

# Example
[My Link](site:pulp-docs/docs/dev/reference/markdown-cheatsheet.md).

# Rendered
[My Link](http://127.0.0.1:8000/pulp-docs/docs/dev/reference/markdown-cheatsheet/).

Tabbed content

Having tabs for alternative content is enabled by mkdocs-material (learn more here). It looks like this:

Example

cat myfile.txt

line1
line2
line3

The basic syntax is:

  • Each tab title must be in quotes
  • Each tab block must have 4 spaces of indent
  • Put space around === "Title"
sample-tabbed-content.md
=== "Run"

    ```bash
    cat myfile.txt
    ```

=== "Output"

    ```bash
    line1
    line2
    line3
    ```

Ordering Files

Ordering is enabled by mkdocs-literate-nav (learn more here).

The basic setup is having a a file in {repo}/docs/{user}/{persona}/_SUMMARY.md. In this file you should use the following syntax:

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)

# Subdirs
* [First list item](some-page.md)
* Subsection title
    * [Foo](subdirectory/foo.md)
    * [Bar](subdirectory/bar.md)

# Recursive Globs
* [I want this first](some-page.md)
* *.md
* [This last and recurse this dir](other/)

Codeblocks

Mkdocs-material comes with builtin support for syntax highlighting in codeblocks. You may use python, bash, yaml, json, yaml and most popular programming languages.

Example

serializer = mymodelserializer(data=data)
serializer.is_valid(raise_exception=true)
instance = serializer.create(serializer.validated_data)
print(instance)

Markdown syntax:

```python
serializer = mymodelserializer(data=data)
serializer.is_valid(raise_exception=true)
instance = serializer.create(serializer.validated_data)
```

The codeblock can also have a title, which is useful if its a file:

Example

sample-title-here.sh
pulp file repository update --name myrepo --retained-versions 1

Markdown syntax:

```bash title="script.sh"
pulp file repository update --name myrepo --retained-versions 1
```

Admonitions

See mkdocs-material

Use them wisely.