Markdown Syntax & Shortcodes Guide

This post serves as a reference guide to showcase all the various syntax and formatting options available when writing content for this blog.

1. Headings#

Headings are created using the # symbol. The h1 is automatically populated from the title frontmatter, so you should start with h2 (##) for major sections within your post.

This is an h3 (Sub-heading)#

Use ### for sub-sections.

This is an h4#

And #### for even deeper nesting if absolutely necessary.

2. Text Formatting#

You can format your text in a variety of ways to emphasize certain points:

• Use double asterisks for bold text.
• Use single asterisks or underscores for italic text.
• You can even combine them for bold italics.
• Strikethrough is done using double tildes: this text is crossed out.

3. Inline Code and Code Blocks#

When mentioning a variable, command, or file path in the middle of a sentence, use single backticks for inline-code. For example: “Be sure to edit your config.toml file.”

For larger snippets, use fenced code blocks. Specify the language for proper syntax highlighting:

Bash Example#

#!/bin/bash
echo "Hello, world!"
BACKUP_PATHS=("/mnt/storage" "/home/pankaj/stacks")
for path in "${BACKUP_PATHS[@]}"; do
    echo "Backing up $path..."
done

Python Example#

def fetch_data(url):
    """Fetches data from the given URL."""
    response = requests.get(url)
    return response.json()

4. Links#

Standard links are created using square brackets for the text and parentheses for the URL: Visit my GitHub profile

5. Lists#

Unordered Lists#

You can use - or * for bulleted lists:

• First item
• Second item
  • Nested item A
  • Nested item B
• Third item

Ordered Lists#

Use numbers followed by a period:

1. First step
2. Second step
3. Final step

6. Blockquotes#

To quote text from another source or highlight an excerpt, use the > symbol:

“Simplicity is the ultimate sophistication.”

• Leonardo da Vinci

7. Tables#

Markdown tables are great for structured data:

8. Images and GIFs#

There are four main ways to add images depending on your needs.

Method A: Standard Markdown Image#

The simplest way to embed an image or a GIF:

Method B: Image with Caption (Zola Shortcode)#

Use the custom img_caption shortcode to beautifully display an image with a caption below it:

Method C: Lightbox Image (Click to Zoom)#

If you want the user to be able to click the image and view it in a full-screen overlay (lightbox), use this raw HTML snippet:

Method D: Image Grid (Side-by-Side Images)#

When you have multiple related images (like progress shots of a homelab build or multiple dashboard screenshots), stacking them vertically takes up too much space. The image-grid class creates a responsive 2-column grid that automatically handles spacing and scales down to a single column on mobile. It even gracefully centers the last image if there is an odd number of photos!

9. Media Embeds (Maps & YouTube)#

Maps (Google Maps / My Maps)#

You can directly embed custom Google Maps or My Maps using the standard HTML iframe snippet. The site will render it inline perfectly:

YouTube Videos#

There are two primary ways to embed YouTube videos that are used across the site.

Method A: Native Embed (Zola Shortcode)#

Use the custom youtube shortcode to embed the full interactive iframe directly into the post:

Method B: Lightweight Image Link#

For better page-load performance, you can use a thumbnail image that links out to the video instead of loading an iframe:

10. Admonitions / Callouts#

Admonitions are custom Zola shortcodes used to highlight important information, warnings, or notes.

11. Code Line Differences#

Zola natively supports diff highlighting in code blocks:

- println("Hello Old World")
+ println("Hello New World! 👋")

12. Mermaid Diagrams#

You can write technical flowcharts directly in Markdown using Mermaid.js syntax:

flowchart TD
    A([📝 Hashnode]) -->|Export Posts| B[60 Markdown Files]
    B -->|AI Asset Rescue| C[(Local Images)]
    B --> D[[Zola Build]]
    C --> D
    D -->|Wrangler Deploy| E([☁️ Cloudflare Edge])

13. Inline HTML Elements#

Because Markdown fully supports raw HTML, you can use semantic tags to enhance your text:

• Abbreviations: HTML is awesome.
• Superscript: E = mc²
• Subscript: H₂O is water.
• Keyboard inputs: Press Ctrl + C to copy.
• Highlighted text: You can highlight important information using the mark tag.

14. Footnotes#

You can add footnotes to your text by using standard markdown footnote syntax. Here is a sentence with a footnote.^[1]
You can also add multiple footnotes in the same document.^[2]

15. Math Rendering (KaTeX)#

You can render mathematical equations cleanly using KaTeX.

For inline equations, wrap your math in single dollar signs: $E=mc^2$.

For block equations, wrap them in double dollar signs:

$$ x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} $$

This concludes the syntax reference guide. Happy writing!

Flush!