Welcome to a comprehensive demonstration of Markdown capabilities, designed to stress-test your Hugo theme. This document includes standard Markdown, GitHub Flavored Markdown (GFM) extensions, and elements often supported by various parsers.
Section 1: Basic Text Formatting & Structure
Headings (All Levels)
H2: Major Section
H3: Subsection Heading
H4: Detailed Point
H5: Minor Point
H6: Sub-Minor Detail
This is a standard paragraph of text. It demonstrates how regular prose flows. Markdown allows for simple, human-readable text that can be easily converted to HTML. A paragraph ends when there is a blank line.
This is another paragraph. It shows the separation between blocks of text.
Emphasis & Strong Emphasis
This text is italic or italic.
This text is bold or bold.
This text is bold and italic or bold and italic.
This text has a strikethrough.
Let’s combine them: bold and italic within bold. Or even strikethrough and italic.
Blockquotes
This is a single-level blockquote. It’s often used for citations or important notes.
This is a nested blockquote. Markdown parsers should handle multiple levels.
And another level, just to be thorough. This is back to the first level after some nested content.
Horizontal Rules
A simple line using three hyphens.
Another line, this time with three asterisks.
And one more, using three underscores.
Section 2: Lists & Tasks
Unordered Lists (Nested & Varied Markers)
- First item using an asterisk
- Nested item 1
- Deeply nested item A
- Deeply nested item B
- Nested item 2
- Nested item 1
- Second item using an asterisk
- Another top-level item using a hyphen
- Another nested item
- Yet another deeply nested item
- Another nested item
- A final top-level item using a plus sign
Ordered Lists (Nested & Starting Numbers)
- First ordered item
- Nested ordered item 1
- Nested ordered item 2
- Second ordered item
- Can mix with unordered lists inside!
- Back to ordered within
- Third item
- This is a sub-bullet.
- Fourth item 5. This item explicitly starts with ‘5.’, demonstrating arbitrary starting numbers. 6. The numbering continues automatically.
Task Lists (GitHub Flavored Markdown - GFM)
- Task 1: This task is completed.
- Sub-task A: This sub-task is pending.
- Sub-sub-task 1: Done.
- Sub-sub-task 2: Pending.
- Sub-task B: Completed.
- Sub-task A: This sub-task is pending.
- Task 2: This task is incomplete.
- Task 3: Another incomplete task.
Section 3: Code & Preformatted Text
Inline Code
This is an example of inline code within a sentence. You can include variables, function_calls(), or even <span>HTML tags</span>.
Fenced Code Blocks (Syntax Highlighting)
# Python example
def factorial(n):
if n == 0:
return 1
else:
return n * factorial(n-1)
print(f"Factorial of 5 is: {factorial(5)}")
// JavaScript example
const greet = (name) => {
console.log(`Hello, ${name}!`);
};
greet("World");
<!-- HTML example -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Sample Page</title>
</head>
<body>
<h1>Welcome</h1>
<p>This is an HTML snippet.</p>
</body>
</html>
# Bash example
#!/bin/bash
echo "Current directory:"
pwd
ls -la
This is a plain text block without any specific language highlighting.
It's useful for displaying raw output or general information.
You can include whitespace and special characters like <>& here.
Indented Code Block (Legacy Style)
This is an older style of code block,
indented by four spaces or a tab.
It does not support syntax highlighting.
Section 4: Links, Images & Media
Links
- Inline Link: Visit Google
- Reference-Style Link: Here’s a link to [Wikipedia][1] about Markdown.
- Autolink (URL): https://www.example.com
- Autolink (Email): mailto:[email protected]
- Link with title in reference: [My Blog][blog_link]
- Relative Link: Go to a local page
Images
- Inline Image:
- Reference-Style Image: ![Alt text for a larger image][img_id]
Image with Caption/Figure (often handled by Hugo Shortcodes or specific theme styling)
Even though Markdown doesn’t have native captioning, Hugo themes often render an image immediately followed by a paragraph of text as a captioned figure.
This is a descriptive caption for the image above, demonstrating how themes might style images with accompanying text.
Section 5: Tables
Simple Table
| Header 1 | Header 2 | Header 3 |
|---|---|---|
| Row 1 Col 1 | Row 1 Col 2 | Row 1 Col 3 |
| Row 2 Col 1 | Row 2 Col 2 | Row 2 Col 3 |
| Row 3 Col 1 | Row 3 Col 2 | Row 3 Col 3 |
Table with Alignment
| Left Aligned | Center Aligned | Right Aligned |
|---|---|---|
| Apple | Banana | Cherry |
| Dog | Elephant | Fox |
| Grapes | Honey Dew | Kiwi |
Larger Table with More Content (demonstrates wrapping/scrolling)
| Feature Name | Description | Support Level | Notes |
|---|---|---|---|
| Headings | Hierarchical structure for document organization. | Standard | Up to six levels. |
| Lists | Ordered and unordered lists, including nested structures. | Standard | Can mix list types. |
| Code Blocks | Preformatted text, often with syntax highlighting. | GFM | Fenced code blocks are widely supported. |
| Emphasis | Bold, italic, and strikethrough text styling. | Standard | Italic for emphasis, bold for strong emphasis. |
| Blockquotes | Quoting text, can be nested. | Standard | Good for citations. |
| Images & Links | Embedding visual content and hyperlinking to external or internal resources. | Standard | Inline and reference styles. Alt text is crucial for accessibility. |
| Tables | Structured data presentation in rows and columns. | GFM | Supports alignment. |
| Task Lists | Checkbox lists for managing tasks. | GFM | Popular on GitHub for issue tracking. |
| Front Matter (YAML/TOML) | Metadata for the page (title, date, tags, categories, etc.). | Hugo Specific | Essential for dynamic content generation in static site generators. |
| HTML Passthrough | Ability to embed raw HTML for complex layouts or unsupported Markdown features. | Standard | Allows for greater control, but reduces Markdown’s portability and readability. Use sparingly. |
| Footnotes | Small citations or additional notes at the bottom of the page. | Extension | Syntax varies; [^id] for reference, [^id]: content for definition. |
| Abbreviations | Defining acronyms or short forms with their full meaning. | Extension | Often seen as *[abbr]: full form. |
| Definition Lists | Used for terms and their corresponding definitions. | Extension | Can be structured as Term : Definition. |
| Keyboard Keys | Styling for keyboard input, e.g., <kbd>Ctrl</kbd>+<kbd>C</kbd>. | HTML | Achieved via embedded HTML <kbd> tag. |
| Superscript / Subscript | (x^2), (H_2O). | HTML/Extension | Often requires embedded HTML (<sup>, <sub>) or a MathJax-like renderer. |
| Comments (HTML-style) | <!-- This is a comment --> | HTML | Ignored by browser, but visible in source. Hugo themes might strip them. |
| Emoji (Unicode/Shortcode) | ❤️ or :heart:. | Unicode/GFM | Direct Unicode characters are generally supported. Shortcodes often require a pre-processor. |
Section 6: Miscellaneous & Advanced Elements
Definition Lists (often an extension)
- Term 1
- Definition of the first term, which can span multiple lines if needed.
- Another line of definition for Term 1.
- Term 2
- Definition of the second term.
Footnotes (often an extension)
Here’s some interesting information that requires a footnote.1 You can have multiple footnotes within your document.2
Abbreviations (often an extension, e.g., in Pandoc)
The HTML is widely used for web pages. The CSS styles the web.
HTML Passthrough / Embedded HTML
Markdown parsers generally allow you to embed raw HTML. This is useful for things not directly supported by Markdown syntax, or for specific styling.
This paragraph is styled using inline HTML.
This is content inside a custom HTML div.
You can use any valid HTML.
Emoji
You can use direct Unicode emojis: ✨🚀🎉❤️. Many parsers also support emoji shortcodes (often GFM-style): :smile: :thumbsup: :rocket:
Subscript and Superscript (usually via HTML or MathJax)
For scientific notation: (H_2O) (using HTML <sub>) or (E=mc^2) (using HTML <sup>).
Often, you’d just write H₂O (using Unicode subscript) or E=mc² (using Unicode superscript) or rely on a math rendering library like MathJax, which Hugo can integrate.
Here’s how you’d do it with HTML tags: Water is H2O. The equation is E=mc2.
Keyboard Keys (via HTML)
Press Ctrl+Shift+R to reload without cache.
Citations (often theme-dependent or using shortcodes)
While Markdown doesn’t have a native citation syntax beyond blockquotes, Hugo themes might use shortcodes for structured citations.
< quote author=“Isaac Newton” > If I have seen further than others, it is by standing upon the shoulders of giants. < /quote >
Escaping Markdown Characters
Sometimes you want to display a Markdown character literally instead of having it parsed.
To see an asterisk, use \* instead of just *.
To avoid bolding, use \*\*not bold\*\*.
A literal backtick: `.
Section 7: Hugo Specifics & Front Matter (Already at Top)
The YAML front matter at the very top of this document (--- ... ---) is crucial for Hugo. It defines:
title: The page title.date: Publication date.lastmod: Last modified date.draft: Iftrue, the page won’t be published unless specified.tags: Keywords for the content.categories: Broader classifications.series: For content belonging to a series.authors: Who wrote the content.weight: Used for ordering pages within a section.
This comprehensive .md file should give your Hugo theme a thorough workout! Save it as a .md file (e.g., ultimate-markdown-test.md) in a content directory within your Hugo project (e.g., content/posts/) and let Hugo generate the site.
This is the content of the first footnote. It can contain Markdown formatting too. ↩︎
And this is the second footnote. It might even include a link to external resources. ↩︎