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:
- Select a Markdown Editor: Choose an editor with a real-time preview feature so you can see your changes instantly.
- Visualize Your Work: Learn how the preview helps you check the final output as you write.
- Create Simple Documents: Write headings, apply bold and italic formatting, and more.
- Build Complex Documents: Combine various Markdown elements for advanced documentation.
- Troubleshoot Markdown: Identify and solve common formatting issues.
- 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.mdand 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
- Numbered List Item 1
- Numbered List Item 2
- 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)
What It Looks Like:
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:
| Column 1 | Column 2 |
|---|---|
| Row 1, Cell 1 | Row 1, Cell 2 |
| Row 2, Cell 1 | Row 2, Cell 2 |
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:
-
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.