Markdown overview

Published January 15, 2023・Last updated October 23, 2024・4 min read

Markdown is a markup language mainly used for writing documentation. Its extension is .md, and most of the IDEs provide a previewer of the written documents. This post will cover basic syntax, some use cases with examples, and different flavors.

Basics

Headers
- # some text for h1 header
- ## some text for h2 header
- ### some text for h3 header
- #### some text for h4 header
- ##### some text for h5 header
- ###### some text for h6 header
Blockquotes
- > some text
Links
- External links
  - [link text](link URL)
- Internal links (e.g., the link to Gitlab flavored header)
  - ```
  [Gitlab flavored](#gitlab-flavored)
```
Images
- ![image description](image URL)
Space between paragraphs
- blank line

Lists

unordered

- list item
  - sublist item
- list item
  - subitem item

ordered
```
1. post
1. post
1. post
```

Text modifications
- Highlighted
  - ```
  `text`
```
- Bold
  - ```
  **text**
```
- Italic
  - ```
  *text*
```
- Underlined
  - ```
  <u>underlined</u>
```
- Strike-through
  - ```
  ~~some text~~
```

Tables

| Hackathon | Location | Date |
| --------- | -------- | ---- |
| [hackathon](URL) | place | 1-2 June 2023 |

Code snippets with syntax highlighting
- ```
```js
  console.log('Hello world');
```
```
HTML tags and entities
- ```
<p>paragraph with some text &lt;3</p>
```
Comments
- ```

```
Escape characters
- ```
\> not a blockquote text
```
Show markdown content without rendering

````markdown
```js
console.log('Hello world');
```
````

~~~
```js
console.log('Hello world');
```
~~~

Usage

Documentation

Every repository should contain a Readme file with (at least) a project description and instructions on how to set up the project, run it, run the tests, and which technologies are used. Here is the link to the template example.

Blog posts

This post is written in Markdown and converted to HTML.

Diagrams

Different diagrams can be written in PlantUML. Check the rendered output in PlantUML editor.

Sequence diagrams

@startuml
User -> PaymentService: POST /payments
PaymentService -> PaymentService: handlePayment()
PaymentService -> User: response
@enduml

Architecture diagrams

@startuml
title Calculation
package calculationService {
  database postgres {
    collections scores
    collections users
  }
  interface POST_calculations
  interface GET_calculated_scores
  component calculator
  component scoreService
  interface userEventConsumer
}
package worker {
  component scheduler
  interface userEventProducer
}
package gateway {
  interface GET_scores
}
file USER_EVENT
actor User
userEventProducer --> USER_EVENT: Message event flow
USER_EVENT --> userEventConsumer: Message event flow
userEventConsumer --> users: keep users updated
scheduler --> POST_calculations: trigger calculation
POST_calculations --> calculator: calculate scores
calculator --> scores: store scores
User -> GET_scores: get scores
GET_scores --> GET_calculated_scores: get scores
GET_calculated_scores --> scoreService: get scores
scoreService --> scores: get scores
@enduml

Flavors

GitHub flavored
- Task lists
  - ```
  - [x] completed
  - [ ] in progress
```
- Emojis
  - ```
  :tada:
```

Gitlab flavored

Task lists

- [x] completed
- [~] inapplicable
- [ ] in progress

Emojis
- ```
:tada:
```
Table of content
- ```
[[_TOC_]]
```

Miscellaneous

Front matter

It is metadata placed at the beginning of the file before the content. This data can be used by static site generators like Gatsby or blogging platforms like dev.to.

---
title: Markdown overview
published: true
tags: ['markdown']
cover_image: https://picsum.photos/200/300
canonical_url: https://sevic.dev/notes/markdown-overview/
---

Mdx

Allows using JSX in Markdown documents.

import { Dashboard } from './dashboard.js'
<Dashboard year={2023} />