Getting Started with Markdown in VS Code

Introduction to Markdown

Markdown is a lightweight markup language created by John Gruber and Aaron Swartz to enable people "to write using an easy-to-read, easy-to-write plain text format, and optionally convert it to structurally valid XHTML (or HTML)." Its primary goal is simplicity and readability. This section introduces you to the basics of Markdown syntax, covering the essentials needed to start writing your documentation.

Basic Syntax

• Headings: Created by adding one or more # before your heading text. The number of # you use will determine the level of the heading.
• Paragraphs: Separate text into paragraphs by leaving a blank line between lines of text.
• Bold and Italic: Use **bold** for bold text and *italic* or _italic_ for italic text.
• Lists: Use - or * for unordered lists and numbers for ordered lists.
• Links: Create links using [link text](URL).
• Images: Add images using ![alt text](image URL).

Extended Syntax

Some Markdown applications support additional elements like tables, footnotes, definition lists, and fenced code blocks. VS Code, coupled with extensions, can enhance these capabilities, making it ideal for more complex documentation needs.

!TODO
Fill in information about GitHub markdown and custom extensions

• Code Blocks: Use triple backticks ``` before and after your code block. Optionally, you can specify a language for syntax highlighting.
• Tables: Create tables using dashes - for headers and pipes | for column dividers.
• Task Lists: Make task lists with - [ ] for an unchecked box and - [x] for a checked box.

Setting Up VS Code for Markdown Editing

Visual Studio Code (VS Code) is a powerful, open-source code editor developed by Microsoft. It supports a myriad of programming languages and markup languages, including Markdown. Here's how to set up VS Code for Markdown editing:

Installation

1. Download and Install: If you haven't already, download VS Code from the official website and follow the installation instructions.
2. Open VS Code: Launch VS Code once installed.

Configuring VS Code for Markdown

1. Install Markdown Extensions: VS Code's functionality can be extended with extensions. Some popular Markdown extensions include:
   • Markdown All in One: Provides keyboard shortcuts, table of contents, auto-preview, and more.
   • MarkdownLint: Helps catch syntax errors and improve writing by adhering to Markdown best practices.
2. Access Extensions: Press Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (Mac) to open the Extensions view. Search for the extensions mentioned above and install them.
3. Markdown Preview: VS Code has built-in support for Markdown preview. To open a preview of the Markdown file you are editing, click the preview in the top right area of VS Code, or press Ctrl+K V (Windows/Linux) or Cmd+K V (Mac).

Conclusion

You now have a foundational understanding of Markdown and how to configure VS Code for Markdown editing. These skills form the basis for writing clear, effective documentation. As you become more familiar with Markdown, you'll appreciate its simplicity and efficiency for documentation tasks.

In the next tutorial, we'll explore how to structure your documentation according to the Divio system, using the Markdown skills you've developed here.