Skip to main content

Markdown for GitHub Documentation

In the developer world, your code is only as good as your documentation. Markdown is a lightweight markup language that allows you to add formatting (headings, lists, links, images) using plain text.

At CodeHarborHub, we use Markdown for everything: README files, Issue descriptions, Pull Request comments, and even these tutorial pages!

tip

Don't worry if you've never heard of Markdown before! It's designed to be simple and intuitive. This guide will cover all the basics you need to know to create professional documentation that stands out on GitHub.

1. Structure: Headings​

Headings create a hierarchy in your document, making it "scannable." Use the # symbol followed by a space.

Heading Syntax
# H1: Project Title (Only use one per file)
## H2: Major Sections (About, Installation)
### H3: Sub-sections
#### H4: Minor Details

It's best practice to use only one H1 per file (usually the project title) and then use H2s and H3s to organize your content. This helps readers quickly find the information they need.

2. Emphasis: Bold, Italic, and Strikethrough​

Highlighting key terms helps learners focus on what's important.

ResultSyntax
Bold Text**Bold Text**
Italic Text*Italic Text*
Strikethrough Text~~Strikethrough Text~~
Bold & Italic (Combined) Text***Bold & Italic (Combined) Text***

3. Lists: Organized Thoughts​

Unordered Lists​

Use an asterisk *, hyphen -, or plus +.

Code Example:

* Item 1
* Item 2

Preview:

  • Item 1
  • Item 2

Ordered Lists​

Use numbers followed by a period.

Code Example:

1. First step
2. Second step

Preview:

  1. First step
  2. Second step

Task Lists (Checklists)​

Perfect for tracking project progress at CodeHarborHub.

Code Example:

- [x] Create repository
- [ ] Write documentation
- [ ] Push to main

Preview:

  • Create repository
  • Write documentation
  • Push to main

In this example, the first task is completed (checked), while the others are still pending.

4. Code: Inline and Blocks​

This is the most important feature for developers.

Inline Code​

Use a single backtick (`) to mention a variable or command like git status inside a sentence.

Code Blocks​

Use triple backticks (```) to create a standalone block. You can add the language name for syntax highlighting.

Example:

```javascript
function greet() {
  console.log("Welcome to CodeHarborHub!");
}
```

Preview:

function greet() {
  console.log("Welcome to CodeHarborHub!");
}

This will render a nicely formatted JavaScript code block, making it easier for readers to understand and copy your code.

Markdown makes it easy to connect resources.

Links: [Clickable Text](https://codeharborhub.github.io)

Images: ![Alt text for screen readers](https://codeharborhub.github.io/img/hero-img.png)

6. Blockquotes and Horizontal Rules​

Blockquotes are great for tips or warnings:

"Open Source is about collaboration, not just code." — CodeHarborHub

Horizontal Rules create visual breaks: Use three dashes: ---

7. Tables: Comparing Data​

Tables are perfect for listing project dependencies or comparison charts.

| Feature | Basic | Pro |
| :--- | :--- | :--- |
| Storage | 1GB | Unlimited |
| Support | Email | 24/7 Live |

Best Practices for CodeHarborHub​

  1. Use H1 for Titles Only: Use only one # at the top of your file.
  2. Meaningful Alt-Text: When adding images, describe the image in the [] so visually impaired developers can understand your docs.
  3. Preview Before Committing: In VS Code, press Ctrl + Shift + V to see how your Markdown looks before you push it to GitHub.
tip

GitHub supports "Emoji Codes"! You can add personality to your READMEs by typing things like :rocket: (🚀), :white_check_mark: (✅), or :tada: (🎉).

Now that you know the basics of Markdown, you can create professional documentation that not only looks great but also helps other developers understand and use your projects effectively.