Master Git & GitHub From Scratch

Clear, practical, and structured lessons designed to take you from Git fundamentals to real-world GitHub collaboration.

Markdown Documentation

Markdown is a lightweight markup language that formats plain text using simple, readable symbols. GitHub automatically renders Markdown files with headings, lists, links, tables, and code blocks.

Markdown files commonly use the .md extension. The most important example in many repositories is README.md, which introduces the project and explains how to use it.

Remember: Markdown is plain text. You can edit it using Visual Studio Code, Notepad, or GitHub's built-in file editor.

1. Headings

Use the hash symbol (#) followed by a space to create headings. The number of hashes determines the heading level.

# Document Title
## Major Section
### Subsection
#### Smaller Heading
##### Level Five Heading
###### Level Six Heading
Rendered Example

Document Title

Major Section

Subsection

2. Text Formatting

Use Markdown symbols to emphasize important text.

*Italic text*
**Bold text**
***Bold and italic text***
~~Strikethrough text~~
Rendered Example

Italic text

Bold text

Bold and italic text

Strikethrough text


3. Lists

Use hyphens or asterisks for bullet lists and numbers for ordered lists.

- First item
- Second item
  - Nested item





1. First step
2. Second step
3. Third step
Rendered Example
  • First item
  • Second item
    • Nested item
  1. First step
  2. Second step
  3. Third step

4. Links and Images

Links use square brackets for the display text and parentheses for the destination URL. Images use the same syntax with an exclamation mark at the beginning.

[GitHub](https://github.com)

![Project Architecture](./images/architecture.png)
Rendered Example

GitHub

An image will appear when the specified image path exists in the repository.

Tip: Use descriptive alternative text for images. Relative paths such as ./images/architecture.png are useful when the image is stored inside your repository.

5. Inline Code and Code Blocks

Use single backticks for commands inside a sentence. Use triple backticks for multi-line code examples. Adding a language identifier enables syntax highlighting on supported Markdown platforms.

Use `git status` to check repository changes.

Example of a fenced Bash code block:

```bash
git checkout -b feature/login
git add .
git commit -m "Add login feature"
```

On GitHub, the fenced example is rendered as a formatted code block rather than ordinary paragraph text.


6. Tables

Tables help present commands, descriptions, and other structured information.

| Command | Purpose |
| --- | --- |
| `git pull` | Fetches and integrates remote changes |
| `git push` | Uploads local commits to a remote repository |
| `git status` | Shows the working tree status |
Rendered Example
Command Purpose
git pull Fetches and integrates remote changes
git push Uploads local commits to a remote repository
git status Shows the working tree status

7. Task Lists

GitHub supports task lists that are useful for tracking project setup steps and documentation work.

- [x] Create project repository
- [ ] Configure GitHub Actions
- [ ] Deploy production files
Rendered Example

Create project repository

Configure GitHub Actions

Deploy production files


8. Writing a Good README.md

A useful README helps developers understand your project before they start using or contributing to it.

# Project Name

## Overview
Describe what your project does.

## Features
- Feature one
- Feature two

## Requirements
List the required software and dependencies.

## Installation
Explain how to clone and configure the project.

## Usage
Show how to run and use the application.

## Contributing
Explain how others can contribute.

A README commonly includes:

  • Project name and purpose
  • Features and screenshots
  • Prerequisites and installation steps
  • Usage instructions and examples
  • Contribution guidelines and license information

9. Markdown Best Practices

  • Use headings to divide long documents into clear sections.
  • Keep paragraphs short and easy to scan.
  • Format terminal commands using inline code or fenced code blocks.
  • Use meaningful link text and image alternative text.
  • Include installation and usage instructions in your README.
  • Preview the rendered Markdown before publishing changes.
Key Takeaway
Markdown makes project documentation readable, maintainable, and easy to publish. Learn these basic elements to create better README files, contribution guides, and technical documentation.
← Previous GitHub Pages