Markdown Usage & Tricks

Principles & Quick Tips ✅

Use two trailing spaces at the end of a line for a hard line break when you want a new line within the same paragraph.
A blank line creates a paragraph break (a visible empty line in the rendered output).
Prefer bold for small section highlights or inline emphasis when you want the text to stand out.
Keep headings shallow—avoid more than three levels (H1, H2, H3) for most articles.
Always add a blank line before a table or a code block to ensure proper rendering.
Use numbered lists only when items are short and contiguous. If each item needs a long explanation, use manual numbers or bold headings for each section instead of relying on automatic incremental numbering.

Line breaks & paragraphs 🔧

Hard line break (same paragraph):

This is a line with two spaces at the end.  
This will render on the next line but in the same paragraph.

Alternative hard break using HTML:

Line one<br>
Line two

Paragraph break (new paragraph):

This is the first paragraph.

This is a new paragraph (visible gap above).

Headings & structure 🏗️

Use H1 for the page title (Hugo handles this via frontmatter). For content, prefer H2 and H3.
Avoid deep nesting; if you need more than three heading levels, consider splitting to a separate page or using subsections within docs.

Example:

## Section (H2)
### Subsection (H3)

Emphasis & small headings ✨

Italic: *italic* or _italic_
Bold: **bold** or __bold__
Inline code: `code`

Tip: Use bold to create short inline headings inside sections when you don’t want an extra header line.

Lists — ordered & unordered ✅

Unordered list:

- Item one
- Item two
  - Subitem

Ordered list (automatic):

1. First
2. Second
3. Third

When list items require long paragraphs between them, don’t rely on automatic numbering. Instead use manual numbers / bold headings:

**1. First item**

Long explanation for the first item...

**2. Second item**

Long explanation for the second item...

Tables 📋

Remember to leave an empty line before the table:

| Column A | Column B |
|----------|----------|
| Row 1    | Row 1    |
| Row 2    | Row 2    |

Alignment examples:

| Left | Center | Right |
|:-----|:------:|------:|
| a    |   b    |     c |

Images & links 🖼️🔗

Images:

![Alt text](/images/photo.png "Optional title")

Hugo shortcode example (recommended for responsive images and captions):


      Caption text

Links (open in same tab by default):

[Link text](https://example.com)

External link tip: For accessibility, include descriptive link text rather than “click here.”

Code blocks & syntax highlighting 💻

Use fenced code blocks and specify a language for highlighting:

# Shell example
hugo server --noHTTPCache -D -w

# Python example
def greet(name):
    print(f"Hello, {name}")

Inline code is for single tokens: git commit -m "message".

Task lists & checkboxes ✅

- [ ] Todo item
- [x] Done item

Footnotes & references ✍️

Basic footnote:

This is a sentence with a footnote.[^1]

[^1]: Footnote text goes here.

Hugo frontmatter tips (SEO & structure) 🔧

Follow your site’s frontmatter conventions. Example frontmatter used in this project:

---
title: "Article title"
description: "Short description for SEO (150-160 chars)."
date: 2025-01-01
author: "Author Name"
categories: ["Category"]
keywords: ["keyword1", "keyword2"]
draft: false
---

Optional: If you use AI-assisted content, include the attribution fields used in this repo (e.g., aiGenerated, aiAssisted, aiTools).

Common mistakes & troubleshooting ⚠️

Forgetting a blank line before a table or code block (renders incorrectly).
Using automatic ordered lists when items have long explanations (breaks flow).
Forgetting to escape special characters in URLs (e.g., _ inside URLs can cause italics).
Not specifying a language for code fences (no syntax highlighting).

Quick reference cheat sheet 🔍

Hard break: two spaces at line end + Enter
Paragraph break: empty line
Code fence: ``` (triple backticks)
Image: ![alt](url "title")
Table: blank line + pipe-delimited rows