10. Markdown & Project Wikis

Clear documentation is a hallmark of professional software development. GitHub utilizes GitHub Flavored Markdown (GFM) across issues, PRs, comments, and readmes. Additionally, it provides **Wikis** for writing long-form developer documentation. In this chapter, we will learn how to write rich GFM and structure a project Wiki.

1. GitHub Flavored Markdown (GFM) Guide

Markdown is a lightweight markup language that allows you to format plain text using simple symbols. Here is a cheatsheet of the most commonly used GFM syntax:

Headers

# Heading 1 (h1)
## Heading 2 (h2)
### Heading 3 (h3)

Text Formatting

This is **bold text** and this is *italic text*.
You can also use ~~strikethrough text~~.

Lists & Task Checklists

# Unordered List
- Mangoes
- Apples

# Task Checklist
- [x] Complete landing page design
- [ ] Add form validation rules

Code Blocks with Syntax Highlighting

Wrap code in three backticks and specify the language to enable professional syntax highlighting:

```javascript
const sayHello = () => {
  console.log("Hello GitHub!");
};
```

Tables

| Header 1 | Header 2 |
|----------|----------|
| Row 1    | Value 1  |
| Row 2    | Value 2  |

2. Structuring Project Wikis

While a README.md is great for a quick introduction, complex projects with extensive guides, architecture diagrams, and API documentation require a **Wiki**.

To activate and create a Wiki:

1. Go to your repository and click the Wiki tab.
2. Click "Create the first page".
3. Give the page a title (e.g., Home or API-Specification) and write the content in Markdown.
4. Click "Save page".

You can create a structured sidebar on the right by adding a page named _Sidebar, which lets you link pages together like a book index!

git clone https://github.com/username/project.wiki.git