Markdown fundamentals
What Is Markdown?
By KenRich ยท Last updated: July 30, 2026
Markdown is a plain text writing format for notes, documentation, articles, READMEs, and drafts that need to stay easy to read before and after rendering.
Markdown is readable source plus structured output
A Markdown document is still plain text. You write a small amount of structure into the file: a heading starts with #, a list starts with - or a number, links use brackets and parentheses, and code blocks use fences.
That source can be read directly, but it can also be rendered into HTML, documentation pages, blog posts, PDF-style output, or a clean preview inside an editor. The format works because the source and the output both remain useful.
# Product Notes
## Goals
- Write quickly
- Preview clearly
- Keep files portable
Read the [VeloWrite guide](/guide) when the draft needs more structure.Product Notes
Goals
- Write quickly
- Preview clearly
- Keep files portable
Read the VeloWrite guide when the draft needs more structure.
NoteThe source is readable before it is rendered, and the preview still has clear structure.
Why plain text still matters
Plain text files are easy to back up, compare, search, version, and move between tools. They do not depend on one account, one database, or one vendor-specific document format.
Developers like Markdown because it fits Git and code review. Writers like it because the formatting does not interrupt the draft. Teams like it because the same file can move from a note to a README, a help article, or a release note without being rewritten from scratch.
Markdown is not the same job as a rich text editor
A rich text editor asks you to style while you write: font size, spacing, colors, page breaks, pasted formatting, and layout controls. Markdown asks you to describe structure first: this is a heading, this is a list, this is a link, this is code.
That makes Markdown a better drafting format for documents that change often. It is usually not the best final layout tool for page-perfect brochures or heavily designed reports. A practical workflow is to draft in Markdown, preview while writing, then export or publish when the content is stable.
## Decision
Use Markdown for the draft because the content will change during review.
## Final output
Export the finished version only after the structure and wording are stable.Decision
Use Markdown for the draft because the content will change during review.
Final output
Export the finished version only after the structure and wording are stable.
NoteMarkdown keeps the decision and the final output as separate concerns.
The core syntax is small on purpose
Most daily Markdown work uses a small set of patterns: headings, paragraphs, lists, links, blockquotes, fenced code blocks, images, and tables. You do not need to memorize everything before writing useful documents.
Learn the structures you use every day first. Add math, code tabs, reference links, and templates only when the document needs them.
## Meeting notes
> Keep the note short enough to review later.
1. Confirm the decision
2. Record the owner
3. Link the follow-up issue
```bash
npm run build
```Meeting notes
Keep the note short enough to review later.
- Confirm the decision
- Record the owner
- Link the follow-up issue
npm run build
NoteA few reliable patterns cover most working documents.
Where Markdown fits best
Markdown fits notes, READMEs, specs, changelogs, study guides, knowledge-base articles, product docs, launch copy, and blog drafts. It is strongest when the document needs to stay editable and searchable.
It also helps when a document may have several destinations. The same source can start as a private note, become a review draft, and later turn into a public article or support document.
| Source document | Possible output |
| --- | --- |
| README draft | GitHub project page |
| Product note | Help center article |
| Launch checklist | Internal runbook |
| Blog outline | Published article || Source document | Possible output |
|---|---|
| README draft | GitHub project page |
| Product note | Help center article |
| Launch checklist | Internal runbook |
| Blog outline | Published article |
NoteMarkdown helps when the source needs to outlive one export format.
Know what Markdown does not try to solve
Markdown is not a full design system, database, spreadsheet, whiteboard, or collaborative workspace by itself. Some editors add those layers, but the format remains strongest when the plain text file is still understandable.
Tool choice depends on the job. For heavy collaboration, complex permissions, or database views, a larger workspace product may fit better. For private writing, readable files, preview, export, and local history, Markdown is a lighter base.
Start in the browser, then move important files local
The easiest way to learn Markdown is to write a real document instead of reading syntax charts for an hour. Start with a title, a few headings, and one short list. Then preview the document and adjust the structure.
VeloWrite's web editor handles that first draft. When the document becomes important, the desktop app is the better place for native open and save, offline writing, recent files, and local history snapshots.
# Draft title
## What changed
Write the short version first.
## Why it matters
Add the reason readers should care.
## Next step
- Review the preview
- Save the Markdown file
- Share or export when readyDraft title
What changed
Write the short version first.
Why it matters
Add the reason readers should care.
Next step
- Review the preview
- Save the Markdown file
- Share or export when ready
NoteA useful Markdown document starts with shape, not decoration.