Markdown, End-to-End: Syntax, Extensions, Best Practices, Tooling, and Jekyll/GitHub Pages

Markdown, End-to-End

Markdown is a lightweight, plain-text markup that converts into HTML (and beyond) with minimal effort. It’s readable, portable, version-control friendly, and perfect for blogs, docs, notes, READMEs, and technical tutorials.

This post is a single, practical reference: we’ll start with the core syntax, layer on useful extensions (GFM/kramdown), then cover formatting/SEO patterns, editor + lint + conversion tools, and a clean publishing workflow for Jekyll/GitHub Pages.
Oh, and I almost forgot to introduce myself—Yahallo! It’s me, SuiiKawaii ✨ Today we’ll see what Markdown is, why it matters, and how to use it effectively across this docs and blog.

Table of Contents

• 1) Why Markdown (value proposition)
• 2) Flavors & ecosystem (CommonMark, GFM, kramdown)
• 3) Core syntax (mini cheat + examples)
• 4) Extended syntax you’ll actually use
• 5) Best practices (structure, SEO, a11y, maintainability)
• 6) Tooling (editor, lint/format, conversion, diagrams)
• 7) Using Markdown in Jekyll/GitHub Pages
• 8) A production writing workflow
• 9) Troubleshooting cheats
• 10) Obsidian quickstart for docs & notes
• 11) Choosing your editor (2025 comparison)
• FAQ
• Appendix A — Quick Markdown cheatsheet
• Resource Library (Articles & Videos)

1) Why Markdown (value proposition)

• Plain text longevity — open/edit anywhere; Git diffs are meaningful.
• Fast to learn — minimal syntax; beginners become productive in an hour.
• Portable — one .md can become HTML, PDF, DOCX, or slides via Pandoc.
• Focus on content — CSS/theme handles styling; you write ideas, not <div>s.
• Automation-friendly — perfect for CI/CD, SSGs, and GitHub Pages.

2) Flavors & ecosystem (CommonMark, GFM, kramdown)

Further references:

• CommonMark (spec)
• GitHub Flavored Markdown (GFM)
• kramdown syntax reference

3) Core syntax (mini cheat + examples)

Headings, paragraphs, emphasis

# H1
## H2
### H3

Normal paragraph with *italic* and **bold**.

Lists

- Bullet A
- Bullet B
  - Nested bullet

1. First
2. Second

Links & images

[OpenAI](https://openai.com)
![Alt text](/assets/images/markdown/example.png)

Code & blockquotes

Inline code:

echo "Hello Markdown"

Quote or note here

Tables (GFM)

| Column | Meaning |
|-------:|:--------|
|   123  | Right   |
|  text  | Left    |

You could try this video!!

Further references:

• Writer 101 — Markdown Guide

4) Extended syntax you’ll actually use

Task lists (GFM)

- [x] Outline
- [ ] Add screenshots

Strikethrough & autolinks (GFM)

~~deprecated~~ now updated
https://example.com

Footnotes (kramdown)

A sentence with a footnote.[^why]
[^why]: Footnote content here.

Attribute Lists (kramdown)

## Section with anchor {#my-section}
A paragraph {.note}

Definition lists (kramdown)

Term
: Definition line 1

Syntax highlighting (Rouge)

def greet(name: str) -> str:
    return f"Hello, {name}"

Refrences video:

Further references:

• Use Obsidian (BEST Markdown editor) for tech docs!

5) Best practices (structure, SEO, a11y, maintainability)

• One H1 per post, then H2/H3 hierarchy.
• Front matter: clear description, relevant tags, and excerpt_separator: <!--more-->.
• Stable anchors (use HTML ids like in this post if your parser ignores {#id}).
• Meaningful alt text for images.
• Language hints on code fences for highlighting.
• Link hygiene: prefer internal links for related posts.
• Keep it skimmable: lists, callouts.
• Prefer relative URLs + optimized assets (.webp when possible).

6) Tooling (editor, lint/format, conversion, diagrams)

Editors

• VS Code (+ Markdown All in One, vscode-markdownlint, Paste Image).
• Obsidian (excellent for notes and docs).
• Typora / MarkText (distraction-free).

Further references:

• OPEN SOURCE alternatives to popular productivity apps

Lint & format

npm i -D markdownlint-cli2 markdownlint-rule-search-replace prettier
npx markdownlint-cli2 '**/*.md' '!node_modules'

.markdownlint.jsonc

{ "default": true, "MD013": false, "MD024": { "allow_different_nesting": true }, "MD033": false }

Convert with Pandoc

pandoc post.md -o post.pdf --pdf-engine=wkhtmltopdf
pandoc post.md -o post.docx

CI (optional) — GitHub Actions

name: markdown-lint
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm i -D markdownlint-cli2
      - run: npx markdownlint-cli2 '**/*.md' '!node_modules'

7) Using Markdown in Jekyll/GitHub Pages

Key _config.yml:

markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighter: rouge
  hard_wrap: false
  footnote_nr: 1
highlighter: rouge

Front matter pattern:

---
layout: post-with-comments
title: "Your Post Title"
permalink: /posts/your-slug/
tags: [topic, keywords]
description: "One-sentence value proposition."
excerpt_separator: <!--more-->
---

Assets & links:

![Alt](/assets/images/markdown/diagram.webp)
[Related post](/posts/another-article/)

Further references:

• Jekyll docs — Markdown & kramdown
• kramdown configuration

8) A production writing workflow

1. Outline
2. Create _drafts/your-slug.md
3. Add front matter (title, description, tags, excerpt)
4. Write core content; add anchors you’ll link to
5. Add media under /assets/images/your-slug/ with alt text

6. Lint & preview

   npx markdownlint-cli2 '**/*.md'
   bundle exec jekyll serve
   

7. Add internal links to related posts
8. Final pass: headings, consistent code fences
9. Publish (move to _posts/)
10. Post-publish: small typo fixes, update resources

9) Troubleshooting cheats

• ToC not jumping → if {#id} shows as text, use <a id="..."></a> anchors.
• Paragraphs “stick” → blank line between blocks.
• Lists break → consistent 2–4-space indent + blank lines around fenced code.
• Table fails → GFM table syntax; avoid tabs.
• Images 404 → check relative path/case + relative_url.
• Underscores render italic → escape \_ or use backticks.
• Code not highlighted → add language + ensure Rouge.
• Mermaid not rendering → include Mermaid JS in layout.

10) Obsidian quickstart for docs & notes

• Vault structure: content/ (notes), assets/ (images), snippets/ (reusable MD).
• Core tips: wikilinks [[Page Title]], templates for skeletons, daily notes as scratchpad.
• Plugins: Templater, Dataview, Advanced Tables, Paste URL into selection, Paste Image.
• Export: copy final .md + assets to Jekyll; replace wikilinks with standard Markdown links if needed.

Further references:

• My Obsidian Setup: The King of Note Taking Apps
• Use Obsidian (BEST Markdown editor) for tech docs!

11) Choosing your editor (2025 comparison)

TL;DR:

• Obsidian — graph view, plugins, great for knowledge bases; needs a few tweaks for Jekyll export.
• Typora — beautiful WYSIWYG-like live preview; great for writers who want minimal UI.
• MarkText — open-source, lightweight; good if you want a simple GUI editor.

FAQ

Can I mix HTML with Markdown? Yes; keep it minimal. Open links in new tab? This post keeps links in the same tab. Line breaks? Two spaces at EOL create <br>; prefer real paragraphs. Center an image? Wrap with <p style="text-align:center">…</p>. Right width for images? Prefer responsive; optimize assets.

Appendix A — Quick Markdown cheatsheet

Embed the printable PNG (you could do it by put it under your repo path):

# H1 / ## H2 / ### H3
*italic* **bold** `code`
- Bullet / 1. Numbered
[Link](https://example.com)  ![Alt](/assets/img/pic.webp)
> Quote
```bash
echo Hello
```
| H | H |
|--:|:-:|
| 1 | 2 |
- [x] Done
- [ ] Todo
Footnote[^f]   ## Title {#id}
[^f]: Footnote text.

Resource Library (Articles & Videos)

Videos:

• The Only Markdown Crash Course You Will Ever Need
• BEST Markdown Editors For Linux
• What is Markdown?
• Writer 101 — Markdown Guide
• Every USEFUL Markdown Syntax That I Use in Obsidian
• Use Obsidian (BEST Markdown editor) for tech docs!
• How To Take Notes as a Programmer
• Typora vs MarkText vs Obsidian (2025)
• Obsidian: The King of Learning Tools (FULL GUIDE + SETUP)
• My Obsidian Setup
• OPEN SOURCE alternatives to popular productivity apps

Articles / official docs:

• Markdown Guide
• CommonMark Spec
• GitHub Flavored Markdown (GFM)
• kramdown Syntax
• Jekyll docs
• Pandoc manual

Final notes

Use Markdown as your content source of truth. Keep the writing clean and portable; let CSS/theme do the rest. With a small toolchain (editor + lint + preview), you’ll publish faster and safer.

Thanks for reading!

Until next time — Otsumachi!! 💖☄️✨