Guide to the Markdown Syntax
This guide examines how to work with the markdown syntax. Learning markdown will allow you to style Readme files, add items such as syntax highlighting to GitHub comments, and much more.
Guide Tasks
  • Read Tutorial
  • Watch Guide Video
Video locked
This video is viewable to users with a Bottega Bootcamp license
APPLY NOWLEARN MORE

In this guide, I'm going to talk about markdown. Looking at your GitHub repo you will see the README.md, section. Markdown syntax gives this section its formatting.

Open your README.md file in sublime. The file name ends with .md, because it is written in markdown. In many ways, this is similar to a programming language like HTML.

It's incredibly vital to know markdown, especially if you’re working with applications and specifically if you are going to work with repositories like GitHub. Most version control systems allow you to integrate styles into your comments and documentation. Markdown is the industry standard for adding these styles, and that is why your README file is in markdown.

I want to give you a basic tutorial on markdown, but I will also give you some resources because there is so much material available that we won’t be able to cover with this short guide.

A good place to learn more about markdown is www.markdowntutorial.com. It's a dynamical tutorial that'll walk you through the process of learning it.

Another good resource, and the one I usually reference, is www.daringfireball.net. They have one of the most well renowned tutorials on how to understand the markdown syntax. They have great documentation that explains how to do everything from creating headers to adding code snippets.

Why should you learn Markdown?

You may be wondering how important it is to learn Markdown. I've explained the importance of using it for version control items, but that is not all.

Markdown is growing in importance, as it is used across different fields. For example, I wrote my ebook completely in markdown. Leanpub.com allows you to build an entire book in markdown.

Also, all tutorials on DevCamp are written using markdown language. It allows you to add images and code snippets with a fairly basic syntax.

The Syntax

Next, let's go through some popular syntax used in markdown.

Open up your README.md file. Go ahead and delete everything except for line 1.

That should still read

# Devcamp Portfolio Application

or # followed by whatever you have chosen as your app name.

Next, let’s add a block quote. For this you will use the > symbol. We will follow that with information about what the app does.

> This is a Ruby on Rails 5 application that allows users to create their own portfolios.

Next, we will list out the features. We will use an H3 size header , so we will use ###

Notice that line 1 uses a single # . That is for an H1 size header. (Hence, the number of #s you have determines the size of the header).

We want to list our features using bullet points. For that we will use -

So our features section syntax will look like this:

### Features

- Real time chat engine for comments
- Blog
- Portfolio
- Drag and drop interface

Make sure you leave a line between the Features header and the list, or the syntax will not work properly.

Adding a Code Snippet

We can also include a code example using the back tics symbol that is located just below the ESC key on your keyboard ( ` ). Do not confuse this with the quotation symbol. The Syntax we want looks like this:

### Code Example

```ruby
def my_great_method
  puts "here it is"
end
```

We can also have javascript or any other language inside of a block that starts and ends with three back tics. 

```javascript
alert('Hi there')
```

Push your changes to GitHub

Now, go to terminal, and enter the git status command. You should see that the README.md file has been modified. Follow this with git add . and git commit -m ‘Updated the readme with guide for markdown’. Last use the git push command.

Now you can go to the browser, refresh your GitHub page and and you can see your updated README.md file.

You have an nice H1 tag displaying your app name at the top. Notice, how the block quote is indented and has an attractive little highlighting feature. Your bullet points are displaying nicely, and your code snippets even have syntax highlighting.

I truly appreciate how easy markdown is to use. The syntax may look a little peculiar at first, but I guarantee that the more you use it the more you will like it and find it is preferential to the fancier styling options available.

So, that is how you can integrate markdown into your application in the README.md file.

Using Markdown in GitHub

I want to show you how you can use markdown in GitHub. Go to the issues tab. This is Github’s area dedicated to bug tracking. You can click on the button that says New Issue. Take note that the form has a notice that let's us know styling with markdown is supported. You will find this support available to you throughout GitHub!

Go ahead and give the issue a title, such as ‘Some Issue’. In the description, using markdown language explain where the bug is by adding this markdown syntax:

## There is a bug here:

``` ruby
def some_method
  puts "aeiou"
end
 ```

Then, click the Submit new issue button.

Now your issue is listed with a comment explaining the details, but that information is supported with full syntax highlighting and any styling you want with your markdown syntax. You can also include images such as a logo or a screenshot.

In my devCamp repo I keep a style guide and rules. That way, other team members who are also working on the app can use the README as a reference guide.

So, that is an introduction on how you can begin to implement markdown.

Resources