Open CheatSheet Back To List Next Tutorial

Markdown Tutorial (Video Tutorial)

Video Timestamps
0:00 Intro 0:20 About Markdown 2:34 VS Code Markdown Preview 3:02 Basic Markdown syntax 8:31 GitHub Flavored Markdown 9:59 Table of Contents 12:19 GitHub README.md files

Markdown Tutorial

Intro

Read it, watch it, do it, review it:
  • There are both a written and accompanying video version of this tutorial. The written version has timestamps under the headings that align with the video version of the topic.
    • Read it: For each topic heading, first read the topic. 
    • Watch it: Then watch the associated section of the video.
    • Do it: Then follow the instructions to replicate the steps on your computer.
  • The CheatSheet has a major category that aligns with this tutorial.
    • Review it: Open the CheatSheet and review the Markdown category which includes all the topics from this tutorial. Make sure you understand everything, and can refer back to the CheatSheet when you are working on your own projects in the future.

  • In this tutorial we will cover Markdown including:
    • Introduction to Markdown
    • Markdown syntax
    • GitHub Flavored Markdown
    • Adding a Table of Contents
    • Creating Readme files
    • VS Code's Markdown side-by-side preview

  • This tutorial is the fifth in a series of tutorials about Git and GitHub. It can be viewed independently, but if you are following along in the series, open the git-demo project.


About Markdown

[0:20 Video timestamp]

  • Markdown is a lightweight markup language for creating formatted text documents using a plain-text editor.
  • Use Markdown syntax to add formatting such as headings, lists, bold and italic text, hyperlinks, and images.
  • Unlike WYSIWYG (what you see is what you get) editors like MS Word, the formatting does not happen directly in the editor. Instead, behind the scenes a software program converts it to HTML, then it is rendered in a browser.
  • The syntax is designed to be readable as is, and is much less obtrusive than HTML or other markup languages. 

  • The original Markdown language was created in 2004 and a Perl script was released to convert it to HTML.
  • There are currently several variants. A commonly used basic version is called CommonMark.
  • GitHub has its own variant based on CommonMark called GitHub Flavored Markdown. It extends the basic syntax by adding tables, tasklists, and more.

  • Markdown is commonly used throughout the web. 
  • You can create a Markdown document such as a Readme file or software documentation in a plain text editor like Visual Studio Code.
  • Then upload it to GitHub. GitHub automatically converts Markdown files to HTML before rendering them in the browser. 
  • Many web and messaging applications like Reddit, Slack, and Stack Overflow allow you to use Markdown syntax in their web forms. 
  • These sites have toolbars above their web forms that add the Markdown syntax so users don't actually have to know the syntax.

  • HTML tags in Markdown: Many Markdown variants, including GitHub's, allow you to use HTML tags in your Markdown document.

  • There are also fully dedicated Markdown applications for the desktop or web that convert Markdown to HTML like dillinger.io.
  • Enter Markdown text and it can convert it to an HTML document, or PDF file.


Visual Studio Code Markdown Preview

[2:34 Video timestamp]

  • The Visual Studio Code text editor has a side-by-side Markdown preview feature.
  • If you are following along with the git-demo project, create a directory called docs in the project. Markdown is very handy for creating software documentation because, unlike HTML, it is readable as is, and it offers syntax highlighting when documenting code.
  • Create a file called markdown-demo.md. If you are following along with the git-demo project then place it in the docs folder.
  • Markdown files must have either a .markdown or more commonly a .md extension.
  • Add the below line of text to it. 

docs/markdown-demo.md
# Markdown Examples

  • When you create a file with a .md extension, the editor window will display a Preview toolbar at the top right: 
  • Click the toolbar and the Preview window will open next to the markdown file. 
  • Behind the scenes a program built into VS Code converts the Markdown to HTML, and renders it in the Preview window to the right.
  • To close the Preview window again click the close icon X to the right of the Preview filename. 


Basic Markdown syntax

[3:02 Video timestamp]

  • Now lets go through the basic Markdown syntax. You can follow along by pasting the syntax into the markdown-demo.md file and viewing it in the Preview window.

Horizontal Rule:
  • We will start with the horizontal rule. Put 3 or more underscores, dashes, or asterisks on a line. That will create a horizontal line across the screen, corresponding to the HTML <hr> tag.
___

---

***

  • Note, h1 and h2 headings will automatically add a horizontal line below the heading.

Headings:
  • Markdown has level 1 through 6 headings that correspond to the HTML  h1 through h6 tags.
  • Put pound signs before the heading text.
  • A single pound sign creates a level 1 heading.
  • Two pound signs creates a level 2 heading. All the way down to level 6.

# Markdown Examples

## Table of Contents

Coming soon
___

## BASIC MARKDOWN SYNTAX

## Headings

# h1  
## h2  
### h3  
#### h4  
##### h5  
###### h6  

### Altnernate Syntax for h1 and h2:

h1  
=  

h2  
-

  • At the top is a Level 1 heading, followed by two level 2 headings.
  • Then a series of level 1 through 6 headings.  

  • Below that is an alternative syntax for level 1 and 2 headings. Instead of prefacing the title with a pound sign: 
    • h1: underline the title with one or more equal signs to make it a level 1 heading.
    • h2: Or underline the title with one or more dashes to make it a level 2 heading. 

Escape Markdown
To escape Markdown syntax add a backslash before it. Change the above starting after ## Headings to the following:
\# h1  
\## h2  
\### h3  
\#### h4  
\##### h5  
\###### h6  

### Altnernate Syntax for h1 and h2:

h1  
\=  

h2  
\-

Line breaks, Paragraphs and Blockquotes:
  • Next we'll look at line breaks, paragraphs, and blockquotes.

___

## Line breaks, Paragraphs and Blockquotes

This is line 1. It ends with two spaces.  
Line 2 ends with an HTML break tag.<br>
This is line 3.
This is also line 3.

This is paragraph 1.

This is paragraph 2.

> This is a blockquote.
___

  • Two spaces: To create a single line break, you need to end the line with two spaces. The first line after the heading ends with two spaces which creates a line break when rendered in the Preview window.

  • BR tag: Unfortunately you can't see the spaces in your code so some people prefer to use the HTML <br> tag instead as in the next line. 
  • Many Markdown variants will render basic HTML tags including CommonMark and by extension GitHub.

  • Return key does not render as a new line: Just hitting the return key may create a separate line in your code, but it won't render as a separate line. 

  • To create a separate paragraph, put an empty line before your text as in the paragraph 1 and paragraph 2 lines above.

  • To create a block quote, put a pointy bracket in front of your text.

Italic and Bold:

## Italic and Bold

This is *italic*. So is _this_.  
This is **bold**. So is __this__.  
This is both ***bold and italic***. So is ___this___.  
___

  • To make text italic, surround it with asterisks or underlines. 
  • To make it bold, surround it with two asterisks or underlines.
  • To have it both italic and bold, surround it with three asterisks or underlines.

Code and Code blocks:
  • Now let's look at formatting code.
  • Markdown is popular with programmers and programming focused websites like GitHub and StackOverflow in part because it adds formatting to code lines and code blocks.

## Code and Code Blocks

This is `monospaced computer code`.

Below is a block of code:

    function double(num) { 
      return num * 2; 
    }; 
    double(2);

### GitHub Flavored Markdown Code Blocks:
- Can be fenced with 3 backtics or tildes.  
- And can do language syntax highlighting.

``` javascript
function triple(num) { 
  return num * 3; 
}; 
double(2);
```
___

  • For inline code, surround it with backticks: `code goes here`
  • For blocks of code, indent them by four spaces or a tab.

  • Many Markdown variants including CommonMark and by extension Github allow fenced code blocks. Where you surround the code block with lines containing three backtics or tildes.
  • Some of these also have code syntax highlighting. Put the language name after the first backtics. In this case it is JavaScript. You could also put just JS. 

Lists:

## Lists

### Unordered list

- First Item.
- Second Item.
- Third Item.
  - Intented item.
  - Second indented item.

### Ordered list

1. Item 1
2. Item 2
3. Item 3
    1. Indented item 1.
    2. Indented item 2.

Some text.  

4. Item 4
___

  • Unordered lists are bullet pointed lists. Put a dash, or an asterisk before each list item.
  • Indenting the Markdown will indent the list. 

  • Ordered lists are numbered sequentially.
  • To indent the list, just indent your code.
  • The first number in the list is the starting number. The numbers after it can be any number.

Links:

## Links

This is a link to [example.com](https://example.com)

Or you can use regular HTML <a href="https://example.com">example.com</a>

GitHub automatically creates a link from a URL: https://example.com  
___

  • Put the link text in square brackets and the URL in parentheses.
  • If you are already comfortable with HTML you may just want to just use an anchor tag. It is only slightly longer.
  • Note that some variants of Markdown, including GitHub, will automatically turn a text URL into a hyperlink.

Images:
  • Create a directory called images and put some images in it. In the git-demo example on GitHub there is an images folder with the below images in it. 

## Images

- Image alt text is displayed if the image doesn't load.
- Title is optional. It displays when hovering over an image.
- You can not set height or width with Markdown, so use the HTML img tag if you need to set those.

![Git icon](../images/git-icon.svg "Git") 
<img src="../images/github-mark.png" alt="GitHub icon" width="100" height="100" title="GitHub">
<br><br>
___

  • Image syntax:
    • Start with an exclamation mark.
    • In square brackets put the image alt text. Alt text will appear if the image fails to load. 
    • In parentheses, put the file path or URL to the image. Use the relative path to the image files. 
    • Optionally put an image title in quotes inside the parentheses after the URL. The title appears if you hover your mouse over the image.

  • The image will be rendered at whatever size the underlying image is. 
  • If you want to set a specific width and/or height you need to use the HTML image tag with those attributes. The dimensions are in pixels.

Paste headings
  Alt syntax
Paste line breaks, 
  paragraphs, 
  blockquotes


GitHub Flavored Markdown

[8:31 Video timestamp]

  • GitHub uses Markdown to display Readme and any other files with the .md extension. It also allows you to use Markdown to style comments.
  • GitHub has its own Markdown variant called GitHub Flavored Markdown. It uses the CommonMark syntax for basic Markdown, plus it has some extended syntax to create tables, tasklists, strikethough, and more.

## GITHUB FLAVORED MARKDOWN

## Supports basic HTML tags and inline style attributes
This text is <span style="color: red">red</span>.
___

## Strikethrough
Remove this line: ~~Unwanted text here.~~
___

  • Basic HTML tags are allowed. Including inline styles. For example, to change the color of one word of text, put it within HTML span tags, add the style attribute with color: red.

  • To put a strike through your text, surround it by two tildes.

Task List:

## Task List

- [ ] unchecked item
- [x] checked item

Note, task lists are supported on GitHub but not by VS Code's Markdown converter.
___

  • GitHub has syntax for creating task lists that can be checked off. 
    • - [ ] for unchecked.
    • - [x] for checked off.
  • Note that VS Code's Markdown converter doesn't support this feature so you won't see it rendered in your text editor but it will render in GitHub.

Table:

## Table

First Header | Second Header | Third Header
------------ | ------------- | ------------
Cell 1 content | Cell 2 content | Cell 3 content
Cell 1 content | Cell 2 content | Cell 3 content

  • To add a table, use the pipe symbol to separate each cell, and dashes to separate the table heading from the body. 


Table of Contents

[9:59 Video timestamp]

  • If your document is large you may want to add a Table of Contents at the top. 

  • GitHub built-in Table of Contents: 
    • GitHub automatically creates a hidden Table of Contents for all Markdown files that contain two or more headings.
    • For instance if there is a Readme file with multiple headings, then to the left of the file name there will be a menu toolbar: 
    • Clicking the toolbar will display the table of contents with links to each heading.
    • And it sticks to the top of the window so you can access it no matter where you are on the page. 
    • The downside is not everybody knows about this TOC. 

  • There are plugins to generate a table of contents for you.
  • Or you can create a table of contents manually

  • Create a TOC manually:
    • Headings are automatically given an id based on the heading title. 
      • The heading text is lowercased, 
      • Spaces are changed to dashes, 
      • And commas and periods are removed.
    • To make a TOC manually, just make a bunch of hyperlinks to URL fragments.
    • URL fragments are a location on a page. They start with the # sign, followed by the element id. 

## Table of Contents

__Basic Markdown Syntax:__  
[Headings h1 - h6](#headings)  
[Line breaks, Paragraphs and Blockquotes](#line-breaks-paragraphs-and-blockquotes)  
[Italic and Bold](#italic-and-bold)  
[Code and Code blocks](#code-and-code-blocks)  
[Links](#links)  
[Images](#images)  

__GitHub Flavored Markdown:__   
[HTML and inline style](#html-and-inline-style)  
[Strikethrough](#strikethrough)  
[Task Lists](#task-list)  
[Tables](#table)  
___


GitHub README.md files

[12:19 Video timestamp]

  • README files are displayed at the bottom of every GitHub repository's main page.

  • The README file is where you provide information on one or more of the following:
    • What the project does.
    • Why the project is useful.
    • How users can get started with the project.
    • Where users can get help with the project.
    • Who maintains and contributes to the project.

  • GitHub looks for a README.md file in the project's root directory or in a docs or .github folder. 
 
  • You can view the Readme for the git-demo project at github.com/LearnByCheating/git-demo below the code.
  • If you are following along with your own git-demo project, add the below as the Readme:

README.md
# Git Demo

The purpose of this project is to demonstrate Git, GitHub and Markdown. 

<p>
  <img src="images/git-icon.svg" alt="Git icon" height="30" title="Git">  
  <img src="images/github-mark.png" alt="GitHub icon" height="30" title="GitHub"> 
  <img src="images/markdown-icon.svg" alt="Markdown icon" height="30" title="Markdown">
</p>

It accompanies a series of written and video tutorials available at:  
[learnbycheating.com/subjects/git-github](https://www.learnbycheating.com/subjects/git-github)

And a CheatSheet available at:  
[learnbycheating.com/subjects/git-github/cheatsheet](https://www.learnbycheating.com/subjects/git-github/cheatsheet#cat-2)

_____________________________________________________

## How to follow along with the tutorials:

Clone this repository: `git clone https://github.com/LearnByCheating/git-demo.git git-demo-master-copy`

This is the final version.

To get the start or ending code do a hard reset based on tag name from the table below.

`git reset --hard TAGNAME`

Tutorial | Starting tag name | Ending tag name
------------ | ------------- | ------------
Beginning Git | - | v1-beginning-git
Intermediate Git | v1-beginning-git | v2-intermediate-git
Beginning GitHub | v2-intermediate-git | v3-beginning-github
Intermediate GitHub | v3-beginning-github | v4-intermediate-github
Markdown | v4-intermediate-github | v5-markdown
___________________________________________________

## Creating a README file for your project

The README file is where you provide information on one or more of the following:
- What the project does.
- Why the project is useful.
- How users can get started with the project.
- Where users can get help with the project.
- Who maintains and contributes to the project.

Use the Markdown language to add styling.  
Markdown syntax is demonstrated in the docs: [markdown-demo.md](./docs/markdown-demo.md)


Wrap up

  • If you are following along with the git-demo app the let's finish it up.

  • Check the Git status, stage and commit the changes, push them to the remote repo, add a tag, push the tag to the remote repo, and log the commits.
    • git status
    • git add .
    • git commit -m 'Add docs and update Readme'
    • git push 
    • git tag -am 'Markdown' v5-markdown 
    • git push origin v5-markdown 
  • Print the logs and branches
    • git glog or git log --graph --oneline 
    • git branch 

  • Make the last tagged commit into a release. 
  • Go to the GitHub repo > Click on Releases > click the Draft a new release button > click the Choose a tag drop-down > select v5-markdown > Release title: 5.0.0 
    • Release notes: 
### Markdown

- Add docs/markdown-demo.md
- Review Markdown syntax
- Modify Readme

    • Click the Publish release button.

Open CheatSheet Back To List Next Tutorial