I've been building web pages for over a year now, and at first I didn't create README files at all. Doing Frontend Mentor challenges introduced me to the concept and gave me a basic template for doing so. But without that scaffolding, I sometimes feel a little unsure of how to create (or in the case of open source, add to) a README file. These files are written in Markdown, which I hadn't learned until now. I am going to share what I've learned as a start.
If you are on Discord, you may have already learned a few things about Markdown. You can pull up emojis by surrounding their alt text in colons, or share an inline code snippet with backticks - <p>like this</p>. But Markdown is also commonly used for code reviews, comments and of course, the README file. It allows us to write HTML in a quick and fluid way.
.
Important elements in Markdown
Headings
Headings are useful for breaking up your content into meaningful sections. You can create heading elements with the corresponding number of pound symbols. For example, an <h1> would be one '#' followed by a space and then the text of that heading. <h2> would be two '##', <h3>, '###', and so on... I've done this below.
Heading one
Heading two
Heading three
Heading four
Heading five
Heading six
.
Inline styles
In order to emphasize text in your markdown, you may want to take advantage of inline styles.A few examples of styling text inline in markdown are:
- bolding with double asterisks surrounding text
- bolding with double underscores surrounding text
- italicizing with single asterisks surrounding text
- italicizing with single underscores surrounding text
-
striking throughwith double tildes
You can create a horizontal rule with three dashes '---' beneath the text you wish to underscore.
You can create a blockquote with a carat '>' to the left of the text.
"Alright, alright, alright... " - Matthew McConaughey
.
Lists
You can create ordered and unordered lists pretty easily. If you want an ordered list (numbered), you simply put a number and a period in front of the text. The numbering will be sequential by default, even if for some strange reason you randomized your numbers. You can also nest lists. Below is an example of an ordered list (note the indentation):
- Ordered list item
- Second list item
- nested list item
- nested list item
- Last list item
An unordered list can be created by putting a '-' (dash) before each list item. (You can also use '*' (asterisk) or '+' (plus symbol), each of these will have the same appearance, a bolded dot next to the text.) As with ordered lists, these will be indented accordingly.
- Unordered list item with a dash
- Unordered list item with an asterisk
- Unordered list item with a plus symbol
- Tab to nest list items.
- Consistency is best practice.
- Using a dash is more common.
.
Code Blocks
To offset blocks of code, wrap the desired text in nested backticks
``` <-- A set of these surround code.
<body>
<div id="compiled-markdown"></div>
<script src="./marked.min.js"></script>
<script src="index.pack.js"></script>
</body>
In this code block, the first script tag links to a markdown linter that Dylan Israel is using in his Learn Markdown course on Scrimba.
.
Adding Images
You can add images in your markdown in the following way. Start with an exclamation point ('!'), followed by square brackets ('[ ]') that enclose alt text, and then the image URL inside of parentheses ('( )') - (No quotation marks are needed to surround the URL.)
I will add an image in this way -
.
Links and Email Addresses
Links are created in markdown in a way that is similar to how we added an image. Basically we just leave off the bang/exclamation point('!'). You use square brackets ('[ ]') for the text that you want to display on the page, and parentheses ('( )') to enclose the URL.
I can link to my Twitter profile in this way.
Emails are simpler. You merely enclose the email address in angle brackets ('< >') (No quotations are needed for any of these URLs by the way.) Feel free to email me at micha.ella@hotmail.com with an amazing job offer. 😅
It might be appropriate to share some links here for some Markdown reference guides. There's Basic Syntax as well as Extended Syntax, which I'll touch on in the next section.
.
Extended Syntax
You can create a task list that can be checked off by yourself or others. It starts with the syntax of an unordered list (a dash '-'), and then opening square brackets('[ ]'). This will create an empty checkbox. One can check the box by adding an 'x' inside the brackets with spaces around it ('[ x ]').
.
Checklist
- [ x ] Talked about what markdown is for
- [ x ] Gave examples
- [ ] Checklist supported by Hashnode?
- [ ] Checklist supported by Dev?
.
Conclusion
Now that you know many of the main markdown elements, you will be able to use them to enhance the appearance and readability of README files for your projects, pull requests, code reviews, and much more. I learned Markdown by taking Dylan Israel's course on Scrimba. Whether you're starting from scratch, or merely want to enhance your skills, Scrimba offers a variety of high-quality courses for Frontend Web Development, many for free. Check it out, if you haven't already.!
Top comments (1)
Thank you for writing this. Awesome work!