How to write README.md using Markdown?

How to write README.md using Markdown?

How to write README.md using Markdown

Hello Everyone

Welcome to CloudAffaire and this is Debjeet.

Today we are going to discuss how to write readme.md files using Markdown language.

What is Markdown language?

Like HTML (Hyper Text Markup Language), Markdown is also a Markup language created by John Gruber and Aaron Swartz around 2004 to create formatted text document using simple text editor. Markdown initially was used by computer geeks only but due to its ease of use it slowly adopted by the general population and is now used in almost everywhere for blogging, online forum, instant messaging, documentation etc.

What is README.md file?

README.md is simple a file name used to document your code using markdown language and is the default documentation option in most code repository like GitHub or GitLab.

Note: README is the default name that is given to the documentation but you can use any other name for your documentation file as long as it adheres to markdown language syntax.

Next, we will explore different syntax for writing markdown language.

How to write README.md using Markdown?

How to write a paragraph or header in README.md?

Without any additional characters, any plain text in readme.md file will be treated as a paragraph. For multi-line paragraph, you need to insert a line break in between your paragraph. For heading, you need to prefix your text with a # and the number of hash (#) will determine the heading size.

Example:

Rendered Output:

How to write README.md using Markdown?

How to format text in README.md?

Markdown uses combination of special characters to format text. Below table list most common text formatting options available in Markdown language.

Style Syntax
Bold **<text>**
Italic *<text>* or _<text>_
Strike ~~<text>~~
Code <text>
Quote > <text>

Example:

Rendered Output:

How to write README.md using Markdown?

Note: You can combine multiple text formatting in a singe text.

How to add footnote in README.md?

You can use caret (^) sign followed by number or words to insert a footnote in your README.md file. Footnotes are used to add reference in your documents and is rendered at the bottom of the page.

Example:

Rendered Output:

How to write README.md using Markdown?

How to insert horizontal lines in README.md?

You can use three hyphens (-), asterisks (*) or under scores (_) to insert a horizontal line in README.md file.

Example:

Rendered Output:

How to write README.md using Markdown?

How to insert code block in README.md?

You can use single tic () to insert single line code and three tics () for multi-line code. Markdown language also supports code snippet syntax highlight and to use syntax highlight use three tics () followed by language name in lowercase the code is written with.

Example:

Rendered Output:

How to write README.md using Markdown?

How to insert a list in README.md?

You can insert an ordered or unordered or task list in your README.md file. To create an ordered list, add line items with numbers followed by periods. The numbers don’t have to be in numerical order, but the list should start with the number one.

To create an unordered list, add dashes (-), asterisks (*), or plus signs (+) in front of line items. Indent one or more items to create a nested list. To create a task list, preface list items with a regular space character followed by [ ]. To mark a task as complete, use [x].

Example:

How to insert a table in README.md?

You can create tables with pipes (|) and hyphens (-). Hyphens are used to create each column's header, while pipes separate each column. You must include a blank line before your table in order for it to correctly render.

Cells can vary in width and do not need to be perfectly aligned within columns. There must be at least three hyphens in each column of the header row. Table also supports formatting such as links, inline code blocks, and text styling within your table.

You can align text to the left, right, or center of a column by including colons (:) to the left, right, or on both sides of the hyphens within the header row.

Example:

Rendered Output:

How to write README.md using Markdown?

How to insert a collapsed section in README.md?

You can temporarily obscure sections of your Markdown by creating a collapsed section that the reader can choose to expand. For example, when you want to include technical details in an issue comment that may not be relevant or interesting to every reader, you can put those details in a collapsed section.

Any Markdown within the <details> block will be collapsed until the reader clicks arrow to expand the details. Within the <details> block, use the <summary> tag to create a label to the right of

Example:

Rendered Output:

How to write README.md using Markdown?

How to insert a link in README.md?

You can create an inline link by wrapping link text in brackets [ ], and then wrapping the URL in parentheses ( ).

Examples:

Rendered Output:

How to write README.md using Markdown?

How to insert an image in README.md file?

To add an image, add an exclamation mark (!), followed by alt text in brackets, and the path or URL to the image asset in parentheses. You can optionally add a title after the URL in the parentheses. To add a link to an image, enclose the Markdown for the image in brackets, and then add the link in parentheses. You can also resize the image using HTML img tag which is supported by most sites.

Example:

Rendered Output:

How to write README.md using Markdown?

How to escape special characters in README.md file?

You can use a backslash (/) to escape special characters like backslash (\) backtick () asterisk (*) underscore (_) curly braces ({}) square brackets ([]) angle brackets (<>) parentheses (()) hash (#) plus sigh (+) hyphen (-) dot (.) exclamation mark (!) and pipe (|) in markdown language.

Example:

Rendered Output:

How to write README.md using Markdown?

Hope you have enjoyed this article, here is a link of the actual README.md file used in this demo.

Leave a Reply

Close Menu