DEV Community

Methodox Technologies, Inc. profile image Charles Zhang
Charles Zhang for Methodox Technologies, Inc.

Posted on

[Share] Beginner’s Guide to GitHub-Flavoured Markdown

#markdown #syntax #technique #typesetting

Originally posted on Methodox Wiki

Markdown shown on this page has limited rendering features, consult original post for more: https://wiki.methodox.io/en/KnowledgeBase/Markdown

1. Introduction

1.1 Why Markdown Rocks ✨

Markdown is plain text with super-powers. It lets you jot notes, write docs, craft blog posts, even format PDFs - all without leaving the comfort of your favourite text editor.

  • Human-friendly – readable in raw form, so your future self (and collaborators) can skim it in any terminal.
  • Portable – works on GitHub, GitLab, Stack Overflow, Jira, Notion, countless CMSes and static-site generators.
  • Speedy – no buttons or WYSIWYG mysteries; just type.
  • Version-control bliss – diffs stay clean because it’s plain text.

1.2 Where You’ll Meet Markdown

  • README files, issue & PR templates on GitHub.
  • Technical blogs (Jekyll, Hugo, Astro, etc.).
  • Docs sites (Docsify, MkDocs, Docusaurus).
  • Note-taking apps (Obsidian, Logseq, Typora).
  • Chat & community tools (Telegram, Discord, Slack, Discourse).

1.3 Little Wonders You Can Do 😍

Markdown’s magic is that every one of those tricks is still perfectly legible in raw text.

Wonder What happens
Task lists Interactive check-boxes in GitHub issues.
Syntax-highlight Colours like an IDE!
Tables Nicely aligned grids.
Collapsible blocks Click to reveal secrets.
Emoji Turns into 😍 🎉.

(CoderLegion's markdown has limited rendering features and has no syntax highlighting, consult original post)

2 · Quick Reference (Cheat Sheet)

Tip: Try every sample in a .md file on GitHub and hit Preview.

2.1 Headings 

# H1
## H2
### H3
Enter fullscreen mode Exit fullscreen mode

Rendered ⇒

peek
# H1

## H2

### H3

2.2 Emphasis 

*italic*   _italic_
**bold**   __bold__
~~strike~~
Enter fullscreen mode Exit fullscreen mode

italic  bold  strike

2.3 Lists

Unordered 

- Item A
  - Sub-item
* Asterisks work too
Enter fullscreen mode Exit fullscreen mode

  • Item A

    • Sub-item

  • Asterisks work too

Ordered 

1. First
2. Second
Enter fullscreen mode Exit fullscreen mode
  1. First
  2. Second

2.4 Links 

[visible text](https://example.com)
<https://example.com>   <!-- autolink -->
Enter fullscreen mode Exit fullscreen mode

visible text
https://example.com

2.5 Images 

![Alt text](https://picsum.photos/200/300)
Enter fullscreen mode Exit fullscreen mode

Alt text

2.6 Code

Inline

`code` → code

Fenced (with highlight) 


```js
function greet() {
  console.log("Hello!");
}
```

2.7 Blockquotes 

> One level
>> Nested wisdom
Enter fullscreen mode Exit fullscreen mode

One level

Nested wisdom

2.8 Horizontal Rule (Divider) 

---
Enter fullscreen mode Exit fullscreen mode

Rendered ⇒

peek

2.9 Tables 

| Col A | Col B |
|-------|-------|
|  1    |  2    |
|  3    |  4    |
Enter fullscreen mode Exit fullscreen mode
Col A Col B
1 2
3 4

2.10 Task Lists 

- [ ] Walk dog
- [x] Write guide
Enter fullscreen mode Exit fullscreen mode
  • [ ] Walk dog
  • [x] Write guide

2.11 Emoji 

:rocket: :sparkles: :100:
Enter fullscreen mode Exit fullscreen mode

🚀 ✨ 💯

2.12 Strikethrough 

~~obsolete~~ now shiny
Enter fullscreen mode Exit fullscreen mode

obsolete now shiny

2.13 Inline HTML (Collapsible) 

<details>
<summary>Click me</summary>
Surprise! 🎈
</details>
Enter fullscreen mode Exit fullscreen mode
Click me Surprise! 🎈

2.14 Escaping Characters

Need a literal *? Use backslash:

\*not italic\*
Enter fullscreen mode Exit fullscreen mode

*not italic*

2.15 Footnotes 

Markdown is handy.[^1]

[^1]: And footnotes are too!
Enter fullscreen mode Exit fullscreen mode

Markdown is handy.1

Explore More🗺️

To truly master Markdown, you should combine it with features from some foundational languages like HTML and CSS, and utilize additional extensions. See Charles' cool demo for some additional features:

  1. HTML
  2. CSS
  3. LaTeX
  4. Mermaid
  5. JavaScript

Notice those features may not be ubiquitously supported depending on the renderer.

References

  1. And footnotes are too! ↩

Top comments (0)