Intro to Markdown for the BTAA-GIN¶

Part 1: Overview of Markdown¶

What?¶

  • Markdown is a lightweight language for writing text documents

Why?¶

  • allows us to create and store standalone, non-proprietary documents
  • very simple to learn and most text editors support it
  • many tools can transform Markdown to other formats, such as HTML or PDF

Where?¶

  • GitHub
  • Jupyter Notebook
  • Reddit
  • Slack
  • WordPress
  • Stack Overflow
  • Trello
  • and many others that support adding content in Markdown

BTAA-GIN¶

  • Markdown is used to create pages for the gin.btaa.org website
  • Docs on the GIN website start off as Markdown and are converted to HTML upon publishing.

If your committee or workgroup produces a public report, we would like to add it to the GIN website.

If possible, please submit these as Markdown documents.

With Markdown, we can focus on writing, rather than formatting.

Part 2: Let's Learn Markdown!¶

What's in a Markdown file?¶

  • text styles
  • lists
  • paragraph styles
  • tables
  • code
  • links & images

Text Styles¶

In [ ]:
# Heading 1

Heading 1¶

In [ ]:
## Heading 2

Heading 2¶

In [ ]:
### Heading 3

Heading 3¶

In [ ]:
*italics*

italics

In [ ]:
**bold**

bold

Lists¶

In [ ]:
- unordered list
- unordered list
- unordered list
  • unordered list
  • unordered list
  • unordered list
In [ ]:
1. ordered list
1. ordered list
1. ordered list

1. ordered list
2. ordered list
3. ordered list

Paragraph styles¶

Markdown will not automatically produce line breaks.

In [ ]:
This will produce one line,<return>

even if you hit return in the middle.

This will produce one line, even if you hit return in the middle.

In [ ]:
For line breaks,<space><space>

add two spaces at the end of a line.

For line breaks,
add two spaces at the end of a line.

In [ ]:
> Blockquote

Blockquote

In [ ]:
--- 
horizontal rule

horizontal rule

Tables¶

In [ ]:
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1, Column 1 | Row 1, Column 2 | Row 1, Column 3 |
| Row 2, Column 1 | Row 2, Column 2 | Row 2, Column 3 |
| Row 3, Column 1 | Row 3, Column 2 | Row 3, Column 3 |
Column 1 Column 2 Column 3
Row 1, Column 1 Row 1, Column 2 Row 1, Column 3
Row 2, Column 1 Row 2, Column 2 Row 2, Column 3
Row 3, Column 1 Row 3, Column 2 Row 3, Column 3

Code¶

In [ ]:
`Inline code`

Inline code

In [ ]:
```
code block
```

code block

Links & Images¶

In [ ]:
[Link](http://geo.btaa.org)

Link

In [ ]:
![Image](https://images.digital.library.illinois.edu/iiif/2/910a3e90-82d6-0134-1f08-0050569601ca-6/full/175,/0/default.jpg?download=true)

Image

That's pretty much everything - all the syntax you need to create tutorials, guides, and reports.¶

Let's try this interactive tutorial next: https://commonmark.org/help/tutorial/

Part 3: F.A.Q.¶

Why do some sites say to use "-" for bulleted lists while others say to use "* "?¶

You will likely come across various Markdown documentation sites that seem to have conflicting information on syntax. This is because there are several different "flavors" or variations of Markdown that have been developed over the years, each with its own unique features and syntax. However, most platforms seem to accept any version and interpret "-" the same as "* "

Can I embed images right into the Markdown file or do I always need to have them stored separately?¶

Images need to be hosted online, usually in a folder next to the Markdown document. This may take more time that just pasting an image right into a document, such as Google Slides. On the other hand, this may ultimately make a document easier to update and maintain - if we overwrite a new image in a directly using the same, we do not need to edit the Markdown file.

Markdown doesn't include certain features found in HTML. For example, how can I format images?¶

You can always add straight HTML code in your Markdown file and include style elements, such as float, border, or margin.

How do I submit Markdown content to the gin.btaa.org website?¶

  • Markdown can be used for workgroup reports and other documents you would like to be publicly available.
  • To edit the site yourself, review the instructions here: https://github.com/geobtaa/geobtaa.github.io?tab=readme-ov-file#updating-the--website
  • Otherwise, just email or Slack a markdown file to me

Thank you!¶

Questions?