Learning Markdown

A repository where I document my process of learning the Markdown language

What is Markdown?

Markdown is a lightweight markup language that converts text to HTML. In short, it helps to format text that appear on the screen.

A Markdown file (.md or .markdown extension) is converted by a Markdown application (containing a markdown processor/parser) into a HTML file.

Why am I learning Markdown?

To improve my proficiency in the JAM stack (JavaScript, APIs, Markup). It is a tech stack where the application logic typically resides in the client side, without being tightly coupled to the backend server.

JAM stack architecture vs Traditional Web architecture

Traditional Web: Client <--> Server <--> Database/CMS

JAM stack:

Based on my understanding, what is JAM stack:

• Static Site Generators like Gatsby/Hugo/Jekyll generate the static HTML/CSS/JS files of your website based on A) your input files & B) a set of template files:
  • Input files: a) Files that provide the data/content of your website - e.g. Markdown files (which will later be converted to HTML files using the SSG) AND b) Other types of static files - e.g CSS/JS/Image files
  • Template files: Derived from the templating engine used in the SSG - e.g. Gatsby uses React as it's templating engine.
  • For more information, can visit the Youtube video link (reference 7) & Gatsby repo link (reference 8) below to see how the markdown, css, js and image files are organized in a Gatsby-generated site.
• These pre-built static HTML/CSS/JS files are then hosted on a CDN, which are served to users when requested.
• Since they are pre-built, they load very quickly in users' browsers. The static content is first shown to the user (M portion).
• Next, the javascript code in the JS files executes in the client/browser (J portion) to handle some logic. For instance, the JS code executes to call API endpoints (A portion) to fetch dynamic content.
• The dynamic content will then be fetched from the API endpoint & then be shown to the user (both static + dynamic content shown to the user now in your website).

Useful images for visualization

References:

[1] https://jamstack.org/
[2] https://www.fullstackpython.com/static-site-generator.html
[3] https://www.cloudflare.com/en-gb/learning/performance/static-site-generator/
[4] https://bejamas.io/discovery/static-site-generators/
[5] https://www.toptal.com/front-end/static-site-generators-comparison-2018
[6] https://devopedia.org/static-site-generators
[7] Gatsby Markdown Tutorial: https://www.youtube.com/watch?v=rgyTpQVDP44
[8] Gatsby-generated Website Source Code: https://github.com/guidingdigital/yt-gatsby-markdown

What is Markdown used for?

1. Readme Files (e.g. Github)
2. Forum & Blog posts
3. Used in many Static Site Generators (e.g. Gatsby, Hugo, Jekyll)

Syntax of Markdown

A) Core Markdown syntax

1. Headings

   H1 header

   H2 header

   H3 header

   H4 header

   H5 header

   H6 header

2. Italics - Can use * * or _ _

   This text is italic

3. Bold - Can use ** ** or __ __

   This text is bold

4. Bold & Italic - Can use *** ***

   This text is both bold & italic

5. Strikethrough - Can use ~~ ~~

   This text is strikethrough

6. Horizontal Rule (a horizontal line), can use triple --- or ___ or ***

   ---

7. Escape character: \ (backslash)

8. Blockquote: Use >

   This is a quote

9. Links - a) [text goes here](link goes here) OR b) [text goes here](link goes here space insert_title)

   a) Markdown Guide b) Markdown Guide

10. UL - Insert a - or * for each item

• Item 1
• Item 2
• Item 3
  • Nested Item 1 (insert tabs)
  • Nested Item 2

11. OL

    1. Item 1
    2. Item 2
    3. Item 3

12. Inline Code Block - Use backticks ``

    e.g. This is an inline code block. Notice it's color is different from the rest of the words.

13. Images - 

    Normal image using Markdown syntax (can't adjust width & height)

    Alternative image (using HTML code - can adjust width & height)

14. Soft breaks - see example below:

    The text should look like this
    Without any spaces between the 2 sentences

    • Use either <br> or use 2 spaces to force a 'Soft break' between sentences.

15. Hard breaks

    The text should look like this

    With a visible line/space between the 2 sentences

    • Press 'Enter' in your text editor to to force a 'Hard break' between sentences (go to the next line).

16. To make a URL/Email address clickable on its own - use <insert URL/Email address here>

    https://www.google.com

    jeff@gmail.com

17. Comments

• Use

B) Github Markdown syntax (Github has their own flavor of using Markdown)

1. Code Blocks (in GitHub) - Use triple backticks ``` ```

   npm install
   
   npm run start
   

   Provides special highlighting

   function add(num1, num2) {
     return num1 + num2;
   }

2. Tables

   Name	Email
   John	john@gmail.com
   Doe	doe@gmail.com

3. Task lists (should show up as checkboxes in Github README.md)

   • Task 1
   • Task 2
   • Task 3

4. To include diagrams in your GitHub Markdown files

   • Use the mermaid syntax (i.e. ```mermaid [insert your diagram] ```)
   • Reference: GitHub Blog Mermaid syntax
   • TD means Top Down, LR means Left Right, TB means Top Bottom, RL means Right Left
   • Example:

     graph TD;
           A-->B;
           A-->C;
           B-->D;
           C-->D;
     

5. Note & Warning blockquotes (follow the syntax below)

   Note This is a note

   Warning This is a warning

   > **Note**
   > This is a note
   
   > **Warning**
   > This is a warning
   

6. Note there's also online 'Markdown to HTML code' converters online that convert your Markdown code to HTML code (in case you want to see how it looks like in HTML):

   • https://markdowntohtml.com/

References

1. Markdown Crash Course [Traversy Media] - https://youtu.be/HUBNt18RFbo
2. https://www.markdowntutorial.com/lesson/1/
3. https://www.markdownguide.org/
4. https://en.m.wikipedia.org/wiki/Jamstack
5. https://jamstack.org/
6. https://blog.dreamfactory.com/the-importance-of-loose-coupling-in-rest-api-design/
7. https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax