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 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.
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
Traversy media about Markdown
About markdown
Dillinger- online markdown editor
Top comments (0)