Skip to content

Commit a4045b5

Browse files
caio-pizzolcaio-pizzol
committed
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.
1 parent d827001 commit a4045b5

10 files changed

Lines changed: 626 additions & 387 deletions

File tree

‎apps/create/src/templates.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -176,7 +176,7 @@ Key options for the editor:
176176
| \`modules.comments\` | \`object\` | Comments panel configuration |
177177
| \`modules.collaboration\` | \`object\` | Real-time collaboration (Yjs) |
178178
179-
Full config: https://docs.superdoc.dev/core/superdoc/configuration
179+
Full config: https://docs.superdoc.dev/editor/superdoc/configuration
180180
181181
## Theming
182182
@@ -256,7 +256,7 @@ superdoc save && superdoc close
256256
- Quickstart: https://docs.superdoc.dev/getting-started/quickstart
257257
- React guide: https://docs.superdoc.dev/getting-started/frameworks/react
258258
- Document Engine: https://docs.superdoc.dev/document-engine/overview
259-
- MCP server: https://docs.superdoc.dev/document-engine/ai-agents/mcp-server
259+
- MCP server: https://docs.superdoc.dev/ai/mcp/overview
260260
- Examples: https://github.com/superdoc-dev/superdoc/tree/main/examples
261261
`;
262262
}

‎apps/docs/docs.json‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@
7777
"pages": [
7878
"editor/superdoc/overview",
7979
"editor/superdoc/configuration",
80+
"editor/superdoc/import-export",
8081
"editor/superdoc/methods",
8182
"editor/superdoc/surfaces",
8283
"editor/superdoc/events"
@@ -144,7 +145,11 @@
144145
},
145146
{
146147
"group": "Theming",
147-
"pages": ["editor/theming/custom-themes", "editor/theming/css-variable-migration"]
148+
"pages": [
149+
"editor/theming/overview",
150+
"editor/theming/custom-themes",
151+
"editor/theming/css-variable-migration"
152+
]
148153
},
149154
{
150155
"group": "PDF",

‎apps/docs/editor/superdoc/import-export.mdx‎

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
---
2+
title: Import and export reference
3+
sidebarTitle: Import/Export
4+
keywords: "import, export, docx export, html import, markdown import, document formats"
5+
---
6+
7+
Full reference for loading and exporting documents in the browser editor. For a five-minute orientation, see [Getting Started > Import and export](/getting-started/import-export).
8+
9+
SuperDoc is a Word editor that accepts multiple content formats as input. All content is normalized into Word's document model internally.
10+
11+
## Supported formats
12+
13+
| Format | Import | Export | Round-Trip | Use Case |
14+
|---|---|---|---|---|
15+
| **DOCX** | Full | Full | Perfect | Word documents |
16+
| **JSON** | Full | Full | Perfect | Programmatic control |
17+
| **HTML** | Structure only | Structure only | Visual only | Web content, AI output |
18+
| **Markdown** | CommonMark | CommonMark | Visual only | Documentation, AI output |
19+
| **Text** | Plain text | Plain text | Perfect | Simple content |
20+
21+
<Note>
22+
HTML and Markdown imports preserve structure (headings, lists, links, tables) but strip CSS styles.
23+
</Note>
24+
25+
## Importing content
26+
27+
### At initialization
28+
29+
Pass content when creating the SuperDoc instance.
30+
31+
```javascript
32+
// DOCX file — full fidelity
33+
new SuperDoc({
34+
selector: '#editor',
35+
document: docxFile // File, Blob, URL string, or config object
36+
});
37+
38+
// HTML content — requires a base DOCX for styles
39+
new SuperDoc({
40+
selector: '#editor',
41+
document: blankDocx,
42+
html: '<h1>Title</h1><p>Content</p>'
43+
});
44+
45+
// Markdown content
46+
new SuperDoc({
47+
selector: '#editor',
48+
document: blankDocx,
49+
markdown: '# Title\n\nContent with **formatting**'
50+
});
51+
52+
// JSON (ProseMirror schema)
53+
new SuperDoc({
54+
selector: '#editor',
55+
document: blankDocx,
56+
jsonOverride: documentSchema
57+
});
58+
```
59+
60+
<ParamField path="document" type="string | File | Blob | Object">
61+
The document to load. Strings are treated as URLs. Files and Blobs are used directly.
62+
</ParamField>
63+
64+
<ParamField path="html" type="string">
65+
HTML content to initialize the editor with. Requires a `document` for styles.
66+
</ParamField>
67+
68+
<ParamField path="markdown" type="string">
69+
Markdown content to initialize the editor with. Requires a `document` for styles.
70+
</ParamField>
71+
72+
<ParamField path="jsonOverride" type="Object">
73+
ProseMirror JSON to override the document content with.
74+
</ParamField>
75+
76+
### After initialization
77+
78+
Insert content into an existing document using editor commands.
79+
80+
<Note>
81+
For new code, prefer [`editor.doc.insert`](/document-api/overview) — it accepts a positional target and returns a typed receipt. The chain command shown below stays supported for apps already wired to `activeEditor.commands.*`.
82+
</Note>
83+
84+
<CodeGroup>
85+
```javascript Usage
86+
superdoc.activeEditor.commands.insertContent(content, {
87+
contentType: 'html' // 'html' | 'markdown' | 'text' | 'schema'
88+
});
89+
```
90+
91+
```javascript Full Example
92+
import { SuperDoc } from 'superdoc';
93+
import 'superdoc/style.css';
94+
95+
const superdoc = new SuperDoc({
96+
selector: '#editor',
97+
document: yourFile,
98+
onReady: (superdoc) => {
99+
superdoc.activeEditor.commands.insertContent(content, {
100+
contentType: 'html' // 'html' | 'markdown' | 'text' | 'schema'
101+
});
102+
},
103+
});
104+
```
105+
</CodeGroup>
106+
107+
<ParamField path="value" type="string | Object" required>
108+
The content to insert. String for `html`, `markdown`, and `text`. ProseMirror JSON object for `schema`.
109+
</ParamField>
110+
111+
<ParamField path="options.contentType" type="string">
112+
Content type: `'html'`, `'markdown'`, `'text'`, or `'schema'`
113+
</ParamField>
114+
115+
## Exporting content
116+
117+
### DOCX export
118+
119+
<Note>
120+
`superdoc.export()` **triggers a browser download by default**. If you need the raw `Blob` (e.g. to upload to a server), pass `triggerDownload: false` — otherwise you'll get a duplicate download.
121+
</Note>
122+
123+
<CodeGroup>
124+
```javascript Usage
125+
// Download as .docx file
126+
await superdoc.export();
127+
128+
// Get blob without triggering download
129+
const blob = await superdoc.export({ triggerDownload: false });
130+
131+
// Export without comments
132+
await superdoc.export({ commentsType: 'clean' });
133+
134+
// Export as final document (applies tracked changes)
135+
await superdoc.export({ isFinalDoc: true });
136+
137+
// Custom filename
138+
await superdoc.export({ exportedName: 'Final Contract' });
139+
```
140+
141+
```javascript Full Example
142+
import { SuperDoc } from 'superdoc';
143+
import 'superdoc/style.css';
144+
145+
const superdoc = new SuperDoc({
146+
selector: '#editor',
147+
document: yourFile,
148+
onReady: async (superdoc) => {
149+
// Download as .docx file
150+
await superdoc.export();
151+
152+
// Get blob without triggering download
153+
const blob = await superdoc.export({ triggerDownload: false });
154+
155+
// Export without comments
156+
await superdoc.export({ commentsType: 'clean' });
157+
158+
// Export as final document (applies tracked changes)
159+
await superdoc.export({ isFinalDoc: true });
160+
161+
// Custom filename
162+
await superdoc.export({ exportedName: 'Final Contract' });
163+
},
164+
});
165+
```
166+
</CodeGroup>
167+
168+
<ParamField path="exportType" type="string[]" default="['docx']">
169+
Formats to export
170+
</ParamField>
171+
172+
<ParamField path="commentsType" type="string" default="'external'">
173+
`'external'` to include comments, `'clean'` to remove all comments
174+
</ParamField>
175+
176+
<ParamField path="exportedName" type="string">
177+
Custom filename without extension
178+
</ParamField>
179+
180+
<ParamField path="triggerDownload" type="boolean" default="true">
181+
Whether to automatically trigger a file download. Set to `false` to get a `Blob` back instead.
182+
</ParamField>
183+
184+
<ParamField path="isFinalDoc" type="boolean" default="false">
185+
Export as final version (applies tracked change mode)
186+
</ParamField>
187+
188+
<ParamField path="fieldsHighlightColor" type="string">
189+
Color for field highlights in the exported document
190+
</ParamField>
191+
192+
<ParamField path="additionalFiles" type="Blob[]" default="[]">
193+
Additional files to bundle. When multiple files are exported, they are zipped together.
194+
</ParamField>
195+
196+
<ParamField path="additionalFileNames" type="string[]" default="[]">
197+
Filenames for additional files
198+
</ParamField>
199+
200+
### HTML export
201+
202+
<CodeGroup>
203+
```javascript Usage
204+
// Returns array of HTML strings (one per document)
205+
const htmlArray = superdoc.getHTML();
206+
207+
// From the active editor (single string)
208+
const html = superdoc.activeEditor.getHTML();
209+
```
210+
211+
```javascript Full Example
212+
import { SuperDoc } from 'superdoc';
213+
import 'superdoc/style.css';
214+
215+
const superdoc = new SuperDoc({
216+
selector: '#editor',
217+
document: yourFile,
218+
onReady: (superdoc) => {
219+
// Returns array of HTML strings (one per document)
220+
const htmlArray = superdoc.getHTML();
221+
222+
// From the active editor (single string)
223+
const html = superdoc.activeEditor.getHTML();
224+
},
225+
});
226+
```
227+
</CodeGroup>
228+
229+
<Note>
230+
HTML export is structure-only. Custom CSS styling and Word-specific formatting are not included.
231+
</Note>
232+
233+
### JSON export
234+
235+
<CodeGroup>
236+
```javascript Usage
237+
// From the active editor
238+
const json = superdoc.activeEditor.getJSON();
239+
```
240+
241+
```javascript Full Example
242+
import { SuperDoc } from 'superdoc';
243+
import 'superdoc/style.css';
244+
245+
const superdoc = new SuperDoc({
246+
selector: '#editor',
247+
document: yourFile,
248+
onReady: (superdoc) => {
249+
const json = superdoc.activeEditor.getJSON();
250+
},
251+
});
252+
```
253+
</CodeGroup>
254+
255+
JSON export preserves the full document structure and can be re-imported with `jsonOverride`.
256+
257+
### Markdown export
258+
259+
<CodeGroup>
260+
```javascript Usage
261+
// From the active editor
262+
const markdown = await superdoc.activeEditor.getMarkdown();
263+
```
264+
265+
```javascript Full Example
266+
import { SuperDoc } from 'superdoc';
267+
import 'superdoc/style.css';
268+
269+
const superdoc = new SuperDoc({
270+
selector: '#editor',
271+
document: yourFile,
272+
onReady: async (superdoc) => {
273+
const markdown = await superdoc.activeEditor.getMarkdown();
274+
},
275+
});
276+
```
277+
</CodeGroup>
278+
279+
## HTML element mapping
280+
281+
| HTML Element | Imported As | Notes |
282+
|---|---|---|
283+
| `<h1>` to `<h6>` | Word heading styles | Requires styles in the base document |
284+
| `<p>`, `<div>` | Normal paragraph | |
285+
| `<strong>`, `<b>` | Bold | |
286+
| `<em>`, `<i>` | Italic | |
287+
| `<a href="...">` | Hyperlink | |
288+
| `<ul>`, `<ol>` | Word lists | Nesting supported |
289+
| `<table>` | Word table | Structure only |
290+
| `<img src="...">` | Image | URL preserved |
291+
| `<blockquote>` | Quote style | If style exists in document |
292+
| `style="text-align: ..."` | Alignment | Inline alignment is preserved |
293+
294+
CSS classes, IDs, colors, fonts, margins, and other styling are stripped on import.
295+
296+
## Markdown element mapping
297+
298+
**Supported:**
299+
- Headings (`#` through `######`)
300+
- Bold/italic (`**bold**`, `*italic*`)
301+
- Ordered and unordered lists
302+
- Links `[text](url)`
303+
- Images `![alt](url)`
304+
- Code blocks
305+
- Blockquotes `>`
306+
307+
**Not supported:**
308+
- Tables, footnotes, task lists, custom syntax extensions

0 commit comments

Comments
 (0)