Let’s Learn Markdown

The orientations below are from Rafa Davis’ workshop on Markdown. Make sure to open your spreadsheet on Leonor López de Córdoba to implement changes on your text using Markdown!

Introduction

What is markdown, and markup languages in general?

• A markup language is a system for annotating your text through instruction encapsulated by tags.
• You write in plain text to create rich text.
  • Most famous one: HTML
• Markdown is a language designed for writing.
• It is light enough that allows us to read the text without visual polution.

Why not Microsoft Word or Google Docs?

• Word seems easy now, but it will drive you crazy in the long run.
• Microsoft Office package is expensive.
• Files are not universal.
• Word is very distractive.
• Problems with incompatibility.
• Files are heavier and tend to corrupt.
• Problems merging files, copying text from other files, numbering.

Why should I use Markdown?

• You can make beautiful professional formatting without much work.
• It can easly be converted to other formats: doc, pdf, html, etc.
• Separation of form and content allows you to focus on your writing.
• Text editors are meant to be worked with text structure, so they force you to think about the organization of your writing.
• Future proofing your files: plain text files are universal. They will work on any computer, of any operational system, forever.
• There is no lock-in. If you don’t like it, you can convert the files to doc files (bleargh) and go back to work the way you used to.
• Variety: You can use multiple great softwares to write your dissertation, a lot of them free and open source. It is so light, you can take a look at your work in your cellphone in the subway and edit that paragraph that you cang get off of your mind.
• The more you learn, the more powerful tools you can access, such as automatic citations.
• If you are writing a dissertation, or a thesis, there is a good chance your university has the template ready, so you don’t need to worry about adjusting to their standards.

Writing in Markdown

Headings

Headings are how we structure our text. When we are writing, we should be thinking about the divisions and subdivisions of our text. Markdown helps us with that. To start a new heading, we need to use to start a line with the pound symbol “#” (also called “hash”, “number”, among other words).

The level of your heading is equal to the number of “#”. This is an example of how it works. The following could be the structure of an article:

# Development

# Introduction

Here I would write my introduction.

## Hypothesis A

Describe some valid hypothesis.

## Hypothesis B

Here I describe another interesting point.

# Conclusion

Here is my conclusion.

Now let’s try something.

• In the beginning of your new file, type “# Basic Formatting” and press Enter
• On the next line, type “## Headings” and press Enter
• On the next line, write “Just a simple text line so we can see how it looks like.”

Let’s see how it went:

• In VS Code, on the upper right corner, there is an icon for Open Preview. (Alternatively, you can press “Ctrl/Cmd + k” than “v”, but that won’t work if you do it slowly.)

Paragraphs and line breaks

To create a new paragraph, press enter twice and start typing. This will create a blank line between the last piece of text and the next one. Try the following:

## Paragraph

If you write this here and then  write in the next line.
Like this.
All those three lines will be together in the same paragraph.

However, this will be a new paragraph, since we skipped a line.

For line breaks, there are two options. You can either press space twice in the end of the line, or you can type “" in the end of the line. The second method is preferred, since it is something you and other people can see in the code.

Let’s say we want to try a little poem. Try to make this (or any other short poem in your mind):

## Line Breaks

Ah, what an age it is
When to speak of trees is almost a crime
For it is a kind of silence about injustice!
And he who walks calmly across the street,
Is he not out of reach of his friends
In trouble?

Emphasis

• Wrap the word/sentence with * to make it Italic.
• Wrap the word/sentence with ** to make it Bold.

Therefore, if you write this:

This sentence is normal, but this word is *italic*, 
this one is **bold**,and these are ***italic and bold***.

*This whole sentence is italic, but this word is also **bold***.

You will get this:

This sentence is normal, but this word is italic, this one is bold, and these are italic and bold.

This whole sentence is italic, but this word is also bold.

Block quotes:

Start a line with greater than “>”, press space and start writing. To write a blockquote which is longer than a paragraph, make sure to use the “>” sign in the blank line between one paragraph and the other.

• Type “## Block Quotes”, press enter
• Now, try to make produce this:

This is my first block quote. I will just write some more to make sure it is longer than a line.

Amazing, it even has two different paragraphs.

Lists:

• Type “## Lists” and press enter

Lists are easy to do. Unordered lists can be done with *, + or - symbols. Simply start your paragraph with one of them, press space and type the list item. Than, press enter to go to the next line and do the same.

To make a nested list, with sub-items, just press space for times before using the list symbol.

• Type “### Unordered” and press enter

Now try to make this groceries list:

• Bread
• Eggs
• Fruits
  • Apple
  • Bananas
• Milk

Ordered lists can be done either with “1.” or “1)”. The number don’t actually matter. you can always use “1.” if you want, the program will make sure to count and put it in the right order. This is good because you don’t have to worry about chaning the numbers if you decide to change the order. You can also mix unordered and ordered lists.

• Type “### Ordered” and press enter.
• Now try to make this list of steps to make a trip:

1. Buy airplane tickets
2. Make hotel reservation
3. Packing
   • Shoes
   • Socks
   • Shirts
4. Ask mama to water the plants

Advanced Tools

Comments

• Type “## Comments” and press enter

Comments are a fundamental part of coding, but it can also be very handy to academic writing. Whatever you comment on your file is not going to show up in your final document. This is useful for writing alternative paragraphs that you can decide to change later, leaving comments to yourself of stuff you need to work, decreasing the lenght of an article for a specific publication, etc.

To open a comment, just type <!-- , and close it with --> . Whatever is inside those, will not show up in the final version.

• Now type this and see what happens:

This should show up in the final version, <!-- This should not show up, --> and this should also show up.

Links

• Type “## Links” and press enter

The way to create a link is: [This is the text of the link](link address)

• Now try this: [GCDI](https://gcdi.commons.gc.cuny.edu)

• If you just want to show the address, there is a simpler way to do it. Just wrap it with < and >. For example: <https://gcdi.commons.gc.cuny.edu/>

Images

• Type “## Images” and press enter

The way to create images is: ![text](filename.extension)

• For instance: ![weird cat](cat.jpg). For this to work, you need to have the image file (in this case, “cat.jpg) in the same folder as your text file.

  • If you are working with a lot of images, it might make sense to have a sub-folder of all the images you are using in this project. In that case, your link could be ![weird cat](images/cat.jpg)
• Another option is to use a link in the web. Try this: ![satisfied dog](goo.gl/uGkft3)
• Hint: We can add images to out folder /assets/img/