DEV Community

Cover image for Path to better through Markdown syntax
Milan Zivkovic
Milan Zivkovic

Posted on

Path to better through Markdown syntax


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 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 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 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 file.
Other useful extensions: markdownlint, Markdown Emoji

Markdown syntax


<!-- this is comment-->
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Italic, Bold, Strikethrough

_this text is italic_
*this is also italic*
__this text is bold__
**this is also bold**
~~this text~~ is strikethrough
Enter fullscreen mode Exit fullscreen mode

Horizontal rule
Three hyphens or three underscores in line, no spaces.

Enter fullscreen mode Exit fullscreen mode

Unordered list

- Item 1
- Item 2
 - nested Item 1
 - nested Item 2
Enter fullscreen mode Exit fullscreen mode

Ordered list

1. Item 1
1. Item 2
1. Item 3
Enter fullscreen mode Exit fullscreen mode

External links
In square brackets we will write what we want to be shown on 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")
Enter fullscreen mode Exit fullscreen mode

Same page links
This is very useful for Table of content part of 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)
Enter fullscreen mode Exit fullscreen mode

Images of file structure, database diagram, or else will make your better and easier for user to understand, navigate, use, and install your application.

![<alt tag>](<image link>)
![cute cat](https://cats/one/...)
Enter fullscreen mode Exit fullscreen mode

Inline code blocks
Open with single backtick and close with same, all in one line.

`<p>this is paragraph</p>`
Enter fullscreen mode Exit fullscreen mode

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')
 ` ` `
Enter fullscreen mode Exit fullscreen mode


|first name|last name|email|
|John| Do||
Enter fullscreen mode Exit fullscreen mode

Task List
Task lists can be used for part of reserved for listings of future upgrades. We can check them out as we go.

- [x] Task 1
- [ ] Task 2
- [X] Task 3
Enter fullscreen mode Exit fullscreen mode


Probably the first file someone will see when they come to your application is, this is the right place to hook them to stay and dive into your application. 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 more appealing and easier to understand.


Traversy media about Markdown
About markdown
Dillinger- online markdown editor

Top comments (0)