Markdown Basics for Notes and Docs

Overview

Markdown is a lightweight plain-text syntax that converts to formatted HTML. It thrives in README files, issue trackers, note apps, and static sites because the source stays readable even without a preview pane.

You only need a small core for most writing: headings, emphasis, lists, links, images, and fenced code blocks. Flavors (GitHub, CommonMark, MDX) add tables, task lists, and components—start with portable basics, then learn flavor-specific extras when your platform needs them.

Draft in any text editor, then check rendering with Dockzio’s Markdown Preview so spacing, lists, and code fences look the way you intend before you commit or paste into a CMS.

Step-by-step

1. 1. Structure with headings

   Use `#` for an H1 (often once per doc), `##` for sections, `###` for subsections. Keep headings short and hierarchical—do not jump from `##` to `####` without a reason.

   Leave a blank line around headings for portability across parsers.

2. 2. Add emphasis and inline code

   `*italic*` or `_italic_`, `**bold**`, and `` `inline code` `` cover most prose needs. Avoid stacking emphasis for decoration; it reads as shouting in some renderers.

   Use inline code for filenames, commands, and UI labels that should not be translated or auto-capitalized.

3. 3. Build lists and links deliberately

   Unordered lists use `-` or `*`; ordered lists use `1.` (many renderers auto-number). Indent nested lists with consistent spaces.

   Links: `[label](https://example.com)`. Images: ``. Write alt text that describes the image for accessibility—not “image1.”

4. 4. Fence code blocks by language

   Triple backticks start and end a block; put a language tag on the opening fence (` ```ts `, ` ```bash `) when your renderer supports highlighting.

   Keep one idea per fence. Giant dumps are hard to review—link to files when the snippet is long.

5. 5. Preview, then adjust spacing

   Markdown is sensitive to blank lines between paragraphs and around lists. If a list “eats” the next paragraph, add spacing or tighten indent.

   Open the Markdown Preview with your draft, click through rendered links mentally, and fix heading levels before publishing.

Common mistakes

• Mixing tabs and spaces in nested lists. Inconsistent indentation breaks nesting. Use spaces consistently (two or four) per project convention.
• Forgetting a blank line before a fence. Some parsers attach a code block to the previous list item awkwardly. Separate blocks with blank lines when unsure.
• Using raw HTML without knowing the sanitizer. Many hosts strip HTML for safety. Prefer pure Markdown unless you know the platform allows specific tags.
• Writing headings in ALL CAPS instead of `#` syntax. Caps do not create structure for tables of contents or accessibility outlines. Use real heading markers.