Markdown Mastery

| Feature | Basic Markdown | GFM Extended | Notes |
|---------|---------------|--------------|-------|
| Bold | `**text**` | Same | Use double asterisks |
| Italic | `*text*` | Same | Use single asterisks |
| Strikethrough | — | `~~text~~` | Not in original spec |
| Task List | — | `- [ ] task` | GFM only |
| Tables | — | `\| col \| col \|` | GFM only |
| Auto-link | — | `<url>` | Angle brackets |
| Fenced code blocks | — | ```` ``` ```` | With language tag |
| Emoji | — | `:smile:` | GFM renders to emoji |

**Alignment in tables:**

#### Footnotes

#### Task Lists

#### Definition Lists

#### Subscript and Superscript

#### Highlight and Keyboard Tags

---

### Mermaid Diagrams

Mermaid lets you create diagrams using text definitions that render inline in markdown. Diagrams are version-controlled alongside your code.

#### Setup

#### Flowcharts

flowchart LR
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> E[Fix the issue]
    E --> B
    C --> F[End]

    style A fill:#4CAF50,color:#fff
    style C fill:#4CAF50,color:#fff
    style D fill:#ff9800,color:#fff
    style E fill:#2196F3,color:#fff

flowchart <orientation>
  <node_id>[<label>] --> <node_id>{<label>}

Orientations: LR (left-right), RL (right-left), 
              TB (top-bottom), BT (bottom-top)

Node shapes:
  [text]    - Rectangle
  (text)    - Rounded rectangle
  {text}    - Diamond (decision)
  [[text]]  - Subroutine
  >text]    - Asymmetric
  (((text))) - Double circle

**Syntax:**

#### Gantt Charts

gantt
    title Project Timeline - Q1 2024
    dateFormat  YYYY-MM-DD
    axisFormat  %b %d
    
    section Planning
    Requirements           :done,    r1, 2024-01-01, 2024-01-14
    Design Review          :done,    r2, 2024-01-10, 2024-01-20
    
    section Development
    Frontend               :active,  dev1, 2024-01-15, 2024-02-15
    Backend                :         dev2, 2024-01-20, 2024-02-20
    API Integration        :         dev3, 2024-02-01, 2024-02-25
    
    section Testing
    Unit Tests             :         test1, 2024-02-15, 2024-03-01
    Integration Tests      :         test2, 2024-02-20, 2024-03-05
    UAT                    :         test3, 2024-03-01, 2024-03-15
    
    section Launch
    Deployment             :milestone, launch, 2024-03-15, 0d

**Visibility modifiers:**
- `+` Public
- `-` Private
- `#` Protected
- `~` Package/Internal

#### Entity-Relationship Diagrams (ERD)

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "appears in"
    CUSTOMER {
        int id PK
        string name
        string email
        datetime created_at
    }
    ORDER {
        int id PK
        int customer_id FK
        datetime order_date
        string status
        decimal total
    }
    LINE_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
        decimal unit_price
    }
    PRODUCT {
        int id PK
        string name
        string description
        decimal price
        int stock_quantity
    }

#### Pie Charts

pie title Programming Language Usage (2024)
    "JavaScript" : 32
    "Python" : 28
    "TypeScript" : 18
    "Go" : 10
    "Rust" : 7
    "Other" : 5

#### Git Graph

gitGraph
    commit id: "Initial commit"
    commit id: "Add project setup"
    branch develop
    checkout develop
    commit id: "Add feature A"
    commit id: "Add feature B"
    branch feature/cool-new-feature
    checkout feature/cool-new-feature
    commit id: "WIP: work in progress"
    commit id: "Complete feature"
    checkout develop
    merge feature/cool-new-feature
    checkout main
    merge develop tag: "v1.0.0"
    commit id: "Hotfix"
    branch release/v1.1.0
    checkout release/v1.1.0
    commit id: "Release prep"

@username — Mentions a user
@org/team-name — Mentions a team (notifies all members)

<!-- Examples -->
@octocat Can you review this PR?
@acme/security-team Please review the security implications.

#123        — Links to issue/PR #123
org/repo#456 — Cross-repo reference
GH-789      — Also works in some contexts

<!-- In commit messages -->
Closes #123
Fixes #456
Resolves #789
See also: #234

<!-- In PR descriptions -->
**Related issues**: #123, #456
**Depends on**: #789

<!-- URLs are auto-linked -->
https://example.com

<!-- SHA references link to commits -->

<!-- The commit SHA `abc1234` is auto-linked -->

<!-- Markdown references -->
[Documentation](https://docs.example.com)

:rocket: — 🚀
:bug: — 🐛
:sparkles: — ✨
:fire: — 🔥
:white_check_mark: — ✅
:x: — ❌
:warning: — ⚠️
:book: — 📖
:hammer_and_wrench: — 🛠️
:chart_with_upwards_trend: — 📈
:package: — 📦
:lock: — 🔒

<!-- Common in commit messages -->
:tada: Initial commit
:sparkles: New feature
:bug: Fix bug
:recycle: Refactor
:zap: Performance improvement
:memo: Documentation
:white_check_mark: Add tests
:green_heart: Fix CI

> [!NOTE]
> Useful information that users should know, even when skimming.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

<details>
<summary>Click to expand — Troubleshooting Steps</summary>

1. Check the logs at `/var/log/app.log`
2. Verify the configuration file exists
3. Restart the service: `systemctl restart app`
4. If still failing, contact support

</details>

In GFM, diff blocks with `+` (green) and `-` (red) lines visually highlight changes.

{
  "MD001": true,
  "MD003": { "style": "atx" },
  "MD004": { "style": "dash" },
  "MD007": { "indent": 2 },
  "MD009": { "br_spaces": 2 },
  "MD012": true,
  "MD013": { "line_length": 80, "code_blocks": false },
  "MD014": true,
  "MD018": true,
  "MD019": true,
  "MD022": true,
  "MD024": { "allow_different_nesting": true },
  "MD025": true,
  "MD026": { "punctuation": ".,;:!" },
  "MD027": true,
  "MD028": true,
  "MD029": { "style": "one" },
  "MD030": true,
  "MD031": true,
  "MD032": true,
  "MD033": { "allowed_elements": ["details", "summary", "kbd", "sub", "sup"] },
  "MD034": true,
  "MD035": { "style": "---" },
  "MD036": false,
  "MD037": true,
  "MD038": true,
  "MD039": true,
  "MD040": true,
  "MD041": true,
  "MD042": true,
  "MD043": false,
  "MD044": { "names": ["Markdown", "GitHub", "JavaScript", "TypeScript", "VS Code"] },
  "MD045": false,
  "MD046": { "style": "fenced" },
  "MD047": true,
  "MD048": { "style": "backtick" }
}

# Install markdownlint
npm install -g markdownlint-cli2

# Check all markdown files
npx markdownlint-cli2 'docs/**/*.md' '#node_modules'

# Auto-fix what you can
npx markdownlint-cli2 --fix 'docs/**/*.md'

# With custom config
npx markdownlint-cli2 \
  --config .markdownlint.json \
  'docs/**/*.md'

{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "all",
  "printWidth": 80,
  "proseWrap": "always",
  "overrides": [
    {
      "files": "*.md",
      "options": {
        "parser": "markdown",
        "proseWrap": "always",
        "printWidth": 80
      }
    }
  ]
}

# Format all markdown files
npx prettier --write '**/*.md'

# Check without writing
npx prettier --check '**/*.md'

# Format in CI
npx prettier --check 'docs/**/*.md' || echo "Run 'npx prettier --write' to fix"

# .github/workflows/markdown-quality.yml
name: Markdown Quality
on:
  pull_request:
    paths:
      - '**/*.md'

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Markdown Lint
        run: |
          npx markdownlint-cli2 '**/*.md' \
            '#node_modules' \
            --config .markdownlint.json
      
      - name: Format Check
        run: |
          npx prettier --check '**/*.md'
      
      - name: Spell Check
        uses: streetsidesoftware/cspell-action@v2
        with:
          files: '**/*.md'
      
      - name: Validate Mermaid Diagrams
        run: |
          # Extract mermaid blocks and validate syntax
          for file in $(find docs -name "*.md"); do
            echo "Checking $file for mermaid syntax..."
            # Use mermaid CLI to render and check for errors
          done

# Vitepress (Vue-based)
npm create vitepress my-docs
cd my-docs
npm run docs:dev

# Docusaurus (React-based)
npx create-docusaurus@latest my-docs classic

# MkDocs (Python-based)
pip install mkdocs mkdocs-material
mkdocs new my-docs

# Hugo (Go-based)
hugo new site my-docs

<!-- Manual TOC (update when structure changes) -->
## Table of Contents
- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Configuration](#configuration)
- [API Reference](#api-reference)
- [Troubleshooting](#troubleshooting)

<!-- Or use a TOC generator plugin -->
<!-- VS Code: "Markdown All in One" extension → Right-click → TOC -->

# Generate TOC using doctoc
npx doctoc docs/my-file.md

# Or using markdown-toc
npx markdown-toc docs/my-file.md

# Markdown → HTML
npx marked README.md -o README.html

# Markdown → PDF
npx md-to-pdf README.md

# Markdown → DOCX (Word)
pandoc README.md -o README.docx

# Markdown → LaTeX → PDF
pandoc README.md -o README.pdf --pdf-engine=xelatex

# Markdown → slides
npx marp README.md -o slides.html
npx marp README.md -o slides.pdf

<!-- Custom containers -->
<div class="warning">
  <h3>⚠️ Important Security Notice</h3>
  <p>Never commit API keys or secrets. Use environment variables
  or a secrets manager instead.</p>
</div>

<!-- Image sizing -->
<img src="screenshot.png" alt="Dashboard screenshot" width="600" />

<!-- Iframes for embedded content -->
<iframe 
  src="https://codesandbox.io/embed/example" 
  width="100%" 
  height="500"
  title="Interactive example"
></iframe>

<!-- Video embeds -->
<video controls width="800">
  <source src="demo.mp4" type="video/mp4">
  Your browser does not support the video tag.
</video>

<!-- YouTube embed -->
<iframe 
  width="560" 
  height="315" 
  src="https://www.youtube.com/embed/dQw4w9WgXcQ" 
  title="YouTube video"
  frameborder="0" 
  allowfullscreen
></iframe>

<!-- Custom lists with icons -->
<ul class="feature-list">
  <li>✅ Fast performance</li>
  <li>🔒 Secure by default</li>
  <li>🌐 Cross-platform</li>
</ul>

---
aliases: [alt-name, another-name]
tags: [markdown, obsidian]
created: 2024-01-15
---

# Obsidian Features

## Internal Links
[[My Other Note]]           — Link to another note
[[My Note|Display Text]]    — Link with custom display text

## Embeds
![[image.png]]              — Embed an image
![[note.md]]                — Embed contents of another note

## Tags
#tag                       — Inline tag
#project/active            — Nested tag

## Block References
This is a paragraph. ^block-id
See [[Note#^block-id]]     — Reference a specific block

## Callouts
> [!note] Title
> Content of the callout

> [!abstract] Summary
> Key takeaways

> [!info] Information
> Additional context

> [!danger] Danger
> Critical warning

<!-- Notion Markdown import/export specifics -->

# Heading 1    → Toggle heading in Notion
## Heading 2   → Normal heading 2
### Heading 3  → Normal heading 3

- [x] Task list → Notion checkboxes (synced)
- [ ] Task     → Unchecked checkbox

<!-- Code blocks import as Notion code blocks -->

<!-- Tables import as Notion databases (not markdown tables) -->
| Name | Type |
|------|------|
| Item | Note |

<!-- Notion-specific: -->
<!-- /command → Slash commands in Notion -->
<!-- @date → Date mentions -->
<!-- @person → Person mentions -->

export const Highlight = ({children, color}) => (
  <span style={{backgroundColor: color, padding: '0.2em'}}>
    {children}
  </span>
);

# MDX Example

You can use JSX in markdown with MDX!

<Highlight color="#ff0">
  This text is highlighted in yellow.
</Highlight>

{2 + 2}  {/* → renders as 4 */}

import CodeBlock from '@theme/CodeBlock';

<CodeBlock language="python">
{`print("Hello from MDX!")`}
</CodeBlock>

export const toc = [
  {value: 'Introduction', id: 'introduction', level: 2},
  {value: 'Usage', id: 'usage', level: 2},
];

<!-- Docusaurus/MkDocs Material code tabs -->

=== "Python"

=== "JavaScript"

=== "Go"

=== "Rust"

:::note[My Custom Title]
Some **content** with markdown syntax.
:::

:::tip
Best practice recommendation here.
:::

:::info
Additional context or background information.
:::

:::warning
Be careful with this configuration.
:::

:::danger
Do not do this in production!
:::

<figure>
  <img src="architecture.png" alt="System architecture diagram" />
  <figcaption>
    <strong>Figure 1:</strong> System architecture showing the 
    microservices and their communication patterns.
  </figcaption>
</figure>

<!-- Inline math: $E = mc^2$ -->

<!-- Display math:
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$
-->

<!-- GitHub supports LaTeX with $$ delimiters -->
$$
O(n \log n)
$$

$$
\hat{y} = \sigma(W \cdot x + b)
$$