Path to better README.md through Markdown syntax 
Tags: beginners, markdown, programming, readme
Published: 2021-12-12 21:48:55



## Intro
As my journey at FlatIron school comes to a final phase and having a few projects built, I look back and I see a common thing in all of them: bad readme files! Now when I go back to my first *CLI* I am having hard time starting it without diving into code files. Idea of writing this blog is to serve as reference and help for Markdown syntax used to write README files.

___

**What you will find in this blog**
* About README
* About Markdown
* Useful VS Code extensions
* Markdown syntax (links, headings, tables, code snippets)
* References
 

___

## README
*README* is a text file used to describe the creators idea behind the application, the problem they are trying to solve, a way to intrigue possible users, help them with installation and usage, and leave them a place where they can point to some bugs or possible improvements of application.
The most common language used for writing *README* is Markdown.
___

## Markdown
*Markdown* is a lightweight markup language that you can use to add formatting elements to plaintext text documents.Markdown is platform independent. You can create Markdown-formatted text on any device running any operating system. There are several online Markdown editors that you can use to try writing in Markdown. [Dillinger](https://dillinger.io/) is one of the best online Markdown editors.
___

## VS Code extensions
 
Adding extensions to VS code setup can be of great use if you choose right ones. In your VS Code window open *extensions*(`shift`+`command`+`X` for Mac or `shift`+`command`+`X` for windows) and find ones you need through search bar.

In the search bar type `Markdown` and you will see plenty of extensions for Markdown language. 
**Markdown All in One**
This is the one I use most often.
This extension will give you keyboard shortcuts, a table of content, and best of all auto preview. Make sure to scroll down and check out their animations and notes how to best utilize this extension.
**Markdown Theme Kit**
I use this one to set difference for code snippets as it can set themes which will look not only good but also emphasize importance of code snippets you add in *README.md* file.
Other useful extensions: *markdownlint*, *Markdown Emoji* 

___

## Markdown syntax

**Comments**
```
<!-- this is comment-->
```

**Headings**
Similar to HTML, Markdown has different headings which should be used for different importance and not as styling.
```
# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6
```

**Italic, Bold, Strikethrough**
```
_this text is italic_
*this is also italic*
__this text is bold__
**this is also bold**
~~this text~~ is strikethrough
```

**Horizontal rule**
Three hyphens or three underscores in line, no spaces.
```
---
___
```

**Unordered list**
```
- Item 1
- Item 2
 - nested Item 1
 - nested Item 2
```

**Ordered list**
```
1. Item 1
1. Item 2
1. Item 3
```
**External links**
In square brackets we will write what we want to be shown on README.md as hyperlink and in parentheses will be the link where it will re-direct us. Extra attribute can be placed after link in parentheses separated with white space and quotations. This will appear when we hover over our link. 
```
[link](https://something/something/... "resources")
```

**Same page links**
This is very useful for *Table of content* part of *REDAME.md* so the user can easily navigate through file. Square brackets content will appear as link and in parentheses after it (no spaces) we will have **#** and heading exactly as it is in file. For multi word headings use hyphen to connect the words. 
```
1. [<Heading that will appear as link>](#heading-in-your-file)
2. [How to install](#how-to-install)
```
**Images**
Images of file structure, database diagram, or else will make your README.md better and easier for user to understand, navigate, use, and install your application.
```
![<alt tag>](<image link>)
![cute cat](https://cats/one/...)
```

**Inline code blocks**
Open with single backtick and close with same, all in one line. 
```
`<p>this is paragraph</p>`
```

**Multi line code blocks**
Open/close with three backticks(no spaces between) with possible additional 'attribute' where we can specify in what language code snippet is written in. Different languages will have different highlighting.  
```
` ` ` javascript
const myFunction = (){
   console.log('Hello World')
}
 ` ` `
```

**Tables**

```
|first name|last name|email|
|----------|---------|-----|
|John| Do|jd@example.com|
```

 **Task List**
Task lists can be used for part of README.md reserved for listings of future upgrades. We can check them out as we go.
```
- [x] Task 1
- [ ] Task 2
- [X] Task 3
```
___

## Summary
Probably the first file someone will see when they come to your application is *README.md*, this is the right place to *hook* them to stay and dive into your application. 
*README.md* in your application is about presenting your product (and yourself) with 'user manual', recipe, idea behind it and much more and *Markdown* give us power not to stress about *'how'* so we can focus on *'what'* to write. Plain text is good but utilizing Markdown's features will make our *README.md* more appealing and easier to understand. 

___

## References
[About README.md](https://www.makeareadme.com/)
[Traversy media about Markdown](https://www.youtube.com/watch?v=HUBNt18RFbo&t=2s&ab_channel=TraversyMedia)
[About markdown](https://www.markdownguide.org/getting-started/)
[Dillinger- online markdown editor](https://dillinger.io/)