You’re Probably Underusing Markdown: 12 Tricks Worth Copying
Create diagrams, plot data, map dependencies and package copyable code, all inside a Markdown file.
A Markdown file can explain a system, show a release schedule, typeset a calculation and carry the evidence behind a conclusion. It can also become a document you navigate, export or present, with the right tool.
The file stays text. The surprise is how much structure a few well-chosen instructions can express.
Try these examples in a compatible Markdown viewer and editor. Every screenshot below comes from Markdific, but the notes distinguish portable Markdown, renderer extensions and app-specific features.
1. Draw an architecture, not just a row of boxes
A useful architecture diagram distinguishes users, processing and storage. This one shows how a document reaches an editor, a background worker and a search index.
```mermaid
flowchart TB
browser[Browser] --> gateway[API gateway]
desktop[Desktop app] --> gateway
gateway --> access{Access allowed?}
access -->|No| denied[Explain denial]
access -->|Yes| documents[Document service]
subgraph processing[Processing]
documents --> save[Save revision]
documents --> fetch[Read document]
worker[Background indexer]
end
save --> source[(Source files)]
save --> queue[(Indexing queue)]
queue --> worker
worker --> index[(Search index)]
fetch --> source
search[Search request] --> index
fetch --> preview[Rendered preview]
classDef client fill:#dbeafe,stroke:#2563eb,color:#172554,stroke-width:2px;
classDef service fill:#ccfbf1,stroke:#0d9488,color:#134e4a,stroke-width:2px;
classDef store fill:#ede9fe,stroke:#7c3aed,color:#3b0764,stroke-width:2px;
classDef decision fill:#fef3c7,stroke:#d97706,color:#78350f,stroke-width:2px;
classDef failure fill:#ffe4e6,stroke:#e11d48,color:#881337,stroke-width:2px;
class browser,desktop,search client;
class gateway,documents,save,fetch,worker,preview service;
class source,queue,index store;
class access decision;
class denied failure;
style processing fill:#f0fdfa,stroke:#5eead4,color:#134e4a
```The colours distinguish clients, processing, decisions and rejection; the cylinder shapes identify stored information even if the colours are lost. The queue separates saving a document from indexing it, and the decision makes rejection visible instead of drawing only the happy path.
Try changing: add a second consumer of the queue. You have changed the architecture without redrawing the rest of the picture.
Works where: Mermaid flowcharts are supported. This is a conceptual model, not a running service or a security guarantee.
2. Turn dependencies into a release schedule
A list of dates hides what can overlap and what must wait. A Gantt diagram can show both.
```mermaid
%%{init: {"gantt":{"fontSize":18,"sectionFontSize":16,"barHeight":28,"barGap":8,"leftPadding":180,"topPadding":50}}}%%
gantt
title Example documentation release
dateFormat YYYY-MM-DD
axisFormat %d %b
todayMarker off
tickInterval 3day
section Prepare
Outline :done, outline, 2026-11-02, 1d
section Create
Draft guide :draft, after outline, 3d
Build examples :examples, after outline, 2d
Capture images :images, after examples, 1d
section Review
Editorial review :copy, after draft, 2d
Technical review :tech, after images, 2d
Approval :crit, approval, after copy tech, 1d
section Release
Publish :milestone, launch, after approval, 0d
Inspect live page:inspect, after launch, 1d
```Drafting and example-building start together. Approval depends on both reviews. That relationship is more informative than simply colouring a few calendar cells.
Works where: Mermaid Gantt charts are supported. Dates are illustrative, and crit is an author-applied highlight, not proof that Mermaid calculated the project's critical path.
I’m building Markdific because I wanted a simpler way to read, edit and preview Markdown files, including files received from AI tools. These screenshots use its actual rendering and reading controls, so you can try the examples without switching between unrelated tools.
3. Explain the conversation behind a loading screen
An architecture shows what exists. A sequence diagram shows who talks to whom, and what happens when the first attempt fails.
```mermaid
sequenceDiagram
autonumber
actor Reader
participant App
participant Cache
participant API
participant Store
Reader->>App: Open guide
App->>Cache: Find saved preview
alt Preview is cached
Cache-->>App: Return preview
else No cached preview
Cache-->>App: Miss
App->>API: Request Markdown
API->>Store: Read source
alt Source exists
Store-->>API: Markdown
API-->>App: Source
App->>App: Render document
App->>Cache: Store preview
else Source unavailable
Store-->>API: Not found
API-->>App: Error
App->>App: Prepare recovery message
end
end
App-->>Reader: Preview or recovery action
```The nested alternatives reveal something “load document” does not: a cached response and a missing source are different paths. The automatic numbers make it easier to discuss a specific message in a review.
Works where: Mermaid sequence diagrams are supported. The diagram describes behaviour; it does not make the requests itself.
4. Typeset the calculation beside its assumptions
Math becomes more useful when readers can see both the expression and the numbers being substituted.
For this fictional workshop:
- Fixed cost: 600 units
- Ticket price: 25 units
- Variable cost per attendee: 10 units
$$
N_{\text{break-even}}
= \left\lceil\frac{F}{p-v}\right\rceil
= \left\lceil\frac{600}{25-10}\right\rceil
= 40
$$You get a properly typeset fraction, a subscript and ceiling brackets, not a calculation squeezed into a sentence. The ceiling means rounding up to a whole attendee; this example assumes price exceeds variable cost and ignores other costs or constraints.
Works where: a compatible math renderer is enabled. GitHub documents LaTeX-style expressions; apps use different engines and command sets. Markdown does not recalculate the written result when you edit a number.
5. Make a data model explain its relationships
Boxes labelled “authors” and “documents” leave unanswered questions. Can one author write many documents? Can one tag belong to several documents?
```mermaid
erDiagram
AUTHOR ||--o{ DOCUMENT : writes
DOCUMENT ||--o{ REVISION : contains
DOCUMENT ||--o{ DOCUMENT_TAG : classified_by
TAG ||--o{ DOCUMENT_TAG : labels
AUTHOR {
string author_id PK
string name
}
DOCUMENT {
string document_id PK
string author_id FK
string title
}
REVISION {
string revision_id PK
string document_id FK
int version
}
TAG {
string tag_id PK
string label
}
DOCUMENT_TAG {
string document_id PK, FK
string tag_id PK, FK
}
```The relationship ends encode the counts. DOCUMENT_TAG makes the many-to-many tagging relationship explicit; its two fields jointly identify a link in this illustrative model.
Works where: Mermaid entity-relationship diagrams are supported. This is a model, not a database migration, and the drawn keys do not enforce constraints in an actual database.
6. Show what happens inside a status
“In review” can hide technical checks, editorial checks and correction loops. A composite state opens that box without flattening the whole lifecycle.
```mermaid
stateDiagram-v2
direction LR
[*] --> Draft
Draft --> Review: submit
state Review {
[*] --> Technical
Technical --> Editorial: checks pass
Technical --> Corrections: changes needed
Corrections --> Technical: resubmit
Editorial --> Approved: accepted
Approved --> [*]
}
Review --> Scheduled: review complete
Scheduled --> Published: release
Published --> Withdrawn: serious issue
Withdrawn --> Review: corrected draft
Published --> Archived: retire
Archived --> [*]
```The outer lifecycle remains understandable while the review stage has its own internal progression. The withdrawal route also prevents “published” from looking like an irreversible ending.
Works where: Mermaid state diagrams are supported. Unlike a flowchart’s tasks, these nodes represent conditions a document can occupy; the labels name events that change its state.
7. Turn screenshots into a small visual index
An image can be the clickable label of a link. Two small previews can therefore lead to two detailed diagrams without putting enormous pictures in the main document.
## System overview
[](Assets/architecture-large.png)
Open the architecture for component boundaries and storage.
[](Assets/recovery-large.png)
Open the recovery diagram for failure handling and retries.The inner destination supplies the visible image. The outer destination supplies the full-size version. Add meaningful alternative text so the links are understandable without relying only on their pictures.
Works where: image links are preserved. All four example assets are supplied in this edition. For your own document, replace them with your own files; the syntax does not generate thumbnails or manage their sizes. A Medium upload needs its own link and image checks.
8. Build a change note that shows the actual change
A release note can combine a readable summary, a visual diff and a verification checklist.
Build a change note that shows the actual change
## Retry behaviour changed
The client now waits longer and retries once more.
```diff
- timeout_ms: 3000
- attempts: 1
+ timeout_ms: 8000
+ attempts: 2
```
### Verify before release
- [ ] A normal request completes
- [ ] A timeout shows a recovery message
- [ ] Retrying does not create duplicate workThe plus and minus signs communicate the change even without colours. The checklist turns “updated retry behaviour” into something a reviewer can inspect.
Get Yugene’s stories in your inbox
Join Medium for free to get updates from this writer.
Works where: code blocks are supported; diff colours and task boxes depend on the renderer. This is a human-readable illustration, not a complete executable patch. See GitHub's code-block documentation.
9. Plot measurements against a target without opening a spreadsheet
A list of response times tells you the values. A chart can also show when they cross the threshold that matters. Mermaid can put bars and a target line in the same plot.
```mermaid
%%{init: {
"theme": "base",
"themeVariables": {"xyChart": {"plotColorPalette": "#2563eb,#ea580c"}}
}}%%
xychart-beta
title "Preview latency, fictional measurements"
x-axis [Mon, Tue, Wed, Thu, Fri]
y-axis "Milliseconds" 0 --> 500
bar [410, 330, 280, 250, 220]
line [300, 300, 300, 300, 300]
```
**Bars:** observed latency. **Line:** 300 ms target.The bars fall below the target on Wednesday. That is the conclusion the chart should make easy to see. Both series use milliseconds and the same five days, so the comparison has a consistent scale. The palette assigns blue to the first series and orange to the second. The numbers are fictional, not a benchmark of Markdific.
Try changing: replace the five measurements with your own, then adjust the axis range if needed. Keep the categories and each series the same length. Mermaid draws the values you supply; it does not measure performance or update the numbers for you.
Works where: the bundled Mermaid version supports XY charts. A viewer that supports flowcharts may still lack this newer chart type. The example is captured in Markdific; the explicit caption identifies the series without relying on colour alone.
Want to adapt one of these examples to your own document? Try Markdific, the Markdown app I’m building. Change a diagram, expand a troubleshooting section or edit the source beside its preview. I’d love to hear what works well and what you’d like improved.
Try changing: replace the five measurements with your own, then adjust the axis range if needed. Keep the categories and each series the same length. Mermaid draws the values you supply; it does not measure performance or update the numbers for you.
Works where: the bundled Mermaid version supports XY charts. A viewer that supports flowcharts may still lack this newer chart type. The example is captured in Markdific; the explicit caption identifies the series without relying on colour alone.
Want to adapt one of these examples to your own document? Try Markdific, the Markdown app I’m building. Change a diagram, expand a troubleshooting section or edit the source beside its preview. I’d love to hear what works well and what you’d like improved.
10. Make a troubleshooting guide reveal only the relevant answer
Combine an always-visible warning with an optional diagnostic procedure, instead of hiding everything behind “More.”
> [!WARNING]
> Keep a copy of the document before moving its image folder.
<details open>
<summary>The preview works locally, but shared images are missing</summary>
The document expects this relationship:
```text
handover/
guide.md
images/
workflow.png
```
Send the whole `handover` folder, not just `guide.md`.
</details>The warning remains visible. This demonstration uses the HTML open attribute so you can see the answer immediately; remove it to start collapsed. Readers can then expand the answer when its specific symptom matches theirs. The directory sketch explains the cause instead of asking them to “check the path” without context.
Works where: the host supports both alert syntax and HTML disclosure elements. GitHub documents collapsed sections; HTML filtering and Markdown inside HTML differ elsewhere.
11. Turn a table into a linked, copyable runbook
A command list is more useful when it tells the reader what to inspect after running each command. A table can combine literal commands, a sample result and a link to the official reference, without an embedded spreadsheet.
## Inspect a Git repository
| Inspect | Command | Sample result |
| :--- | :--- | :--- |
| [Working tree][status] | `git status --short` | `?? notes.md` |
| [Unstaged changes][diff] | `git diff --stat` | `2 files changed` |
| [Latest commit][log] | `git log -1 --oneline` | `a1b2c3d Fix links` |
[status]: https://git-scm.com/docs/git-status
[diff]: https://git-scm.com/docs/git-diff
[log]: https://git-scm.com/docs/git-logBackticks keep each command exact and copyable. Reference links make the row labels clickable while keeping long documentation URLs out of the table source. The result column is illustrative, not output produced by Markdown.
In the first row, ?? means an untracked file. The second command summarises unstaged changes to tracked files; it does not include staged changes or untracked files. Those boundaries matter more than making the cells look tidy. These three commands inspect an existing repository rather than committing, resetting or deleting your work.
Try changing: build the same pattern for your own troubleshooting commands. Pair each one with a specific interpretation, not just “check the output.” Keep commands short enough to read on a phone.
Works where: pipe tables, inline code and links render, including Markdific. Tables are an extension, not core CommonMark. The viewer displays these commands; it does not execute them. Git must be installed, and the commands need a Git repository.
12. Put a complete Markdown example inside another Markdown document
What if your example is itself a Markdown file, containing a heading, bold text and a Mermaid fence? Three backticks around the whole thing can close too early. A longer outer fence solves that.
## Inspect a Git repository
| Inspect | Command | Sample result |
| :--- | :--- | :--- |
| [Working tree][status] | `git status --short` | `?? notes.md` |
| [Unstaged changes][diff] | `git diff --stat` | `2 files changed` |
| [Latest commit][log] | `git log -1 --oneline` | `a1b2c3d Fix links` |
[status]: https://git-scm.com/docs/git-status
[diff]: https://git-scm.com/docs/git-diff
[log]: https://git-scm.com/docs/git-logThe four-backtick fence contains the inner three-backtick fence. Inside it, the heading, emphasis and diagram remain literal source, rather than rendering prematurely. The screenshot shows that source-preserving result.
This is useful for README templates, reproducible bug reports and tutorials: the reader gets one complete example to copy, not several fragments to reassemble. Copy the contents of the displayed block, without its four-backtick wrapper, into a new file to render the document.
The rule to remember: the closing fence must use the same character and be at least as long as its opening fence. If your example contains four consecutive backticks, choose five for its outer wrapper. A longer run closes the block too; simply adding any number of backticks at the end is not a nesting mechanism.
Works where: CommonMark fenced code blocks are supported, including Markdific. The example remains readable even without syntax highlighting. Rendering the copied inner Mermaid diagram still needs Mermaid support.
Keep the markdown source. Choose the right result.
A richer document is useful when it answers a question that ordinary paragraphs leave open: what depends on what, which state comes next, what changed, or what evidence supports the conclusion.
Start with the outcome, not the longest block of syntax. Keep the source understandable, use a meaningful label, and check the document where somebody else will read it. A colourful diagram does not excuse an unclear relationship.
Sources and further reading
- Mermaid diagrams in Markdown: fenced diagrams and rendering compatibility.
- LaTeX math in Markdown: inline expressions and display equations.
- Collapsible sections: details and summary for optional explanations.
- Mermaid’s flowcharts, sequence diagrams, Gantt charts, entity relationships and state diagrams.
- Mermaid XY charts, for the measurement and target plot.
- Git’s status, diff and log references, for the inspection commands.
- KaTeX supported functions, for mathematical notation.
- GitHub Flavored Markdown specification, for extensions such as tables and task lists.
- CommonMark specification, for the baseline rules.
- Markdown cheat sheet: everyday syntax to combine with these examples.
Note: Documentation may describe features newer than the renderer in your app. Test the destination before sharing. For Medium, upload the rendered images beside copyable source rather than expecting the Mermaid or math blocks to run inside the story.
Try one in your next document
Pick one example and open it in Markdific. Replace the sample content with your own, compare the source with the preview, and see whether the result explains something better than a paragraph alone.
I’m building Markdific to make working with Markdown simpler. If you try it, I’d really appreciate your feedback: what worked, what felt awkward, and what should I improve next?
