Markdown basics
Markdown Basics
By KenRich ยท Last updated: July 21, 2026
Markdown is easiest to learn when you start with the few patterns you will use every day: headings, paragraphs, lists, links, images, tables, code blocks, and the occasional math block. This guide keeps the examples small so you can copy them into the editor and see the result immediately.
Start with the document shape
A readable Markdown file usually starts with one title, a few section headings, and short paragraphs below each heading. You do not need to decide final styling before the document has a useful shape.
Use one top-level heading for the page title. Use second-level headings for the main sections. If you need a third level, make sure the document is long enough to justify it.
# Project Plan
## Goal
Write the goal in one short paragraph.
## Tasks
- Draft the outline
- Review the preview
- Export the file
## Notes
Keep decisions and open questions here.Project Plan
Goal
Write the goal in one short paragraph.
Tasks
- Draft the outline
- Review the preview
- Export the file
Notes
Keep decisions and open questions here.
NoteHeadings give the document a map before you add detail.
Use blank lines for paragraphs
Markdown treats blank lines as real structure. If two thoughts belong in separate paragraphs, leave an empty line between them. This makes the source easier to read and gives the preview a clean rhythm.
Line breaks inside the same paragraph are usually less important than blank lines. For most writing, keep paragraphs short and let the preview wrap lines naturally.
This is the first paragraph. It can be one sentence or a few short sentences.
This is the second paragraph. The blank line between them matters.
> A quote also reads better when it is separated from nearby text.This is the first paragraph. It can be one sentence or a few short sentences.
This is the second paragraph. The blank line between them matters.
A quote also reads better when it is separated from nearby text.
NoteReadable source is easier to edit later.
Choose the right list
Use bullet lists when order does not matter. Use numbered lists when the reader should follow steps in sequence. Avoid deep nesting unless the structure really helps.
A list works best when every item has the same shape. If one item turns into a long paragraph, it may deserve its own section instead.
Things to check:
- Title is clear
- Links work
- Preview looks right
Steps to publish:
1. Finish the draft
2. Export HTML
3. Review the final pageThings to check:
- Title is clear
- Links work
- Preview looks right
Steps to publish:
- Finish the draft
- Export HTML
- Review the final page
NoteLists are for scanning. Keep them tight.
Add links and images plainly
A Markdown link has readable text in brackets and the URL in parentheses. The link text should explain where the reader is going instead of saying only "click here".
Images use almost the same shape, but start with an exclamation mark. The text in brackets becomes alt text, so write a short description that would still help if the image does not load.
Read the [VeloWrite Markdown guide](/guide) for a longer walkthrough.
Read the VeloWrite Markdown guide for a longer walkthrough.
NoteGood link text and useful alt text help both readers and search engines.
Use simple tables and code blocks
Tables are useful for short comparisons, status lists, and small sets of facts. Keep table cells short. If the table becomes hard to edit, convert it into headings and paragraphs.
Code fences preserve spacing and can include a language label for highlighting. For a basics page, it is enough to know the three-backtick shape and where the language name goes.
| Feature | Status |
| --- | --- |
| Preview | Ready |
| Export | Ready |
```bash
npm run build
```| Feature | Status |
|---|---|
| Preview | Ready |
| Export | Ready |
npm run build
NoteMath, diagrams, and tabbed code examples belong in the advanced guides.
Keep documents easy to scan
Short sections are easier to scan than long paragraphs. Consistent heading levels are easier to follow than visual decoration. If a document needs to be maintained, readable source matters as much as rendered output.
A practical habit is to write a section, check the preview, then continue. This catches broken tables, missing blank lines, awkward links, and code fences that were not closed.
When a document becomes something you want to keep, move it from a temporary browser draft to a local file. That is where the desktop app is better than a tab.