Commit 66f2c51
authored
docs: reframe nav around Editor umbrella + Document Engine (SD-2873) (#3047)
* docs: reframe nav around Editor umbrella + Document Engine (SD-2873)
Group SuperDoc, React, Custom UI, Built-in UI, and Collaboration
under a single Editor umbrella so the top-level nav reads as
Editor / Document Engine / everything else. Custom UI is the
recommended way to drive the editor in new React apps; Built-in
UI stays supported. URLs unchanged in this commit; folder/path
migration follows separately.
* docs: migrate URLs to new IA with redirects (SD-2873) (#3049)
* docs: migrate URLs under /editor/* with redirects (SD-2873)
Move pages so the URL structure matches the Editor umbrella:
core/superdoc to editor/superdoc, core/react to editor/react,
bring-your-own-ui to editor/custom-ui, modules to editor/built-in-ui,
modules/collaboration to editor/collaboration. Move SuperEditor and
extension authoring under advanced/. Add redirects (specific before
broad) so prior links keep working. Sweep cross-references across
mdx, llms.txt, and llms-full.txt.
* fix(docs): order legacy redirects before new wildcards (SD-2873)
Hoist /modules/collaboration/{backend,client,cloud,self-hosted}/*,
/core/superdoc/{properties,types}, and /core/supereditor/hooks
above the new /modules/collaboration/:path*, /core/superdoc/:path*,
and /core/supereditor/:path* wildcards so legacy deep links keep
hitting their intended pages instead of being rewritten into
nonexistent paths.
* docs: tighten Built-in UI nav and hide custom extensions (SD-2873)
- Flatten Built-in UI > Toolbar (drop the Built-in vs BYO vs Headless
comparison page; the comparison no longer fits since BYO and Headless
live elsewhere). Toolbar is now a single page.
- Rename Built-in UI > Track changes module to Track changes.
- Rename Built-in UI > Links to Link popover (the page is about
popoverResolver, not link insertion).
- Hide /advanced/custom-extensions from nav (file kept, hidden frontmatter)
while we plan the v2 editor surface.
- Add redirects so /modules/toolbar/{built-in,overview} and
/editor/built-in-ui/toolbar/{built-in,overview} all land on the
flattened toolbar page.
* docs: move PDF + Whiteboard out of Built-in UI into their own group (SD-2873)
PDF is a separate document type (pdf.js rendering pipeline) and
Whiteboard is an annotation layer that only applies to PDFs. Neither
is ready-made UI on top of the DOCX editor, so they don't fit the
Built-in UI category.
Group them under Editor > PDF (sibling of Built-in UI, Collaboration,
etc.) so they stay close to the SuperDoc browser surface (still
configured via modules.pdf / modules.whiteboard) without polluting
the Built-in UI category.
Add redirects so /modules/{pdf,whiteboard} and the previous
/editor/built-in-ui/{pdf,whiteboard} land on the new paths.
* docs: drop Advanced from nav and hide its pages (SD-2873)
The Advanced group was turning into a junk drawer of paths we're
walking away from in v2 of the editor. Hide all of them from nav
while keeping the files reachable by direct URL for existing
inbound links:
- SuperEditor (4 pages): the Document API on SuperDoc covers the
headless story now (editor.doc.* gives full programmatic access
without instantiating SuperEditor directly).
- Headless toolbar + examples: superdoc/ui will eventually offer
full toolbar control across frameworks (tracked in SD-2874);
hiding now so we don't teach the deprecated path.
Existing redirects keep old URLs working; the pages just don't
appear in the sidebar.
* docs: dissolve Guides into feature homes (SD-2873)
Top-level Guides was a junk drawer mixing product surfaces, migration
docs, and internal contributor material. Move every page to where the
feature actually lives so each section reads as one coherent topic.
Editor:
- Collaboration > Storage (was Guides > Storage)
- Custom UI > Navigation (was Guides > Stable navigation)
- Proofing > Overview, Custom provider (was Guides > Proofing)
- Theming > Custom themes, CSS variable migration (was Guides + Migration)
Document API:
- Migration (was Guides > Migration > Document API)
Resources:
- Upgrade guides > Breaking changes v1, Migrate from ProseMirror
Hidden:
- TypeScript migration (internal contributor doc, not consumer-facing)
Drop the entire Guides nav group. Add redirects so every old
/guides/* URL resolves to its new home. Sweep cross-references.
Also fix the accessibility page: the docs referenced
superdoc.isHighContrastMode (no such public property); replace
with the real setHighContrastMode(value) method.
* fix(docs): collapse redirect chains and fix broken targets (SD-2873)
- /resources/storage now points directly at /editor/collaboration/storage
(was pointing at the old /guides/general/storage which we just moved).
- /resources/guides points at /getting-started/introduction
(the old generic guides landing page no longer exists).
- /api-reference/documents/sign points at /solutions/esign/api-reference
(the previous target /api-reference/signature/sign was never built).
- /guide/integration jumps directly to /getting-started/quickstart
instead of chaining through /getting-started/installation.
- /getting-started/ai-ready jumps directly to /ai/agents/llm-tools
instead of chaining through /getting-started/ai-agents.
Audit: 73 redirects total, 0 chains, 0 broken destinations,
ordering is specific-before-broad.
* docs: rewrite Getting Started FAQ pages and add deep homes (SD-2873)
Getting Started has four entries that exist for FAQ/discoverability
(Import/Export, Font Support, Theming, AI). Two were broken JS-redirect
stubs and two were oversized API references. Reshape each as a tight
'first-week setup' page with a clear deep-dive link.
- Import and export: keep tight workflow page in Getting Started; move
the full reference to Editor > SuperDoc > Import/Export.
- Theming: keep 5-minute setup in Getting Started; move the full
overview to Editor > Theming > Overview.
- Font support: replace JS-redirect stub with a real practical guide
(the canonical fonts doc — no other home for it).
- AI: replace JS-redirect stub with a chooser page that points at
MCP, agent tools, CLI/SDK, and import/export based on use case.
Sweep stale links:
- Introduction cards: Installation -> Quick start, AI Agents -> AI.
- Quickstart: /document-engine/ai-agents/{mcp-server,llm-tools} ->
/ai/{mcp/overview, agents/llm-tools}.
- apps/create/src/templates.ts AGENTS.md generator: update old
/core/superdoc/configuration and /document-engine/ai-agents/* paths
so newly scaffolded projects ship correct docs links.
* docs: tighten Getting Started FAQ pages with correct API usage (SD-2873)
- Theming: createTheme returns a className applied via document.documentElement.classList.add, not a constructor option. Adds popover/CSP pitfalls.
- Fonts: modules.toolbar.fonts takes [{ label, key }] objects, not bare strings. Adds dropdown-not-auto-populated pitfall.
- AI: chooser table + three concrete paths with real install command.
- Import/Export: leads with value statement; adds duplicate-download/HTML-base-DOCX pitfalls.
* docs: rewrite Quick start as linear Install → Render → Load → Export → Next (SD-2873)
The previous quickstart (269 lines) opened with a Mermaid decision tree
and split into three parallel sections (AI agent, backend SDK, browser
editor). It worked as a map but front-loaded too much surface area
before the reader had written any code.
New shape is a single linear path for the most common audience (someone
embedding the DOCX editor in a web app):
1. Install (npm / React / CDN tabs)
2. Render the editor (JS / React tabs)
3. Load a document (URL / File input / Fetch tabs)
4. Export it (Download / Upload tabs)
5. What are you building? table — routes to Custom UI, Built-in UI,
Document Engine, AI, Collaboration based on the goal
AI agents get an Info callout near the top with the npx
@superdoc-dev/create one-liner — visible but out of the main flow.
SDK/CLI moves to the routing table; agents and backend code aren't
the primary quickstart audience.
Result: ~140 lines, single read path, decision lives at the bottom
once the reader has a working editor.
* docs: rewrite Getting Started AI page as a chooser + expectations page (SD-2873)
The previous version used a CardGroup with marketing copy. Replace
with structured prose that answers the questions someone searching
'SuperDoc AI' actually has:
- What is the data boundary (no LLM bundled, nothing auto-uploaded)
- Pick-your-path table (MCP / SDK / browser editor)
- What AI can control (concrete operation list)
- Three short path sections with real install commands and code
- Common patterns table (clause drafting, redlines, comments, etc.)
- 'What SuperDoc does not do' to set expectations
Quick start AI callout now points at /getting-started/ai (the path
picker) instead of jumping straight to /ai/mcp/overview.
* docs: rewrite Document Engine overview as a calm pillar landing (SD-2873)
The previous page listed MCP as a peer surface alongside Document API,
SDKs, and CLI, which blurred the line between Document Engine and AI
in the new IA. Reframe as 'the programmatic layer for .docx files' and
move MCP routing out to the AI section.
- Open with a clear definition and the three places Document Engine
shows up (editor, SDKs, CLI). Don't say 'without a visible editor' -
Document API in the browser usually exists alongside an open editor.
- AI callout near the top routes to /getting-started/ai (the chooser),
not /ai/overview directly, so AI users get the path picker.
- Surfaces table is now three rows (no MCP). 'Best for' framing is
about programmatic role, not just runtime.
- Add 'How it works' section explaining that Document API is the
operation contract and the surfaces are different ways to call it.
- 'Which surface should I use?' table includes Custom UI, serverless,
and AI as routes - reflects how customers actually arrive here.
- Drop the Mermaid diagram (added ceremony, not clarity).
* fix(docs): replace Font Awesome icons with valid Lucide names (SD-2873)
docs.json sets icons.library to lucide, but several pages used Font
Awesome / brand icon names that silently rendered as blank boxes.
Renames:
- arrow-up-right-from-square -> external-link
- screwdriver-wrench -> wrench
- compass-drafting -> compass
- gear (4 framework pages) -> cog
- crosshairs -> crosshair
- arrow-right-arrow-left -> arrow-left-right
- file-export -> file-output
- react/vuejs/js (no Lucide equivalents) -> code
- google/microsoft (no Lucide brand icons) -> book/file-text
Add an Icons section to apps/docs/AGENTS.md (and its CLAUDE.md
symlink) so future agents know:
- Mintlify only resolves icon names against the configured library
- Verify names against lucide.dev/icons before using
- Common Font Awesome -> Lucide name traps
- Brand icons need SVG paths since Lucide doesn't ship them
* feat(docs): add Lucide icon validator + tighten icon picks (SD-2873)
Add scripts/validate-icons.ts that walks every <Card icon=...>,
<Icon icon=...>, and docs.json icon reference and validates the
name against the locally installed Lucide icon set. Wire into
lefthook pre-commit so invalid icons fail the commit instead of
silently rendering as blank boxes in production.
The validator caught two more icons missed in the previous pass:
- cube -> box
- unlock -> lock-open
Tighten icon picks per code-review feedback:
- React-related cards: code -> atom
- Vue card: code -> blocks
- Vanilla JS card: code -> braces
- Comments card (Custom UI overview): message -> message-square
- Discord references in docs.json (contextual + navbar): discord
-> messages-square (Lucide ships no brand icons)
Add a follow-up note in apps/docs/AGENTS.md so future agents know
about pnpm run check:icons.
* docs: pull diffing out of SDKs and reframe as Document Engine workflow (SD-2873)
The page was nested under 'SDKs > SDK Diffing' but the underlying
operations (diff.capture, diff.compare, diff.apply) are canonical
Document API operations, not SDK-specific. Promote diffing to a
sibling of SDKs and CLI under Document Engine.
- Move document-engine/sdk-diffing.mdx to document-engine/diffing.mdx.
- Rename title from 'SDK Diffing' to 'Compare documents' (sidebar
stays 'Diffing'). Reframe the opener: diffing is a Document Engine
workflow; the examples use SDKs because file-to-file comparison
usually runs in backend automation, but the feature isn't SDK-owned.
- Update Document Engine nav: SDKs becomes a flat page (no sub-group),
Diffing becomes a sibling alongside SDKs and CLI.
- Add redirect /document-engine/sdk-diffing -> /document-engine/diffing.
- Sweep cross-references and update the SDK overview's link to
point at the new path with the new framing.
* fix(docs): final pass correctness fixes (SD-2873)
- Drop /getting-started/ai redirect: a real Getting Started AI page
now exists at that URL; the old redirect was sending it elsewhere.
- Fix editor.doc.insert snippet on the Getting Started AI page: the
real shape is { target, value, type: 'html' }, not { target, html }.
- Document Engine overview was wrong about the CLI: it runs in
persistent sessions (open/run/save/close), not one-shot commands.
- Add Diffing as a fourth Where-to-next card on Document Engine
overview. It's a sibling of Document API/SDKs/CLI, not nested.
- Drop CLI Skills from the AI overview path-picker. Skills are not
shipped yet (the page itself says so). Promoting them in the
primary path table is misleading; keep the page reachable but
don't route new users there.
* docs: brand voice + terminology sweep, hide legacy AI pages, rename Custom UI demo (SD-2873)
Final pass over the docs surface to align with brand.md voice and
the new IA terminology.
Terminology:
- 'Bring Your Own UI' / 'BYO UI' to 'Custom UI' across 12+ mdx files,
llms.txt, llms-full.txt, code comments in packages/super-editor and
packages/superdoc.
- Rename the Custom UI demo: demos/bring-your-own-ui to demos/custom-ui.
Update package.json name, playwright port mapping key, README, and
GitHub URL references in mdx.
Brand voice:
- Em-dash sweep across hand-written mdx (skip auto-generated files
under document-api/reference and the gen:docs marker block in
document-engine/sdks.mdx). 'X — Y' becomes 'X. Y' or 'X (Y)' or
'X: Y' depending on context.
- Wrap frontmatter description values that contain colons in double
quotes so YAML parses correctly (caught by mintlify validate).
- Touch up grammatical regressions where the colon substitution read
worse than the em-dash (theming.mdx, document-engine/overview.mdx,
getting-started/{ai,import-export}.mdx).
Legacy hides (kept reachable for inbound links, removed from search):
- document-engine/ai-agents/* (7 pages) and getting-started/ai-agents.mdx
add hidden: true frontmatter. Redirects already point /ai/* and
/getting-started/ai at the new homes; this stops the old pages from
surfacing in search results.
Notes:
- Auto-generated content (Document API reference, sdks.mdx marker
block) still has em-dashes. Filing a follow-up for the generator.
- demos/custom-ui/ folder renamed cleanly (no backward-compat shim
per direction). Old GitHub URLs that pointed at demos/bring-your-own-ui
will 404; trade-off accepted.
* fix(ci): finish bring-your-own-ui to custom-ui rename (SD-2873)
The demo rename missed the CI matrix, the Playwright port map, and
the README filter command. Smoke test failed because the cached
workspace had no demos/bring-your-own-ui, so Playwright's webServer
fell back to a pnpm command on a runner with no pnpm installed.1 parent 957c6aa commit 66f2c51
129 files changed
Lines changed: 1753 additions & 1391 deletions
File tree
- .github/workflows
- apps
- create/src
- docs
- advanced
- supereditor
- ai
- agents
- mcp
- api-reference
- document-api
- document-engine
- ai-agents
- editor
- built-in-ui
- collaboration
- custom-ui
- pdf
- proofing
- react
- superdoc
- theming
- extensions
- getting-started
- frameworks
- guides
- collaboration
- general
- migration
- modules
- toolbar
- resources
- scripts
- snippets/extensions
- solutions
- esign
- template-builder
- demos
- __tests__
- custom-ui
- public
- src
- components
- editor
- packages
- super-editor/src/ui
- superdoc/src/core
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
33 | 33 | | |
34 | 34 | | |
35 | 35 | | |
36 | | - | |
| 36 | + | |
37 | 37 | | |
38 | 38 | | |
39 | 39 | | |
| |||
56 | 56 | | |
57 | 57 | | |
58 | 58 | | |
59 | | - | |
| 59 | + | |
60 | 60 | | |
61 | 61 | | |
62 | 62 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
176 | 176 | | |
177 | 177 | | |
178 | 178 | | |
179 | | - | |
| 179 | + | |
180 | 180 | | |
181 | 181 | | |
182 | 182 | | |
| |||
256 | 256 | | |
257 | 257 | | |
258 | 258 | | |
259 | | - | |
| 259 | + | |
260 | 260 | | |
261 | 261 | | |
262 | 262 | | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
171 | 171 | | |
172 | 172 | | |
173 | 173 | | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
174 | 197 | | |
175 | 198 | | |
176 | 199 | | |
| |||
Lines changed: 6 additions & 2 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
| 2 | + | |
| 3 | + | |
2 | 4 | | |
3 | | - | |
4 | | - | |
5 | 5 | | |
6 | 6 | | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
7 | 11 | | |
8 | 12 | | |
9 | 13 | | |
| |||
Lines changed: 4 additions & 3 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
| 3 | + | |
3 | 4 | | |
4 | 5 | | |
5 | 6 | | |
6 | 7 | | |
7 | 8 | | |
8 | 9 | | |
9 | 10 | | |
10 | | - | |
| 11 | + | |
11 | 12 | | |
12 | 13 | | |
13 | 14 | | |
| |||
140 | 141 | | |
141 | 142 | | |
142 | 143 | | |
143 | | - | |
| 144 | + | |
144 | 145 | | |
145 | 146 | | |
146 | | - | |
| 147 | + | |
147 | 148 | | |
148 | 149 | | |
149 | 150 | | |
Lines changed: 3 additions & 2 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
| 3 | + | |
3 | 4 | | |
4 | 5 | | |
5 | 6 | | |
| |||
8 | 9 | | |
9 | 10 | | |
10 | 11 | | |
11 | | - | |
| 12 | + | |
12 | 13 | | |
13 | 14 | | |
14 | 15 | | |
| |||
428 | 429 | | |
429 | 430 | | |
430 | 431 | | |
431 | | - | |
| 432 | + | |
432 | 433 | | |
433 | 434 | | |
434 | 435 | | |
Lines changed: 1 addition & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
| 3 | + | |
3 | 4 | | |
4 | 5 | | |
5 | 6 | | |
| |||
Lines changed: 1 addition & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
| 3 | + | |
3 | 4 | | |
4 | 5 | | |
5 | 6 | | |
| |||
Lines changed: 3 additions & 2 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
| 3 | + | |
3 | 4 | | |
4 | 5 | | |
5 | 6 | | |
| |||
52 | 53 | | |
53 | 54 | | |
54 | 55 | | |
55 | | - | |
| 56 | + | |
56 | 57 | | |
57 | 58 | | |
58 | 59 | | |
| |||
191 | 192 | | |
192 | 193 | | |
193 | 194 | | |
194 | | - | |
| 195 | + | |
195 | 196 | | |
196 | 197 | | |
197 | 198 | | |
| |||
Lines changed: 8 additions & 7 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
| 3 | + | |
3 | 4 | | |
4 | 5 | | |
5 | 6 | | |
| |||
8 | 9 | | |
9 | 10 | | |
10 | 11 | | |
11 | | - | |
| 12 | + | |
12 | 13 | | |
13 | 14 | | |
14 | 15 | | |
15 | | - | |
| 16 | + | |
16 | 17 | | |
17 | 18 | | |
18 | 19 | | |
19 | 20 | | |
20 | | - | |
| 21 | + | |
21 | 22 | | |
22 | 23 | | |
23 | 24 | | |
24 | | - | |
| 25 | + | |
25 | 26 | | |
26 | 27 | | |
27 | 28 | | |
| |||
50 | 51 | | |
51 | 52 | | |
52 | 53 | | |
53 | | - | |
54 | | - | |
55 | | - | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
0 commit comments