Markdown Tutorial!

In this tutorial, you'll learn how to write Markdown in a hands-on, engaging way. By following the examples and completing the exercises, you’ll soon be able to create well-formatted documents, understand advanced features, and apply Markdown in practical scenarios.

What You’ll Learn

By the end of this tutorial, you will be able to:

1. Select a Markdown Editor: Choose an editor with a real-time preview feature so you can see your changes instantly.
2. Visualize Your Work: Learn how the preview helps you check the final output as you write.
3. Create Simple Documents: Write headings, apply bold and italic formatting, and more.
4. Build Complex Documents: Combine various Markdown elements for advanced documentation.
5. Troubleshoot Markdown: Identify and solve common formatting issues.
6. Apply Markdown in Real Projects: Use Markdown for project descriptions, documentation, and language technology tools like Notion.

1. Getting Started with Markdown

Markdown is a simple way to format plain text that can be easily converted into HTML. It’s used everywhere—from README files on GitHub to documentation on websites.

Your First Task:

• Open your favorite Markdown editor (Visual Studio Code, Atom, or even an online editor like Dillinger).
• Create a new file called tutorial.md and write a short introduction about yourself using Markdown syntax.

2. Core Syntax & Features

Let's explore the basic elements of Markdown. Follow along with the examples, then try writing your own!

2.1. Headers

Headers help you structure your document. Use the # symbol to create them.

Example Markdown Code:

# Header 1
## Header 2
### Header 3

What It Looks Like:

Header 1

Header 2

Header 3

Try It: Create your own headers. Experiment by changing the number of # symbols and see how the header size changes.

2.2. Lists

Lists are a great way to organize information. There are two main types: bullet (unordered) lists and numbered (ordered) lists.

Example Markdown Code:

- Bullet List Item 1
- Bullet List Item 2
- Bullet List Item 3

1. Numbered List Item 1
2. Numbered List Item 2
3. Numbered List Item 3

What It Looks Like:

• Bullet List Item 1
• Bullet List Item 2
• Bullet List Item 3

1. Numbered List Item 1
2. Numbered List Item 2
3. Numbered List Item 3

Try It: Create a list of your favorite hobbies using both bullet and numbered lists.

2.3. Emphasis (Bold & Italic)

Emphasize text to make it stand out.

Example Markdown Code:

*This text is italicized.*

**This text is bold.**

***This text is both bold and italicized.***

What It Looks Like:

This text is italicized.

This text is bold.

This text is both bold and italicized.

Try It: Write a short sentence about your day and experiment with bold and italic text to highlight important words.

2.4. Links & Images

Create clickable links and add images to your document.

Example Markdown Code:

[Visit OpenAI](https://www.openai.com)

![Random Image](https://picsum.photos/100)

What It Looks Like:

Visit OpenAI

Try It: Add a link to your favorite website and include an image that represents something you like.

3. Advanced Markdown Features

Once you’re comfortable with the basics, try these advanced elements.

3.1. Code Blocks

Display code with proper formatting. You can also specify the language for syntax highlighting.

Example Markdown Code:

```python
def greet():
    print("Hello, Markdown!")
```

What It Looks Like:

def greet():
    print("Hello, Markdown!")

Try It: Write a small snippet of code in your favorite programming language using a code block.

3.2. Tables

Tables help you display data neatly.

Example Markdown Code:

| Column 1       | Column 2       |
|----------------|----------------|
| Row 1, Cell 1  | Row 1, Cell 2  |
| Row 2, Cell 1  | Row 2, Cell 2  |

What It Looks Like:

Try It: Create a table that lists your favorite books along with their authors.

3.3. Blockquotes

Blockquotes are perfect for quoting text or highlighting information.

Example Markdown Code:

> This is a blockquote.
> It can span multiple lines.

What It Looks Like:

This is a blockquote.
It can span multiple lines.

Try It: Use a blockquote to display a motivational quote.

3.4. Horizontal Rules

Use horizontal rules to separate sections visually.

Example Markdown Code:

---

or

***

What It Looks Like:

or

Try It: Insert a horizontal rule between sections of your document.

3.5. Inline HTML

Sometimes, you might need a little extra styling. Inline HTML lets you do that.

Example Markdown Code:

<p style="color: red;">This text is styled with HTML.</p>

What It Looks Like:

<p style="color: red;">This text is styled with HTML.</p>

Try It: Add a piece of inline HTML to style a section of your text.

4. Tools & Editors

Markdown is simple, but using the right tools can make it even easier. Experiment with different editors that support real-time preview, like:

• Visual Studio Code
• Notepad++
• Online editors like Dillinger

Exercise 1: Practice using a Markdown editor with real-time preview.
Click to do Exercise 1: Using Markdown Panel

5. Practical Applications

Markdown isn’t just for practice—it’s used in many real-world scenarios:

• Documentation: Write README files for your projects.
• Version Control: Use Markdown to explain changes in your Git commits.
• Content Management: Format blog posts or articles for websites and static site generators like Jekyll or Hugo.

Try It: Write a simple README for a project you’ve worked on using Markdown.

6. Best Practices

Keep your Markdown documents clear and maintainable by:

• Staying Consistent: Use the same header levels and formatting throughout.
• Organizing Content: Break long documents into sections.
• Collaborating Effectively: Use Markdown in pull requests or shared documents.

Tip: Review your document in the preview pane often to ensure everything looks as expected.

7. Customizations and Extensions

Explore different flavors of Markdown:

• Standard Markdown vs. GitHub Flavored Markdown
• Extensions & Plugins: Add footnotes, diagrams, or math expressions as needed.

Try It: Experiment with an online Markdown editor that supports GitHub Flavored Markdown.

8. Real-World Examples & Demos

Seeing is believing! Check out these real-world examples:

• Case Studies: Look at how developers use Markdown in project documentation.
• Live Demos: Convert Markdown to HTML in real-time using your editor.

Exercise 2: Explore how Markdown is used in Paratext by following this exercise.
Click to do Exercise 2: Using Markdown in Paratext

9. Interactive Session

Now it’s your turn to apply what you’ve learned:

• Q&A Session: Ask questions and share your experiences with Markdown.
• Group Exercise: Work together to troubleshoot a Markdown document with common errors.

Exercise 3: Test your troubleshooting skills with this interactive challenge.
Click to do Exercise 3: Troubleshooting Markdown

10. Additional Resources

Keep exploring with these helpful resources:

• Cheat Sheets & Guides:
  • Markdown Guide Cheat Sheet
  • CommonMark Specification
• Community Support:
  • Visit Stack Overflow and search for the Markdown tag for tips and discussions.

Happy Markdowning!
Experiment, make mistakes, and have fun learning how to format your documents with ease.