Getting started with Markdown on GitHub

Key Concepts

• Markdown: A lightweight markup language used for formatting plain text.
• Repository Readme: The primary documentation file for a project.
• Syntax: The specific set of symbols used to trigger formatting in Markdown.
• Markdown Interpreter: The engine that converts Markdown syntax into rendered, readable text.
• Code Snippets: Blocks of code displayed with syntax highlighting.

1. Introduction to Markdown

Markdown is described as an essential, lightweight language for formatting plain text. Its primary purpose is to create clear, readable documentation. On platforms like GitHub, it is used extensively in repository README.md files, issues, pull requests, discussions, and wikis. Beyond GitHub, it is a standard tool for note-taking apps, blogging platforms, and technical documentation tools.

2. Core Formatting Syntax

The video outlines specific symbols used to transform plain text into structured content:

• Headers: Created using the hash symbol (#). One hash denotes a main header, two hashes a subheader, and so on.
• Emphasis:
  • Italics: Wrap text in a single asterisk (*text*).
  • Bold: Wrap text in double asterisks (**text**).
  • Bold & Italics: Wrap text in triple asterisks (***text***).
• Blockquotes: Use the greater-than symbol (>) at the start of a line. For multi-line quotes, each line must begin with the > symbol.

3. Lists and Hierarchies

Markdown supports two primary types of lists:

• Ordered Lists: Created by numbering items (e.g., 1., 2.). Markdown interpreters are flexible; even if numbers are out of sequence, the interpreter will render them as a sequential list.
• Unordered Lists: Created using a hyphen (-), asterisk (*), or plus sign (+).
• Nested Lists: To create a sub-list, indent the item by four spaces. To exit a list and return to plain text, hit "Enter" twice.

4. Code Snippets

To display code, Markdown uses the backtick (`) character:

• Inline Code: Surround the text with single backticks.
• Code Blocks: Surround multi-line code with triple backticks (```). This preserves spaces and new lines and often triggers syntax highlighting in supported environments.

5. Links and Images

These elements use a specific bracket-and-parenthesis structure:

• Links: Format as [Display Text](URL).
• Images: Format as ![Alt Text](Image URL).
  • Note: Adding an exclamation point (!) at the beginning distinguishes an image from a standard link. On GitHub, dragging and dropping an image into an issue or pull request automatically generates this syntax.

Synthesis and Conclusion

Markdown is a foundational skill for developers that significantly improves the quality and accessibility of project documentation. By mastering basic syntax—headers, lists, emphasis, code blocks, and media embedding—users can ensure their GitHub projects are professional, consistent, and easy for others to navigate. The video emphasizes that Markdown is not just a GitHub-specific tool but a universal skill for modern digital communication and technical writing. For further practice, the video recommends visiting gh.io/github-markdown.