Comprehensive Guide To Styling a GitHub README

Learn Essential Markdown Syntax Ranging from Text Styling and URL Links to Image Manipulation.

Photo by Christin Hume on Unsplash

What is Markdown?

Markdown is an easy to use syntax for styling and formatting writing on the internet. Most likely, you’ve seen it used for GitHub READMEs. When developing new applications, it’s always a good idea to create a well-written, informative, and well-styled README to accompany your project. This article will hopefully serve as a helpful reference guide while you’re creating your own READMEs on GitHub.

Text Styling: Bold

To make text bold, simply wrap in double asterisks.

Syntax:

**TEXT**

Example:

This word is **bold**

Result:

Text Styling: Italic

To make text italic, simply wrap in single asterisks.

Syntax:

*TEXT*

Example:

This word is *italic*

Result:

Headers

To create different sized headers, add # plus a space before the word.

Example:

# This is a h1 header
## This is a h2 header
### This is a h3 header
#### This is a h4 header
##### This is a h5 header
###### This is a h6 header

Result:

Images

There are a couple ways of adding images to a README.

Option #1: Markdown Syntax

![Alt Text](IMAGE URL OR FILE PATH)
e.g. ![A Cute Dog](https://thehappypuppysite.com/wp-content/uploads/2017/10/Cute-Dog-Names-HP-long.jpg)

Option #2: HTML Syntax

<img src="IMAGE URL OR FILE PATH">
e.g. <img src="./images/profile.jpeg">

Image Sizing

Most likely, you’ll want to adjust image sizing for your README. To achieve this, you’ll want to use the HTML <img> tag and add in fields for width or height.

Syntax:

<img src="IMAGE URL OR FILE PATH" width="DESIRED WIDTH" height="DESIRED HEIGHT">

Example:

<img src="https://thehappypuppysite.com/wp-content/uploads/2017/10/Cute-Dog-Names-HP-long.jpg" width="200">

Result:

Image Alignment

To change the alignment of images use the HTML <img> tag and add in the align field.

The align field can have 3 inputs, left, right, or center.

Example:

<img align="left" width="200" src="https://thehappypuppysite.com/wp-content/uploads/2017/10/Cute-Dog-Names-HP-long.jpg">
<img align="right" width="200" src="https://thehappypuppysite.com/wp-content/uploads/2017/10/Cute-Dog-Names-HP-long.jpg">

Result:

Links

Adding a link is very straightforward. The syntax to use is:

Syntax:

[DISPLAY NAME](URL LINK)

Example:

[Click Me to Go to GitHub](http://github.com)

Result:

Useful Resources

Mastering Markdown