homeresume
 
   

Markdown overview

Published January 15, 2023Last updated September 28, 20244 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

    • <!-- this is a comment text -->
  • 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} />