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 |
-
HTML tags and entities
<p>paragraph with some text <3</p>
-
Comments
<!-- this is a comment text -->
-
Escape characters
\> not a blockquote text
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
:tada:
-
Gitlab flavored
- Task lists
- [x] completed - [~] inapplicable - [ ] in progress
: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} />
Top comments (0)