Markdown Demo & Reference Guide
Markdown Demo & Reference Guide
This page demonstrates all Markdown syntax features available in this Jekyll blog, including basic formatting, images, and Mermaid diagrams.
Basic Markdown Syntax
Headings
All six heading levels are available:
H1 - Main Heading (Level 1)
H2 - Section Heading (Level 2)
H3 - Subsection Heading (Level 3)
H4 - Minor Heading (Level 4)
H5 - Small Heading (Level 5)
H6 - Smallest Heading (Level 6)
Markdown Syntax:
# H1 - Main Heading
## H2 - Section Heading
### H3 - Subsection Heading
#### H4 - Minor Heading
##### H5 - Small Heading
###### H6 - Smallest Heading
Text Formatting
Bold text using double asterisks or double underscores.
Italic text using single asterisks or single underscores.
Bold and italic using triple asterisks.
Strikethrough using double tildes.
Markdown Syntax:
**Bold text** or __Bold text__
*Italic text* or _Italic text_
***Bold and italic***
~~Strikethrough~~
Lists
Unordered Lists
- First item
- Second item
- Third item
- Nested item 1
- Nested item 2
- Fourth item
Markdown Syntax:
- First item
- Second item
- Third item
- Nested item 1
- Nested item 2
- Fourth item
Ordered Lists
- First item
- Second item
- Third item
- Nested numbered item
- Another nested item
- Fourth item
Markdown Syntax:
1. First item
2. Second item
3. Third item
1. Nested numbered item
2. Another nested item
4. Fourth item
Task Lists
- Completed task
- Another completed task
- Incomplete task
- Another incomplete task
Markdown Syntax:
- [x] Completed task
- [ ] Incomplete task
Links
Markdown Syntax:
[Inline link](https://www.example.com)
[Link with title](https://www.example.com "Example Website")
[Reference-style link][reference-link]
[reference-link]: https://www.example.com
Code
Inline Code
Use inline code with backticks for code snippets within text.
Markdown Syntax:
Use `inline code` with backticks
Code Blocks
def hello_world():
print("Hello, World!")
return True
result = hello_world()
function greet(name) {
return `Hello, ${name}!`;
}
console.log(greet("World"));
Markdown Syntax:
```python
def hello_world():
print("Hello, World!")
```
Blockquotes
This is a blockquote. It can span multiple lines.
And include multiple paragraphs.
Nested blockquote:
This is a nested quote inside another quote.
Markdown Syntax:
> This is a blockquote.
> It can span multiple lines.
>
> And include multiple paragraphs.
Horizontal Rules
Markdown Syntax:
---
Tables
| Column 1 | Column 2 | Column 3 |
|---|---|---|
| Row 1 | Data | Info |
| Row 2 | More | Details |
| Row 3 | Even | More |
Alignment:
| Left Aligned | Center Aligned | Right Aligned |
|---|---|---|
| Left | Center | Right |
| Text | Text | Text |
Markdown Syntax:
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1 | Data | Info |
| Left | Center | Right |
|:-----|:------:|------:|
| Left | Center | Right |
Escaping Characters
Use backslash to escape special characters: *asterisk*, `backtick`, #hash
Markdown Syntax:
\*asterisk\*, \`backtick\`, \#hash
Images
Basic Image Syntax
Markdown Syntax:
Images from _pic/ Directory
Images stored in the _pic/ directory can be referenced using /pic/ path (note: no underscore in the path).
Example:
With title/tooltip:
HTML Image Tag (More Control)
For more control over image size and styling:
HTML Syntax:
<img src="/pic/example-image.txt" alt="Example image" width="400" style="border-radius: 8px;">
Responsive Image
<img src="/pic/example-image.txt" alt="Responsive image" style="max-width: 100%; height: auto;">
Image with Caption
HTML Syntax:
<figure>
<img src="/pic/example-image.txt" alt="Example">
<figcaption>Figure 1: Example image with caption</figcaption>
</figure>
Centered Image
HTML Syntax:
<div style="text-align: center;">
<img src="/pic/example-image.txt" alt="Centered image" width="300">
</div>
Mermaid Diagrams
Mermaid diagrams are created using code blocks with mermaid as the language.
Flowchart
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
C --> E[End]
D --> E
Markdown Syntax:
```mermaid
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
```
Sequence Diagram
sequenceDiagram
participant User
participant Browser
participant Server
participant Database
User->>Browser: Enter URL
Browser->>Server: HTTP Request
Server->>Database: Query Data
Database-->>Server: Return Data
Server-->>Browser: HTTP Response
Browser-->>User: Display Page
Markdown Syntax:
```mermaid
sequenceDiagram
participant User
participant Browser
User->>Browser: Enter URL
Browser->>Server: HTTP Request
```
Class Diagram
classDiagram
class Animal {
+String name
+int age
+eat()
+sleep()
}
class Dog {
+String breed
+bark()
}
class Cat {
+String color
+meow()
}
Animal <|-- Dog
Animal <|-- Cat
Markdown Syntax:
```mermaid
classDiagram
class Animal {
+String name
+eat()
}
Animal <|-- Dog
```
State Diagram
stateDiagram-v2
[*] --> Idle
Idle --> Processing: Start
Processing --> Completed: Success
Processing --> Error: Failure
Error --> Idle: Retry
Completed --> [*]
Markdown Syntax:
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Processing: Start
Processing --> Completed: Success
```
Gantt Chart
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Phase 1
Planning :2025-11-01, 7d
Design :2025-11-08, 10d
section Phase 2
Development :2025-11-18, 20d
Testing :2025-12-08, 7d
section Phase 3
Deployment :2025-12-15, 5d
Markdown Syntax:
```mermaid
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Phase 1
Planning :2025-11-01, 7d
```
Pie Chart
pie title Programming Languages Usage
"JavaScript" : 35
"Python" : 25
"Java" : 20
"C++" : 10
"Other" : 10
Markdown Syntax:
```mermaid
pie title Programming Languages Usage
"JavaScript" : 35
"Python" : 25
```
Git Graph
gitgraph
commit id: "Initial"
branch develop
checkout develop
commit id: "Feature A"
commit id: "Feature B"
checkout main
commit id: "Release"
merge develop
commit id: "Hotfix"
Markdown Syntax:
```mermaid
gitgraph
commit id: "Initial"
branch develop
checkout develop
commit id: "Feature A"
```
Entity Relationship Diagram
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
PRODUCT ||--o{ LINE-ITEM : "ordered in"
CUSTOMER {
string name
string email
}
ORDER {
int orderNumber
date orderDate
}
PRODUCT {
string name
float price
}
Markdown Syntax:
```mermaid
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
CUSTOMER {
string name
string email
}
```
Journey Diagram
journey
title User Journey
section Discovery
Visit Website: 5: User
Browse Products: 4: User
section Purchase
Add to Cart: 3: User
Checkout: 5: User
Payment: 4: User
section Post-Purchase
Receive Email: 5: System
Review Product: 4: User
Markdown Syntax:
```mermaid
journey
title User Journey
section Discovery
Visit Website: 5: User
Browse Products: 4: User
```
Combining Elements
Code Block with Mermaid
You can combine code explanations with Mermaid diagrams:
Here’s a flowchart showing a simple decision process:
graph LR
A[Input] --> B{Valid?}
B -->|Yes| C[Process]
B -->|No| D[Error]
C --> E[Output]
D --> F[Log Error]
Image with Description
Here’s an example workflow:
graph TD
A[Start] --> B[Load Image]
B --> C[Process Image]
C --> D[Display Image]
D --> E[End]
And here’s how to reference the image in Markdown:
Quick Reference
Basic Syntax Cheat Sheet
| Element | Syntax | Example |
|---|---|---|
| Heading | # H1 to ###### H6 |
## Heading |
| Bold | **text** |
bold |
| Italic | *text* |
italic |
| Code | `code` |
code |
| Link | [text](url) |
link |
| Image |  |
|
| List | - item or 1. item |
• item |
| Blockquote | > quote |
> quote |
| Table | \| col \| |
Table |
| Horizontal Rule | --- |
— |
Image Path Reference
- Source:
myblog/_pic/image.jpg - Reference:
/pic/image.jpg(no underscore) - Built site:
_site/pic/image.jpg
Mermaid Quick Reference
- Flowchart:
graph TDorgraph LR - Sequence:
sequenceDiagram - Class:
classDiagram - State:
stateDiagram-v2 - Gantt:
gantt - Pie:
pie - Git:
gitgraph - ER:
erDiagram - Journey:
journey
Tips and Best Practices
- Use descriptive alt text for images
- Keep Mermaid diagrams simple for better readability
- Test your syntax before publishing
- Use consistent formatting throughout your posts
- Optimize images before adding them to
_pic/ - Preview diagrams using Mermaid Live Editor
Progress Bar
Inline Progress Bar
- the target is ongoing
Multiple Progress Bars
- Task 1:
- Task 2:
- Task 3:
Progress Bar Syntax
HTML syntax (works inline):
- [ ] Task <img src="https://progress-bar.xyz/29/" alt="29%" style="display: inline; vertical-align: middle;">
Progress bar URL format:
https://progress-bar.xyz/[PERCENTAGE]/
Examples:
https://progress-bar.xyz/0/- 0%https://progress-bar.xyz/25/- 25%https://progress-bar.xyz/50/- 50%https://progress-bar.xyz/75/- 75%https://progress-bar.xyz/100/- 100%
Note: Use HTML <img> tag with display: inline style to keep progress bars on the same line.
Automatic Header Numbering
The header numbering feature automatically adds sequence numbers to markdown headers without modifying the markdown source.
How It Works
Headers are automatically numbered when the feature is enabled. Notice the headers below - they will show numbers if numbering is enabled for this page.
Example with Nested Numbering
This page demonstrates nested numbering (1.1.1 style). The numbers are added automatically by JavaScript.
First Subsection
This is a subsection under the main section.
Sub-subsection
Even deeper nesting works!
Another Sub-subsection
Another sub-subsection at the same level.
Second Subsection
Another subsection under the main section.
How to Enable
Method 1: Enable for This Post
Add to the front matter:
---
layout: post
title: "My Post"
header_numbering: true
header_numbering_style: nested
---
Method 2: Enable Site-Wide
Add to _config.yml:
header_numbering: true
header_numbering_style: nested
Method 3: Disable for Specific Post
---
header_numbering: false
---
Numbering Styles
- Nested (default):
1,1.1,1.1.1,1.2,2,2.1, etc. - Flat: Only numbers H1 headers (
1,2,3, etc.)
Configuration Options
Per-page options:
header_numbering: true/false- Enable/disable for this postheader_numbering_style: nested/flat- Choose numbering style
Site-wide options (in _config.yml):
header_numbering: true/false- Enable/disable globallyheader_numbering_style: nested/flat- Default style
Notes
- Numbers are added automatically - no need to modify markdown
- Page-level settings override site-wide settings
- Numbers are styled with CSS and can be customized
- Works with all header levels (H1-H6)
Hiding Blog Posts
You can hide blog posts from appearing in listings (like the index page) while keeping them accessible via direct URL.
Method 1: Hide Individual Post
Add published: false to the post’s front matter:
---
layout: post
title: "My Draft Post"
date: 2025-11-14
published: false
---
Note: The post will still be accessible via direct URL, but won’t appear in site.posts collections or listings.
Method 2: Hide Posts Site-Wide
Add posts to the exclude list in _config.yml:
exclude:
- _posts/2025-11-14-draft-post.md
- _posts/drafts/
Note: Excluded posts won’t be processed by Jekyll at all and won’t be accessible via URL.
Tips
- Use
published: falsefor drafts you want to keep accessible but hidden from listings - Use
excludein_config.ymlfor posts you don’t want processed at all - You can exclude entire directories (e.g.,
_posts/drafts/) or specific files - Excluded files won’t appear in any collections or be built by Jekyll
Summary
This demo page showcases:
✅ Basic Markdown: Headings, text formatting, lists, links, code, tables
✅ Images: From _pic/ directory with various display options
✅ Mermaid Diagrams: Flowcharts, sequence diagrams, class diagrams, and more
✅ Progress Bars: Inline progress indicators
✅ Header Numbering: Automatic sequence numbering for headers
Use this page as a reference when writing your blog posts!