Markdown Authoring Guide

The Envelope and the Letter

Every file you write is a piece of mail. The frontmatter — the YAML block bracketed by --- lines at the very top — is the envelope: it carries routing metadata that the platform reads to build listings, sitemaps, and search results. The body — everything after the closing --- — is the letter: what your reader actually opens and reads.

Just as the sender’s address belongs on the envelope, not inside the letter, metadata belongs in frontmatter and prose belongs in the body.

---
title: 'Why Strategy Without Execution Is Just a Dream'
publishedAt: 2026-03-01
authors:
  - jane-smith
tags: ['Strategy', 'Execution']
draft: false
---

Most strategies fail not because the thinking is wrong,
but because the handoff from planning to doing is broken.

Everything in the --- block is invisible to readers but critical to the platform. Everything below it is your article.

Headings: The Newspaper Hierarchy

A broadsheet has a clear visual order: a banner headline dominates the page, section labels (Sports, Business, Opinion) divide it, and subheads break each story into scannable chunks. Markdown headings work the same way.

Rule: Start your article body with ##. The <h1> is rendered from your title frontmatter field — writing a second one creates a duplicate and breaks accessibility.

## The Planning Trap

Most leadership teams confuse activity with progress.

### How to Spot It

Look for these signals in your next strategy review.

Paragraphs and Line Breaks

Markdown treats a blank line as a paragraph break — the same way a double-return in a word processor starts a new paragraph. A single line break inside a paragraph is ignored and the text flows together.

This is the first paragraph. It can span
multiple source lines and still renders as one block.

This is the second paragraph, separated by a blank line.

If you need a hard line break without starting a new paragraph, end the line with two spaces or a \. Use this rarely — it’s a sign the sentence structure needs rethinking.

Emphasis: The Highlighter vs. the Italics Pen

Two tools, two jobs:

• Bold (**word**) is a highlighter pen. Use it for genuinely critical terms, definitions on first use, or the key takeaway in a paragraph. If every third word is bold, none of them are.
• Italic (*word* or _word_) is a gentle vocal stress — the inflection you’d put on a word when speaking. Use it for titles of works, technical terms you’re introducing, or light emphasis.

The **core insight** is that strategy is a *bet*, not a plan.

Read *Good Strategy / Bad Strategy* before your next offsite.

Avoid using either for decoration. Emphasis loses meaning when overused.

Links: The Teleporting Footnote

A hyperlink is a footnote that teleports the reader. It has two parts: what you say ([anchor text]) and where it takes you ((url)). Keep the anchor text descriptive — it should make sense without reading the surrounding sentence.

[Read the full framework](/articles/okr-vs-balanced-scorecard)

Learn how [OKRs differ from balanced scorecards](/articles/okr-vs-balanced-scorecard).

Internal links use root-relative paths starting with /articles/, /cards/, /podcast/, etc. Never use a bare slug like /my-article — the platform routes content under its collection prefix.

External links use the full URL. The platform automatically opens them in a new tab.

[McKinsey's State of AI report](https://www.mckinsey.com/ai-report)

Lists: The Shopping List vs. the Recipe

Two kinds of lists, two very different jobs:

Unordered lists (- or *) are a shopping list — items where order doesn’t matter.

Key inputs to a strategy review:
- Market share data
- Customer NPS trends
- Competitor moves
- Financial runway

Ordered lists (1., 2., …) are a recipe — steps where sequence is critical.

To run a pre-mortem:
1. Imagine it is six months from now and the project has failed.
2. Each participant writes down the most likely cause of failure.
3. Share and cluster the causes by theme.
4. Assign owners to the top three themes.

Nest lists with two spaces of indentation. Keep nesting to two levels — deeper hierarchies usually signal that the content needs restructuring.

Images: The Caption Under a Photo

Images use a syntax similar to links, with a ! prefix. The text in [] is the alt text — what screen readers announce and what appears when the image fails to load. Write it as a description of what the image shows, not a caption or keyword string.

![Four quadrants showing urgency vs importance axes](priority-matrix.webp)

On LinkPress, article images are stored in public/articles/ and referenced by bare filename only — no path prefix:

![Two-by-two matrix of market attractiveness vs competitive position](ge-mckinsey-matrix.webp)

The platform resolves the path automatically at build time.

Code Blocks: The Locked Display Case

A code block is a locked display case — the content is shown exactly as written, preserving every space, newline, and special character. Use backtick fences (```) and specify the language for syntax highlighting.

```python
def calculate_margin(revenue, costs):
    return (revenue - costs) / revenue * 100
```

For inline code (variable names, file paths, short commands), use single backticks:

Set `draft: false` when the article is ready to publish.

Tables: The Spreadsheet Snapshot

Tables are best for comparative data — when readers need to scan across rows and columns to make a decision. Keep them narrow; a table with more than five columns is usually a paragraph waiting to be written.

| Framework | Best for | Pitfall |
|---|---|---|
| OKRs | Ambitious, directional goals | Gameable when tied to pay |
| Balanced Scorecard | Multi-perspective monitoring | Bureaucratic overhead |
| OGSM | Tight strategy-execution alignment | Requires executive discipline |

Quick Reference