What Good Looks Like

The best Markdown documents share three qualities that make them useful for both human readers and automated systems like LLMs, linters, and documentation generators.

Quick Cheat Sheet

A one-table summary of the most frequently used Markdown, Mermaid, and LaTeX syntax supported by Telescopo.

Recommended Authoring Flow

Follow this five-step process to produce well-structured documents consistently. Each step builds on the previous one and avoids premature detail.

1. Write section skeleton first (## headings only).
2. Add one-sentence purpose under each section.
3. Add examples (code, diagram, or math) only where they reduce ambiguity.
4. Add a mini table of contents for long documents.
5. Run a final pass for consistency in tone, naming, and spacing.

Markdown Structure and Rhythm

Use a predictable rhythm throughout your document. A strong pattern is: heading, followed by a one-sentence summary, followed by a bullet list or example. This pattern makes documents scannable for both humans and automated systems.

## Why This Exists
One sentence that states the purpose.

## How It Works
- Input
- Processing
- Output

## Example
```json
{ "input": "X", "output": "Y" }
```

{ "input": "X", "output": "Y" }

Headings and Anchors

Use headings as navigation nodes. Make them short and specific so that anchor links are meaningful when extracted by search engines, LLMs, or table-of-contents generators.

# API Design Notes

## Constraints
Keep latency under 200ms for all endpoints.

### Rate Limiting
- 100 requests per minute per API key
- Burst cap of 20 concurrent connections

## Data Model

- [Constraints](#constraints)
- [Rate Limiting](#rate-limiting)
- [Data Model](#data-model)

Lists and Tables

Use lists for decisions and actions

Lists work best for sequences, decisions, and action items where order or grouping matters.

### Decision
- Keep markdown parser default behavior
- Override only image, code, heading renderers
- Add DOM tests for regression safety

Use tables for comparisons

Tables are ideal for side-by-side comparisons where multiple attributes need to be evaluated together.

| Option | Best For | Cost |
| --- | --- | --- |
| Minimal | Fast docs | Low |
| Structured | Team docs | Medium |
| Rigorous | Long-lived specs | High |

Links and Images

Write descriptive link text so that links are self-explanatory when extracted from context. Avoid generic "click here" phrasing. Use images to clarify, not to decorate.

Good: [View Architecture Overview](#architecture-overview)
Weak: [Click here](#architecture-overview)

![Mountain landscape photo](https://picsum.photos/id/866/200 "Mountain view")

Good: View Architecture Overview

Weak: Click here

Code Blocks

Always specify the language identifier after the opening triple backticks. This enables syntax highlighting in Telescopo (which supports 70+ languages) and helps LLMs correctly interpret code context.

```swift
func purchasePro() async throws {
    let result = try await product.purchase()
    // Handle verified transaction...
}
```

```json
{
  "feature": "pro_unlock",
  "enabled": true
}
```

func purchasePro() async throws {
    let result = try await product.purchase()
    // Handle verified transaction...
}

{
  "feature": "pro_unlock",
  "enabled": true
}

Mermaid Diagram Principles

Telescopo renders Mermaid diagrams natively inside Markdown files with no browser or network dependency. Follow these principles to keep diagrams readable and maintainable.

• One question per diagram ("what flow?", "what states?", "what sequence?").
• Keep labels short and move explanation to surrounding text.
• Prefer several focused diagrams over one giant system map.

Flowchart Example

Use flowchart TD (top-down) or flowchart LR (left-right) to show decision trees, process flows, or data pipelines.

```mermaid
flowchart TD
  A[Open File] --> B{File Type}
  B -->|Markdown| C[Render Markdown]
  B -->|Mermaid| D[Render Diagram]
  B -->|LaTeX| E[Render Equations]
  C --> F[Display]
  D --> F
  E --> F
```

flowchart TD
  A[Open File] --> B{File Type}
  B -->|Markdown| C[Render Markdown]
  B -->|Mermaid| D[Render Diagram]
  B -->|LaTeX| E[Render Equations]
  C --> F[Display]
  D --> F
  E --> F

Sequence Diagram Example

Use sequence diagrams to show message passing between components, API call flows, or user interaction sequences.

```mermaid
sequenceDiagram
  participant U as User
  participant V as View
  participant R as Renderer
  U->>V: Open document
  V->>R: renderMarkdown(...)
  R-->>V: HTML output
  V-->>U: Display result
```

sequenceDiagram
  participant U as User
  participant V as View
  participant R as Renderer
  U->>V: Open document
  V->>R: renderMarkdown(...)
  R-->>V: HTML output
  V-->>U: Display result

State Diagram Example

Use state diagrams to model lifecycle transitions, such as application states, connection states, or document processing stages.

```mermaid
stateDiagram-v2
  [*] --> Idle
  Idle --> Rendering: open()
  Rendering --> Ready: success
  Rendering --> Error: failure
  Error --> Idle: retry
```

stateDiagram-v2
  [*] --> Idle
  Idle --> Rendering: open()
  Rendering --> Ready: success
  Rendering --> Error: failure
  Error --> Idle: retry

Gantt Chart Example

Use Gantt charts to show project timelines, sprint plans, or documentation rollout schedules.

```mermaid
gantt
  title Documentation Rollout
  dateFormat YYYY-MM-DD
  section Core
  Draft guide     :done, d1, 2026-02-01, 3d
  QA with fixtures:active, d2, after d1, 4d
  section Publish
  Website deploy  :d3, after d2, 2d
```

gantt
  title Documentation Rollout
  dateFormat YYYY-MM-DD
  section Core
  Draft guide     :done, d1, 2026-02-01, 3d
  QA with fixtures:active, d2, after d1, 4d
  section Publish
  Website deploy  :d3, after d2, 2d

LaTeX Basics: Inline vs Display

Telescopo renders LaTeX mathematics using MathJax. Use single dollar signs for inline math that flows within a sentence, and double dollar signs for display math that stands on its own line.

Inline: The score is $S = \frac{p}{n}$.

Display:
$$
S = \frac{p}{n}
$$

Readable Equation Layout

Use aligned blocks for multi-step transformations. The aligned environment lets you show derivation steps with consistent alignment.

$$
\begin{aligned}
L &= \frac{1}{n}\sum_{i=1}^{n}(y_i - \hat{y}_i)^2 \\
  &= \frac{1}{n}\left[(y_1-\hat{y}_1)^2 + \cdots + (y_n-\hat{y}_n)^2\right]
\end{aligned}
$$

Narrating Math

Always explain symbols in prose at least once before or immediately after an equation. This is critical for accessibility, searchability, and LLM comprehension of mathematical content.

Let $n$ be the number of samples and $p$ be the number of correct predictions.
Then accuracy is $A=\frac{p}{n}$.

Mixed-Format Document Patterns

The strongest technical documents combine prose, diagrams, and math in a predictable sequence. Two patterns work especially well.

Pattern: Explain → Diagram → Equation → Example

1. Explain the system in two sentences.
2. Show flow with a Mermaid diagram.
3. Show the formal relation with LaTeX.
4. Close with a realistic code or input/output example.

Pattern: Spec writing with key labels

Use italic key labels to call out the inputs, outputs, and constraints of a system component.

_input_: Lesson node from graph
_output_: Problem set aligned to constraints
_constraints_: grade band, topic, complexity

Mistakes to Avoid

Accessibility and UX

These guidelines improve readability for all users and make your documents more reliably parsed by screen readers, search engines, and LLMs.

• Use descriptive link text instead of "click here" or bare URLs.
• Add image alt text that describes meaning, not only appearance.
• Keep heading hierarchy logical (H2 → H3, avoid random jumps).
• Keep line length moderate and paragraphs short.

Starter Template (Copy/Paste)

Use this template as a starting point for any new Markdown document in Telescopo. It includes a title, table of contents, Mermaid diagram, LaTeX equation, code example, and edge-case section.

# Document Title

## Summary
One-paragraph overview of the purpose and audience.

## Table of Contents
- [Architecture](#architecture)
- [Core Formula](#core-formula)
- [Implementation](#implementation)
- [Edge Cases](#edge-cases)

## Architecture
```mermaid
flowchart LR
  A[Input] --> B[Process]
  B --> C[Output]
```

## Core Formula
$$
f(x) = ax^2 + bx + c
$$

## Implementation
```swift
func runPipeline() {
    // concise, realistic example
}
```

## Edge Cases
- Missing input
- Invalid schema
- Timeout behavior

## References
- Internal links
- External docs