docs(readme): restructure layout — H2 groups, merged sections, reordered flow

The previous README was 21 flat H3 sections with three competing
H2 navigation blocks at the top. Several pieces sat in unnatural places
and three pairs of sections were artificial splits of the same concept.

This rewrite simplifies the layout:

Hierarchy
- One H2 navigation block at the top: 'Choose your path' (was three).
- Four H2 content groups: Getting started, Using OpenCode, Extending
  OpenCode, Reference. Each holds a small number of H3 sections.
- 17 H3 sections total (down from 21). Clearer GitHub TOC.

Reordered for a top-to-bottom narrative
- 'When OpenCode isn't the right tool' moved up to right after
  'What is OpenCode?', so trade-offs are visible before sinking time
  into Setup.
- TUI & Themes moved from end-of-page into 'Using OpenCode' alongside
  Prompt Engineering, where 'how do I drive this?' belongs.
- 'Pick the right extension' (the mermaid decision tree) now opens
  'Extending OpenCode' inline, where it has context. Previously it sat
  at the top of the page before any extension had been introduced.

Merged artificial splits
- OpenCode Zen + Configuring providers → Models & Providers, with a
  3-way comparison up front (direct / Zen / local) and the Zen lineup
  as an H4 inside it.
- Subagents + Custom Agents → Agents, with built-in agents first,
  custom agents second. They're the same file format with different
  'mode:' values; the old split made the reader trace forward refs.
- TUI Mastery + Themes → TUI & Themes.

Trimmed redundancy
- Removed the table that duplicated the mermaid decision tree in
  'When to use what'. The mermaid was the unique visual; the table
  was repetition.
- Dropped the standalone 'What's inside' index — replaced by the H2
  group hierarchy itself.

Compatibility
- Added <a id> compatibility anchors for old internal links
  (#opencode-setup, #configuring-providers, #prompt-engineering-deep-dive,
  #tui-mastery, #subagents, #custom-agents, #model-context-protocol-mcp,
  #when-to-use-what, #whats-inside) so any external bookmarks still land
  on the page.
- Anchors for #opencode-zen and #themes are still produced by their
  H4 headings inside the merged sections, so existing deep links still
  resolve.

Net effect: 893 lines → 708 lines, same factual coverage, clearer flow.
This commit is contained in:
Wesam Abousaid
2026-05-18 20:16:57 +02:00
parent ccac453cdb
commit 8937f9da4b
+457 -669
View File
File diff suppressed because it is too large Load Diff