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 through~~ with 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
1. nested list item
2. 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.!