Markdown Tutorial

Markdown is a lightweight markup language that software engineers use daily for documentation, README files, and technical writing. This guide covers everything you need to know to use Markdown effectively in your development workflow.

Table of Contents

• Basics
• Text Formatting
• Lists
• Links and Images
• Code
• Tables
• Blockquotes
• Horizontal Rules
• Extended Syntax
• Best Practices
• Tools

Basics

Markdown files use the .md or .markdown extension. They can be converted to HTML, PDF, or other formats using various tools.

The philosophy behind Markdown is readability: a Markdown document should be publishable as-is, without looking like it’s been marked up with tags or formatting instructions.

Text Formatting

Headings

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Emphasis

*Italic text* or _Italic text_
**Bold text** or __Bold text__
***Bold and italic*** or ___Bold and italic___
~~Strikethrough~~

Example: Italic text and Bold text and Bold and italic and Strikethrough

Lists

Unordered Lists

- Item 1
- Item 2
  - Nested item 2.1
  - Nested item 2.2
- Item 3

Example:

• Item 1
• Item 2
  • Nested item 2.1
  • Nested item 2.2
• Item 3

Ordered Lists

1. First item
2. Second item
3. Third item

Example:

1. First item
2. Second item
3. Third item

Task Lists

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Example:

• Completed task
• Incomplete task
• Another task

Links and Images

Links

[Link text](https://www.example.com)
[Link with title](https://www.example.com "Link title")

Example: GitHub

Reference-style Links

[Link text][reference]

[reference]: https://www.example.com "Optional title"

Images

![Alt text](image-url.jpg)
![Alt text](image-url.jpg "Optional title")

Code

Inline Code

Use the `printf()` function.

Example: Use the printf() function.

Code Blocks

```javascript
function hello() {
  console.log("Hello, world!");
}
```

Example:

function hello() {
  console.log("Hello, world!");
}

Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Example:

Alignment

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|-------------:|
| Left         | Center         | Right        |

Example:

Blockquotes

> This is a blockquote.
> 
> > This is a nested blockquote.

Example:

This is a blockquote.

This is a nested blockquote.

Horizontal Rules

---
***
___

Example:

Extended Syntax

Note: Extended syntax may not be supported in all Markdown processors.

Footnotes

Here's a statement with a footnote. [^1]

[^1]: This is the footnote.

Definition Lists

term
: definition

Mathematics (with MathJax or KaTeX)

When $a \ne 0$, there are two solutions to $ax^2 + bx + c = 0$:

$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$

Best Practices for Software Engineers

1. Document structure: Start with a clear title and description, followed by installation instructions, usage examples, and API references.

2. Code examples: Always include code examples for APIs, functions, or classes.

3. Version control: When updating documentation, clearly mark deprecated features or breaking changes.

4. Commenting: Use HTML comments for notes that shouldn’t be visible in the rendered output:

   <!-- TODO: Update this section with more examples -->

5. READMEs: Structure your GitHub READMEs with:

   • Project title and description
   • Installation instructions
   • Basic usage example
   • Features
   • API documentation
   • Contributing guidelines
   • License information

6. Relative links: Use relative links to reference other files in your repository:

   [Go to docs](./docs/index.md)

Tools for Markdown

Editors with Markdown Support

• Visual Studio Code: With Markdown Preview
• JetBrains IDEs: With Markdown plugin
• Atom: Native Markdown support
• Sublime Text: With Markdown packages

Online Editors

• HackMD: Collaborative Markdown editor
• Dillinger: In-browser Markdown editor
• StackEdit: Feature-rich Markdown editor

Converters

• Pandoc: Convert between Markdown and many other formats
• GitHub Actions: Automated publishing workflows for Markdown docs

GitHub-Flavored Markdown Extras

GitHub has its own flavor of Markdown with additional features:

1. Username mentions: @username
2. Issue/PR references: #123
3. Emoji: :smile: (:smile:)
4. SHA references: Reference commits by SHA
5. Automatic linking: URLs are automatically converted to links

Conclusion

Markdown’s simplicity makes it an essential tool for software engineers. By mastering these basics, you’ll create better documentation that’s easier to maintain and more useful to your users and fellow developers.

Remember, good documentation is as important as good code. Investing time in creating clear, comprehensive Markdown documents will pay dividends throughout your project’s lifecycle.