Academic documents are organized using semantic elements such as headings, paragraphs, and lists, which are usually highlighted using different visual features such as font size, font weight, and spacing. Rather than intuitively marking up the semantic sections of your writing with visual features, in a markup language we explicitly tag our content using standardized syntax.

Markdown provides a set of basic conventions to mark this semantic structure more formally, while keeping it simple.

Head to the Demo editor or Dillinger web-based editor to practice some Markdown basics.

Headings

Headings range from level one to six, with one being the most important concepts. They should move up in order without skipping a level.

Be sure to include a blank line above and below a heading.

# Heading One

## Heading Two

### Heading Three

Note: headings using the # are called “ATX-style”. Less commonly, you may also see “Setext-style” which uses a row of equal signs below heading one and hyphens below heading two, like:

Header One
==========

Header Two
----------

Paragraphs

Paragraphs don’t require any special markup. Just leave an empty line between your paragraphs and any other block element. For example:

Any text with no empty lines between will be joined into a paragraph.
Leave an empty line between headings and paragraphs.

Since there is an empty line above, 
this will start a new paragraph.
This gives you the option to write a paragraph all on one line 
(like a word processor),
or to put each sentence on its own line.
Splitting the sentences can make editing and version control easier. 

Lists

A bullet list (i.e. unordered list) is created using - followed by a space (alternatively can use * or +). Put each list item on a new line. A numbered list (i.e. ordered list) is created using a number + . followed by a space. The items will be automatically renumbered correctly in outputs. Both kinds of lists can be nested by tabbing in a level.

- dog
- cat
- muffin

1. dog
2. cat
6. muffin
1. other thing

1. dog
    - bark
    - wag
2. cat
    - meow
6. muffin
    - yum

- [ ] task one
- [x] completed task

Inline Elements

*Emphasis* or _emphasis_

**Strong** or __strong__

**_Strong and Emphasis_**

[hyperlink](https://www.google.com)

Link:
<https://www.wikipedia.org/>

Email: 
<example@email.com>

image: 

![alt text](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/208px-Markdown-mark.svg.png)

example footnote.[^1]

[^1]: footnote definition will show up at bottom.

Note: always be sure to include high quality alt text for your images and descriptive text in your hyperlinks (i.e. don’t use “click here”)!

Code

Code can be highlighted inline with `backticks`.

```
Or make a code block 
open with three backticks alone on a line 
and close with three more on a line. 
```

This makes it easier to copy unformatted code/text

Or make a code block 
open with three backticks alone on a line 
and close with three more on a line. 

Tables

Tables aren’t supported by all Markdown converters, but can be useful for some quick structure.

| column1 | column2 | column3 |
| --- | --- | --- |
| value | value | value |
| value | value | value |

Block Quotes

> Each line starts with greater-than space.
> Any other markdown can be used.

Horizontal Rule

Three or more dashes on a line:

-----

HTML

Any HTML is also valid in a Markdown file. This is helpful for adding content beyond the simple elements represented by the syntax, for example, embedding an iframe or interactive feature.

Any HTML elements should have a blank line above and below. Avoid any blank lines inside the HTML elements.

Note that Markdown will not be processed inside the HTML tags.

Comments

<!-- you can use HTML comments, they won't show up visually in outputs -->

Escaping

If you ever need to have Markdown ignore a character that would normally be part of the syntax, you can escape with a \ backslash.

For example, \*with asterisks\* will be *with asterisks*.

Markdown Flavors

It is important to keep in mind that Markdown isn’t an 100% formal standard, but comes in “flavors” from various implementations. Each implementation has extensions to the Markdown syntax or extra features they support. Some common flavors:

• CommonMark (standardized specification)
• GitHub Flavored Markdown (GFM) (popular style that can be used any where on GitHub)
• R Markdown (RStudio’s mix of R code blocks and Markdown)
• Pandoc Markdown (document-centric extensions)

So exactly what you can include in your Markdown writing depends on what tools you are using to process it. If you want your Markdown to be interoperable between tools and platforms, keep to the basics!

Semantics and Accessibility

It is important to remember that when using Markdown we are trying to semantically mark up our text content. The headings, inline formatting, and elements are not just for the look, but indicate the meaning and function of the text. This has the advantage of separating semantics and presentation styles, which can make it easier to write and create beautiful outputs.

To create useable, accessible documents, be sure to follow best practices for the markup.

• Use Headings
  • Start with heading 1 (the most important heading, generally the title).
  • Follow a sequential heading hierarchy 1 through 6 with out skipping a level. You can jump back up!
  • Heading indicate structure, not just style formatting.
  • Headings should break up the text into meaningful, readable chunks.
  • Headings should be clear and descriptive, helping people understand the content and organization (without reading the whole page!)
• Write quality alt text for all images
  • Be sure to convey the visual information presented by the image in a clear and concise form.
  • For charts and data visualizations be sure to include a short description of the content, chart type, and purpose. Try to provide the data as a table in addition to the chart.
  • Step-by-Step Instructions for Writing Alt Text, University of South Carolina
• Use descriptive text in hyperlinks
  • Never create a link with “click here”!
  • Readers eyes jump to links in text, be sure to make the content meaningful.