> [Maxim](https://wikilayer.org/smee-again) / [Wikilayer authoring guide](https://wikilayer.org/smee-again/wikilayer-howto) / Anti-patterns

# Anti-patterns

**Contents:**

- [Links](#links)
  - [No "see X" or "details below" framing](#no-see-x-or-details-below-framing)
  - [No quotation marks around link text](#no-quotation-marks-around-link-text)
  - [Article links anchor on the verb, not the publisher](#article-links-anchor-on-the-verb-not-the-publisher)
  - [Same-page `block:N` jumps are rare](#same-page-block-n-jumps-are-rare)
- [Structure](#structure)
  - [No bold-prefix subtopics inside one block](#no-bold-prefix-subtopics-inside-one-block)
  - [No flat h2-only outlines on pages with subtopics](#no-flat-h2-only-outlines-on-pages-with-subtopics)
  - [No outline navigation duplicated in prose](#no-outline-navigation-duplicated-in-prose)
  - [No one-line paragraphs that should be a list](#no-one-line-paragraphs-that-should-be-a-list)
  - [No oversized bullets that should be h3 children](#no-oversized-bullets-that-should-be-h3-children)
- [Punctuation](#punctuation)
  - [Em-dash used sparingly](#em-dash-used-sparingly)

A checklist to run through before committing edits. The outline below is the list itself: every h3 is a checkable item. An item that doesn't pass is something to fix, not a style preference.

## Links

Run through these before saving any block that contains links.

### No "see X" or "details below" framing

**Bad**: "Details on the [payment page](page:N)" or "see [the documents page](page:N)".

**Good**: "by [the payment rules](page:N)", "required [documents](page:N) include…".

**What breaks**: the bad form references the wiki's UI ("page", "section") instead of the topic. Readers don't know about pages, only about subjects. Anchor on the noun and weave the link into the sentence.

### No quotation marks around link text

**Bad**: "under [\"Visa rules\"](page:N)".

**Good**: "under [the visa rules](page:N)".

**What breaks**: quoting the title makes the link feel like a citation of a name. The link should weave into the sentence as a natural noun phrase, not stand off as a quoted artefact.

### Article links anchor on the verb, not the publisher

**Bad**: "the fact-checker [Raskrinkavanje](url) refuted the claim".

**Good**: "the fact-checker Raskrinkavanje [refuted](url) the claim".

**What breaks**: when the URL points to a specific article, anchoring on the publisher name makes the link read as if it goes to a homepage. Anchoring on the verb makes it clear the link is to the piece itself.

### Same-page `block:N` jumps are rare

**Bad**: dropping a `block:N` inside the same page where the target lives.

**Good**: assume readers expect links to leave the page; restructure if a same-page jump feels needed.

**What breaks**: a same-page jump usually masks a deeper problem: "details below" framing, duplicated content, or a block that wants to be split. The reader clicks expecting elsewhere and lands two screens down on the same page; that's a small but real betrayal.

## Structure

Tree damage. Run through these whenever creating, splitting, or extending blocks.

### No bold-prefix subtopics inside one block

**Bad**: a block whose body opens "**Has agency.** … **Owns hygiene.** … **Defends the source.** …".

**Good**: each bolded subtopic promoted to its own h3 child block.

**What breaks**: bold-prefix is fake h3. It hides four (or five) nodes inside one. `get_outline` shows one node, cross-links can only point at the whole block, history records every change as one diff, and splitting later is harder. Tree damage masquerading as style.

### No flat h2-only outlines on pages with subtopics

**Bad**: a page with five h2 sections, zero h3 children, and each h2 body containing 3+ visually parallel ideas.

**Good**: each parallel idea promoted to its own h3 child block.

**What breaks**: the platform's default is h2/h3, deeper when the topic earns it. A flat outline almost always means subtopics are hiding inside blocks as bold-prefix paragraphs. See above.

### No outline navigation duplicated in prose

**Bad**: a body that lists its own sections ("Below: linking, structure, content") or a wiki intro that announces "here you'll find pages on X, Y, Z".

**Good**: trust the outline. Side nav, breadcrumbs, and the rendered headings already show the structure. Use body text to set context (what the topic is, why it matters), not to narrate the table of contents.

**What breaks**: the duplicated list goes stale the moment a section is renamed or moved. Worse, it trains readers to expect prose summaries of structure they could see at a glance.

### No one-line paragraphs that should be a list

**Bad**: a sequence of one-sentence paragraphs that share parallel structure.

```
The agent is the journalist.

The human is the editor-in-chief.

Both think; only one signs off.
```

**Good**: bullets, because the items are short and parallel.

```
- The agent is the journalist.
- The human is the editor-in-chief.
- Both think; only one signs off.
```

**What breaks**: parallel ideas in separate paragraphs read as sequential narrative steps. The reader has to reconstruct that they're a list. The bullet form carries "these belong together" visually for free.

### No oversized bullets that should be h3 children

**Bad**: a bulleted list where each item runs several sentences or paragraphs.

```
- First item. Long explanation. Multiple sentences with detail and caveats and examples.
- Second item. Same shape — a small essay inside a single bullet point.
- Third item. Same again.
```

**Good**: each item promoted to its own h3 child block.

**What breaks**: bullets are visual shorthand for *short* parallel items. Long items inside bullets lose addressability (no `block:N` to link at), readability (no clear visual separation), and history granularity (every edit shows up as "changed the list"). When a bullet wants to be a paragraph, it deserves a node.

## Punctuation

One mark, used too widely.

### Em-dash used sparingly

**Bad**: "The agent — not the human — writes content — sometimes structurally."

**Good**: "The agent, not the human, writes content. Sometimes structurally."

**What breaks**: the em-dash (`—`) is for intonational pauses, parenthetical inserts, and direct speech. For listings and explanations, use a colon, period, or comma. A page with five em-dashes per paragraph reads as if every clause is dramatic.