Markdown overview

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 &lt;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
  

  • 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} />