Styling Samples¶

Zensical natively supports a wide collection of Python Markdown and pymdownx extensions out-of-the-box, alongside custom Zensical-specific features. On this page you can find what they do and how to use them in your markdown. Also see the Python Markdown Extensions reference.

Markdown Quick Reference¶

Format	Example	Result
Insert newline	L1<space><space>L2	L1
		L2
Italic	`_Italic_` or `Italic`	Italic
Bold	`__Bold__` or `Bold`	Bold
Superscript	`H^2^O`	H²O
Subscript	`CH~3~CH~2~OH`	CH₃CH₂OH
Underline	`^^underlined^^`	underlined
Strikeout	`~~deleted~~`	~~deleted~~
Highlight	`==HIGHLIGHT==`	HIGHLIGHT
Emoji	`:smile:`
Monospaced/Code	`echo “Hello”`	`echo "Hello"`
Code Highlighting	`:::bash echo “Hello”`	`echo "Hello"`
Keyboard Keys	`++ctrl+alt+h++`	`Ctrl`+`Alt`+`H`
URL Link	`[Link Title](https://example.langley.stream:4443/)`	Link Title

Emoji support¶

The current configuration uses GitHub’s open source emoji solution, it converts emojis to .png images.

Emoji	Syntax	Name
	:smile:	Smile
	:link:	Link
	:bulb:	Bulb
	:bike:	Bike
	:grin:	Grin

References¶

Icons & emojis for mkdocs-material

EmojiCopy

Emojipedia

Emoji List v12.0

Video: How To Use Emojis and Icons In Material for MkDocs

Examples¶

I like to have a beer or two from time to time.

I like to have a beer or two :beers: from time to time.

Emoji through single Unicode 😊 (😊)

Person playing waterpolo, multi Unicode: 🤽‍♂️ (🤽‍♂️)

Person playing waterpolo with block of beige (&#x1F3FC): 🤽‍♂️🏼 (🤽‍♂️🏼)

About the Skin Tone Modifier

The HTML character code ‘&#x1F3FC’ represents the Emoji Modifier Fitzpatrick Type-3, which is a medium-light skin tone modifier used to change the skin color of human and body-part emojis.

Name: Fitzpatrick Type-3

Tone: Medium-light skin tone

Usage: Combined with emojis like thumbs-up or hands to show skin color

Sane lists¶

Enable:

zensical.toml

[project.markdown_extensions]
sane_lists = {}

With sane_lists enabled lists can start with another number rather than with 1:

third item
fourth item
fifth item

Note: The style attributes applied in this example are optional.

3. third item
{: style="color: teal;"}
4. fourth item
{: style="color: red;"}
5. fifth item
{: style="color: blue;"}

Code block¶

Format¶

Use three backticks to start and end the code block. Specify code language by placing the appropriate language identifyer code on the same line, to the right of the backtics. Add a title to the head of the block: title="My Code Title". Show line numbers in the left column by adding linenums="1" after the language code or title.

Language identifyer code¶

Here are the most common language identifyer codes:

Web Development: html, css, javascript (or js), typescript (or ts), json
Programming: python (or py), java, c, cpp (for C++), csharp (or cs), go, rust, ruby (or rb), php
Data & Configuration: yaml (or yml), toml, xml, csv, ini, sql
Shell & DevOps: bash, sh, zsh, powershell (or ps1), dockerfile (or docker), makefile
Text: markdown (or md)
Use plaintext (or text, txt) to completely turn off syntax highlighting.

PHP example¶

code_test.php
<?php
# Function to add two numbers
function add_em_up ( $a, $b ) {
    return $a + $b;
}

# Example usage
$a = 53.67;
$b = 22;
$result = add_em_up ( $a, $b );
echo "$a + $b : $result\n";

/*
Result:
53.67 + 22 : 75.67
*/
?>

This is the markdown that created the PHP code block above:

```php linenums="1" title="code_test.php"
<?php
# Function to add two numbers
function add_em_up ( $a, $b ) {
    return $a + $b;
}

# Example usage
$a = 53.67;
$b = 22;
$result = add_em_up ( $a, $b );
echo "$a + $b : $result\n";

/*
Result:
53.67 + 22 : 75.67
*/
?>
```

JSON example¶

{
  "@type": "ResourceActionRequest",
  "id": "9e89ebfc-8736-4980-a026-ade761255295",
  "iconId": "5fccca72-4b09-41b6-a216-da10f388e352_icon",
  "version": 5,
  "requestNumber": 740489,
  "state": "SUCCESSFUL",
  "description": "Called via API",
  "reasons": null,
  "requestedFor": "tenant",
  "requestedBy": "tenant,
  "organization": {
    "tenantRef": "TenantName",
    "tenantLabel": "TenantName",
    "subtenantRef": "50b0bc4b-a1c5-42a9-9288-e035ea8407ba",
    "subtenantLabel": "TenantName"
}
  …

This is the markdown that created the JSON code block above:

```json
{
  "@type": "ResourceActionRequest",
  "id": "9e89ebfc-8736-4980-a026-ade761255295",
  "iconId": "5fccca72-4b09-41b6-a216-da10f388e352_icon",
  "version": 5,
  "requestNumber": 740489,
  "state": "SUCCESSFUL",
  "description": "Called via API",
  "reasons": null,
  "requestedFor": "tenant",
  "requestedBy": "tenant,
  "organization": {
    "tenantRef": "TenantName",
    "tenantLabel": "TenantName",
    "subtenantRef": "50b0bc4b-a1c5-42a9-9288-e035ea8407ba",
    "subtenantLabel": "TenantName"
}
  …
```

Highlight specific lines¶

Specific lines can be highlighted by passing the line numbers to the hl_lines argument placed right after the language identifier.

Example:

```python hl_lines="3 4"
""" Bubble sort """
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

Result:

""" Bubble sort """
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Embedded inline code¶

Embedded inline code looks like inline code when you surround the text with backticks (grave accent): `inline code`.

Highlight inline text¶

Highlight some text by using ==some text==.

The HTML tag also works: <mark>some text</mark> yields some text.

Keys¶

A key or combination of key presses is surrounded by ++ with each key press separated with a single +.

Enable rendering of keyboard shortcuts:

zensical.toml

[project.markdown_extensions]
pymdownx.keys = {}

Example:

++ctrl+alt+del++

Result:

Ctrl+Alt+Del

SmartSymbols¶

The SmartSymbols extension converts markdown notation into special characters in the HTML.

Enable rendering of smart symbols:

zensical.toml

[project.markdown_extensions]
pymdownx.smartsymbols = {}

Examples:

Markdown	Result
`(tm)`	™
`(c)`	©
`(r)`	®
`+/-`	±
`-->`	→
`<--`	←
`<-->`	↔
`=/=`	≠
`1/4`, etc.	¼, etc
`1st`, `2nd` etc.	1^st, 2^nd etc.

Tasklist¶

Checkbox style lists:

Markdown:

- [x] First item
- [ ] and another
    - [x] another
    {: style="color: teal;"}
    - [ ] even more
- [x] and this is the last item

Strikethrough¶

You can use ~~some text~~ to strike through ~~some text~~.

Resizing images¶

See Google AI: mkdocs Resizing images

Enable the attribute list extension:

zensical.toml

[project.markdown_extensions]
attr_list = {}

This allows you to define custom width, height, or CSS styles directly next to your Markdown image syntax, e.g.:

![alt text](image-url){: style="height:150px; width:150px;"}

Example:

Markdown:

:grin:{: style="height:150px; width:150px;"}

Footnotes¶

Here’s a sentence with a short footnote. ¹

Here’s a sentence with a multi-line footnote. ²

Markdown:

Here's a sentence with a short footnote. [^1]

[^1]: This is footnote 1.

Here's a sentence with a multi-line footnote. [^2]

[^2]:
    This is footnote 2. 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.

Superscript & subscript¶

Use either HTML or markdown to style superscript and subscript.

2³ = 8

2<sup>3</sup> = 8 [HTML]

2³ = 8

2^3^ = 8 [markdown]

H₂O

 H<sub>2</sub>O [HTML]

H₂O

 H~2~O [markdown]

Monospaced text¶

To be sure every character takes the same amount of space on a line use a monospace font. Surround monospaced text with single blackslashes:

This is `monospaced text` embedded in a line.

This is monospaced text embedded in a line.

Horizontal Rule¶

There are three equivalent markdown specifiers for a horizontal rule:

`___` [3 underscore characters]

`---` [3 dash characters]

`***` [3 asterisk characters]

The default is a barely visible 1px line. Change it globally by adding an extra css rule:

File: docs/stylesheets/extra.css

hr {
  height: 4px; 
  border-width: 0; 
  background-color: var(--md-default-fg-color--lighter);
}

/* Note: Using Zensical's built-in CSS variables like 
--md-default-fg-color--lighter 
ensures your line color adjusts nicely when switching 
between light and dark color schemes. 
*/

Google “Zensical’s built-in CSS variables” for a list.

Use HTML instead of markdown in order to apply inline style to a single <hr> block:

<hr style="height: 3px; border-width: 0; background-color: teal">

Content Tabs¶

Ref:
Grouping code blocks
Code blocks

The Tabbed extension allows the usage of content tabs, a simple way to group related content and code blocks under accessible tabs. Enable these extensions:

zensical.toml

[project.markdown_extensions]
pymdownx.superfences = {}
pymdownx.tabbed.alternate_style = true

[project.theme]
features = [
  "content.tabs.link",
]

Begin each group of tabbed content with three equal signs (===), folowed by the group’s title in quotes. Indent each line of the tab’s content with four spaces:

markdown

=== "Unordered list"

    * Sed sagittis eleifend rutrum
    * Donec vitae suscipit est
    * Nulla tempor lobortis orci

=== "Ordered list"

    1. Sed sagittis eleifend rutrum
    2. Donec vitae suscipit est
    3. Nulla tempor lobortis orci

=== "Test One"

    ```txt
    test 1
    ```

=== "Test Two"

    ```txt
    test 2
    ```

Unordered listOrdered listTest OneTest Two

Sed sagittis eleifend rutrum
Donec vitae suscipit est
Nulla tempor lobortis orci

Sed sagittis eleifend rutrum
Donec vitae suscipit est
Nulla tempor lobortis orci

test 1

test 2

This is footnote 1. ↩
This is footnote 2 with lots of text. 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. ↩