Writing tips for MkDocsλ︎
Making the docs more engaging using the mkdocs-material theme reference guide
Configuring Colors
Material for MkDocs - Changing the colors lists the primary and accent colors available.
HSL Color Picker for codes to modify the theme style, overriding colors in docs/assets/stylesheets/extra.css
Hypertext linksλ︎
Links open in the same browser window/tab by default.
Add {target=_blank}
to the end of a link to configure opening in a new tab
Buttonsλ︎
Convert any link into a button by adding {.md-button}
class names to end of the markdown for a link, which uses .md-button-primary
by default. Include target=_blank
for buttons with links to external sites.
Or specify a different class
Add an icon to the button
Practicalli Issues Practicalli Blog
[:fontawesome-brands-github: Practicalli Issues](http://practical.li/blog){ .md-button .md-button-primary }
[:octicons-heart-fill-24: Practicalli Blog](http://practical.li/blog){ .md-button .md-button-primary }
YouTube videoλ︎
Use an iframe element to include a YouTube video, wrapping in a paragraph tag with center alignment to place the video in a centered horizontal position
<p style="text-align:center">
<iframe width="560" height="315" src="https://www.youtube.com/embed/rQ802kSaip4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</p>
mkdocs material does not have direct support for adding a YouTube video via markdown.
Admonitionsλ︎
Note
Use !!!
followed by NOTE
Adding a title
Use !!!
followed by NOTE
and a "title in double quotes"
Shh, no title bar just the text...
Use !!!
followed by NOTE
and a ""
empty double quotes
Abstract
Use !!!
followed by ABSTRACT
Info
Use !!!
followed by INFO
Tip
Use !!!
followed by TIP
Success
Use !!!
followed by SUCCESS
Question
Use !!!
followed by QUESTION
Warning
Use !!!
followed by WARNING
Failure
Use !!!
followed by FAILURE
Danger
Use !!!
followed by DANGER
Bug
Use !!!
followed by BUG
Example
Use !!!
followed by EXAMPLE
Quote
Use !!!
followed by QUOTE
Collapsing admonitionsλ︎
Note
Collapse those admonitions using ???
instead of !!!
Replace with a title
Use ???
followed by NOTE
and a "title in double quotes"
Expanded by default
Use ???+
, note the +
character, followed by NOTE
and a "title in double quotes"
Inline blocksλ︎
Inline blocks of text to make a very specific callout within text
Info
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
Adding something to then end of text is probably my favourite
Info
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
Code blocksλ︎
Code blocks include a copy icon automatically
Syntax highlighting in code blocks
(defn my-function ; Write a simple function
"With a lovely doc-string"
[arguments]
(map inc [1 2 3]))
Give the code block a title using title=""
after the backtics and language name
(defn my-function
"With a lovely doc-string"
[arguments]
(map inc [1 2 3]))
We all like line numbers, especially when you can set the starting line
src/practicalli/gameboard.clj | |
---|---|
Add linenums=42
to start line numbers from 42 onward
Annotationsλ︎
Annotations in a code block help to highlight important aspects. Use the comment character for the language followed by a space and a number in brackets
For example, in a shell code block, use # (1)
where 1 is the number of the annotation
Use a number after the code block to add the text for the annotation, e.g. 1.
. Ensure there is a space between the code block and the annotation text.
- I'm a code annotation! I can contain
code
, formatted text, images, ... basically anything that can be written in Markdown.
Code blocks with annotation, add !
after the annotation number to suppress the #
character
(defn helper-function
"Doc-string with description of function purpose" ; (1)!
[data]
(merge {:fish 1} data)
)
- Always include a doc-string in every function to describe the purpose of that function, identifying why it was added and what its value is.
GitHub action example with multiple annotations
name: ci # (1)!
on:
push:
branches:
- master # (2)!
- main
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: 3.x
- run: pip install mkdocs-material # (3)!
- run: mkdocs gh-deploy --force
-
You can change the name to your liking.
-
At some point, GitHub renamed
master
tomain
. If your default branch is namedmaster
, you can safely removemain
, vice versa. -
This is the place to install further [MkDocs plugins] or Markdown extensions with
pip
to be used during the build:
Highlight lines in code blocksλ︎
Add highlight line meta data to a code block after the opening backticks and code block language.
hl_lines="2"
highlights line 2 in the codeblock
Embed external filesλ︎
--8<--
in a code block inserts code from a source code file or other text file
Specify a local file from the root of the book project (the directory containing mkdocs.yml)
Practicalli Project Templates
Code example reuse
Use an embedded local or external file (URL) when the same content is required in more than one place in the book.
An effective way of sharing code and configuration mutliple times in a book or across multiple books.
Content tabsλ︎
Create in page tabs that can also be
Setting up a project
Or nest the content tabs in an admonition
Diagramsλ︎
Neat flow diagrams
Diagrams - Material for MkDocs
graph LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];
UML Sequence Diagrams
sequenceDiagram
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
state transition diagrams
stateDiagram-v2
state fork_state <<fork>>
[*] --> fork_state
fork_state --> State2
fork_state --> State3
state join_state <<join>>
State2 --> join_state
State3 --> join_state
join_state --> State4
State4 --> [*]
Class diagrams - not needed for Clojure
Entity relationship diagrams are handy though
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
LINE-ITEM {
customer-name string
unit-price int
}
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
Keyboard keysλ︎
Represent key bindings with Keyboard keys. Each number and alphabet character has their own key.
- 1
++1++
for numbers - l
++"l"++
for lowercase character - U
++u++
for uppercase character or++"U"++
for consistency
Punctionation keys use their name
- Space
++spc++
- ,
++comma++
- Left
++arrow-left++
For key sequences, place a space between each keyboard character
- Space g s
++spc++ ++"g"++ ++"s"++
For key combinations, use join they key identifies with a +
- Meta+X
++meta+x++
- Ctrl+Alt+Del
++ctrl+alt+del++
MkDocs keyboard keys reference
Imagesλ︎
Markdown images can be appended with material tags to set the size of the image, whether to appear on light or dark theme and support lazy image loading in browsers
{style="height:150px;width:150px"}
specifies the image size
{loading=lazy}
specifies an image should lazily load in the browser
{aligh=left}
or {aligh=right}
specifies the page alignment of an image.
![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right}
![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
![Kitty Logo](image/kitty-light.png#only-dark)
or ![Kitty Logo](image/kitty-light.png#only-light)
specifies the theme the image should be shown, allowing different versions of images to be shown based on the theme.
![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){style="height:150px;width:150px"}
![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){style="height:150px;width:150px"}
Requires the color pallet toggle
Alight right, lazy load and set image to 150x150
![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right loading=lazy style="height:64px;width:64px"}
![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right loading=lazy style="height:64px;width:64px"}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
Listsλ︎
Task lists
- Lorem ipsum dolor sit amet, consectetur adipiscing elit
- Vestibulum convallis sit amet nisi a tincidunt
- In hac habitasse platea dictumst
- In scelerisque nibh non dolor mollis congue sed et metus
- Praesent sed risus massa
- Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
Task List example
- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
- [ ] Vestibulum convallis sit amet nisi a tincidunt
* [x] In hac habitasse platea dictumst
* [x] In scelerisque nibh non dolor mollis congue sed et metus
* [ ] Praesent sed risus massa
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
Tooltipsλ︎
The humble tool tip
with references
Icon tool tip with a title
Abreviationsλ︎
The HTML specification is maintained by the W3C.
[HTML]: Hyper Text Markup Language [W3C]: World Wide Web Consortium
Magic linksλ︎
MagicLink can auto-link HTML, FTP, and email links. It can auto-convert repository links (GitHub, GitLab, and Bitbucket) and display them in a more concise, shorthand format.