docs: fix outdates docs + internal apis #1958

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

caio-pizzol merged 45 commits into main from caio/sd-1572-fix-outdated-docs-mark-internal-apis

Feb 6, 2026

+3,044 −5,685

apps/docs/AGENTS.md

Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		CLAUDE.md

apps/docs/CLAUDE.md

-Original file line number
+Diff line change
@@ -0,0 +1,105 @@
+    # SuperDoc Documentation
+    Mintlify-powered docs at `docs.superdoc.dev`.
+    ## File structure
+    File paths must mirror the navigation structure in `docs.json`. If a page appears under "Guides > Collaboration" in the nav, the file lives in `guides/collaboration/`, not somewhere else.
+    When moving or renaming a page, always add a redirect in `docs.json`:
+    ```json
+    {
+      "source": "/old/path",
+      "destination": "/new/path"
+    }
+    ```
+    ## Brand voice
+    One personality, two registers. SuperDoc is the same person in every conversation — warm, clear, technically confident. It adjusts **what it emphasizes** based on who's listening. Developers hear about the how. Leaders hear about the why.
+    Documentation uses the **developer register**: clear, direct, code-forward. Respect the reader's time.
+    ### Headings
+    Sentence case, always. "What we built" not "What We Built."
+    ### Universal voice rules
+    - **Say what it does, not what it is** — "Renders DOCX files in the browser" not "an enterprise document management solution." Nouns are vague. Verbs are clear.
+    - **Short sentences win** — If a sentence has a comma, try splitting it in two. If it has a semicolon, definitely split it. Scannable beats comprehensive.
+    - **No buzzwords** — "Next-generation," "cutting-edge," "revolutionary," "best-in-class" are banned. If it sounds like a press release, rewrite it.
+    - **Show, then tell** — A code snippet or demo is always better than a paragraph of description. When words are needed, be specific: "5 lines" not "easy."
+    - **"You" not "we"** — "Your documents stay on your servers" hits harder than "We ensure data privacy." The reader is the hero, not SuperDoc.
+    - **Acknowledge trade-offs** — If something has a limitation, say so. "SuperDoc runs client-side, so very large documents (1000+ pages) need good hardware." Honesty builds trust.
+    - **Be specific with numbers** — "60+ extensions" not "many extensions." "5 lines of code" not "minimal integration." Specificity is credibility.
+    - **Conversational, not chummy** — Write like you're talking to a smart colleague. Not a pitch deck ("leverage synergies") and not a chat message ("lol it just works fr fr").
+    ### Developer register pattern
+    **Structure:** What it does → How to use it → What it saves you
+    Lead with the developer's problem or goal. Follow with what SuperDoc does (concretely). End with how fast they can start. Always include code or an install command near the top.
+    Example:
+    > "Add document signing to your app with the esign package. Drop in the component, define your fields, and get back a signed document with a full audit trail. No need to integrate DocuSign or build signing from scratch."
+    ### Same concept, two registers
+    | Concept | Developer register | Leader register |
+    |---|---|---|
+    | Self-hosted | "Runs entirely in the browser. No cloud calls. Your data stays on your servers." | "Documents never leave your infrastructure. Full data sovereignty with zero cloud dependency." |
+    | Easy to use | "Five lines of code. Pass a file, mount the editor, done." | "Your team can ship document editing in days, not quarters. No specialized hires needed." |
+    | DOCX fidelity | "Built on OOXML. Real pagination, section breaks, headers/footers. Not rich text with export bolted on." | "Users see documents exactly as they look in Word. No formatting loss, no complaints, no re-work." |
+    | Collaboration | "Yjs-based CRDT. Add real-time editing in ~10 lines. Conflicts resolve automatically." | "Teams edit documents together in real time. Built-in conflict resolution means no lost work." |
+    | Open source | "AGPLv3. Read the code, fork it, contribute. Commercial license if you need proprietary." | "Open-source foundation means no vendor lock-in. Inspect the code. Switch away anytime." |
+    | Extensible | "60+ extensions built-in. Write your own with the plugin API. Full ProseMirror access." | "Adapts to your workflow, not the other way around. Custom extensions, branding, and integrations." |
+    | AI | "Bring your own LLM. AI actions with tool use — find, replace, highlight, insert. Streaming built in." | "AI-assisted document workflows with your choice of provider. Your data, your model, your infrastructure." |
+    ### Quick reference
+    | Instead of | Write | Why |
+    |---|---|---|
+    | "Next-generation document editor" | "A document editor for the web" | Cut the hype. Say what it is. |
+    | "Seamless integration" | "Five lines of code" | Specific beats vague. |
+    | "Enterprise-grade security" | "Self-hosted. Your documents never leave your servers." | Describe the mechanism, not the claim. |
+    | "Leveraging AI capabilities" | "AI that finds, replaces, and rewrites text in your documents" | Say what it does. |
+    | "Robust collaboration features" | "Real-time editing with Yjs. Conflicts resolve automatically." | Name the tech. Devs trust specifics. |
+    | "We ensure data privacy" | "Your documents stay on your servers" | "You" framing. Mechanism, not promise. |
+    | "Comprehensive formatting support" | "60+ extensions: tables, images, lists, tracked changes, and more" | List beats adjective. |
+    | "Get in touch for pricing" | "Free under AGPLv3. Commercial license starts at $X/year." | Transparency builds trust. Devs hate hidden pricing. |
+    ## Page depth
+    - **Getting Started** pages are high-level overviews. Link to detailed pages, don't duplicate content.
+    - **Core** pages (SuperDoc, SuperEditor) are the detailed API reference.
+    - **Module** pages document configuration, API, and events for each module.
+    - **Guide** pages are step-by-step walkthroughs for specific integrations.
+    Don't add Tips, Warnings, or deep explanations in overview pages. Keep examples concise.
+    ## API naming
+    - `superdoc.export()` for SuperDoc-level methods
+    - `superdoc.activeEditor.commands.X()` for editor commands
+    - `superdoc.activeEditor.getHTML()` for editor-level methods
+    - `superdoc.getHTML()` returns `Array<string>` (one per document section)
+    Always verify API names against the source code before documenting. Key source files:
+    | API surface | Source |
+    |---|---|
+    | SuperDoc methods | `packages/superdoc/src/core/SuperDoc.js` |
+    | SuperDoc config | `packages/superdoc/src/core/types/index.js` |
+    | Editor methods | `packages/super-editor/src/core/Editor.ts` |
+    | Extensions | `packages/super-editor/src/extensions/` |
+    ## Mintlify components
+    Common components: `ParamField`, `Note`, `Warning`, `Tip`, `CardGroup`, `Card`, `Tabs`, `Tab`, `Info`.
+    ## Commands
+    - `npx mintlify dev` — Start local dev server
+    - `npx mintlify broken-links` — Check for broken links

apps/docs/ai/ai-actions/methods.mdx

-Original file line number
+Diff line change
@@ Expand Up / @@ -608,7 +608,7 @@ if (isValidTool(myTool)) { @@
     }
     ```
-    ## Advanced Exports
+    ## Advanced exports
     For advanced use cases, the package exports additional classes and utilities:
@@ Expand Down @@

apps/docs/ai/ai-actions/overview.mdx

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -51,7 +51,7 @@ await ai.action.replace(
  
    Formatting results depend on the source DOCX styles; list indentation may vary and may require follow-up instructions.

    ## What it is

    ## What it does

    AI Actions is SuperDoc's **high-level AI offering**. It provides pre-built operations for common document automation tasks:

    @@ -107,11 +107,11 @@ try {
  
    Enable verbose logging by setting `enableLogging: true`. The package will emit parsing and traversal issues to `console.error`.

    ## Advanced Exports

    ## Advanced exports

    The package exports additional utilities for advanced use cases:

    ### Provider Factory

    ### Provider factory

    ```ts

    import { createAIProvider } from '@superdoc-dev/ai';

    @@ -140,14 +140,14 @@ const ai = new AIActions(superdoc, { user, provider });
  
    const result = await ai.planner.execute('Review the document and add comments to all legal terms');

    ```

    ### Service Classes

    ### Service classes

    For custom implementations, you can use the lower-level service classes:

    - **`AIActionsService`** - Core service class that provides AI-powered document actions

    - **`EditorAdapter`** - Adapter for SuperDoc editor operations, encapsulating editor-specific API calls

    ### Tool Utilities

    ### Tool utilities

    Utilities for working with AI tools:

    @@ -166,9 +166,9 @@ const myTool = {
  
    const isValid = isValidTool(myTool);

    ```

    ### Type Exports

    ### Type exports

    The package exports comprehensive TypeScript types including:

    The package exports TypeScript types including:

    - `AIPlannerConfig`, `AIPlannerExecutionResult`, `AIPlan` - Planner types

    - `AIToolActions`, `SelectionRange`, `SelectionSnapshot` - Tool and selection types

    - `AIProviderInput`, `OpenAIProviderConfig`, `AnthropicProviderConfig`, `HttpProviderConfig` - Provider configuration types

apps/docs/ai/ai-builder/overview.mdx

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -23,4 +23,4 @@ See the [AI Actions Quick Start](/ai/ai-actions/overview#quick-start) to get sta
  
    ## Get notified

    Want to be notified when AI Builder launches? [Join our Discord](https://discord.com/invite/b9UuaZRyaB) or [watch on GitHub](https://github.com/Harbour-Enterprises/SuperDoc).

    Want to be notified when AI Builder launches? [Join Discord](https://discord.com/invite/b9UuaZRyaB) or [watch on GitHub](https://github.com/superdoc-dev/superdoc).

apps/docs/api-reference/authentication.mdx

-Original file line number
+Diff line change
@@ Expand Up / @@ -11,7 +11,7 @@ Authorization: Bearer sd_sk_abc123xyz789 @@
     [Get Your Key - Takes 2 minutes](/api-reference/quickstart)
-    ## Production Setup
+    ## Production setup
     <Warning>
     Client-side JavaScript? Stop. Keys belong in environment variables.
@@ Expand Down @@

apps/docs/api-reference/introduction.mdx

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -1,14 +1,14 @@
  
    ---

    title: Meet our API

    title: Meet the API

    sidebarTitle: Introduction

    keywords: "superdoc api, docx api reference, word editor api, document editor sdk, api documentation"

    ---

    Your documents are never persisted. Every API call is stateless—we process and forget. That's the point.

    Your documents are never persisted. Every API call is stateless — process and forget. That's the point.

    Convert contracts to PDF. Add signatures to agreements. Merge quarterly reports. Everything preserves—tracked changes, complex tables, nested lists, headers. Real document operations via REST API.

    ## Why Stateless Matters

    ## Why stateless matters

    Enterprise documents contain sensitive data. NDAs, financial reports, legal contracts. SuperDoc's API processes them in memory and returns results immediately. No storage. No persistence. No risk.

    @@ -25,7 +25,7 @@ Bearer token in every request (except `/v1/health`):
  
    Authorization: Bearer sd_sk_abc123xyz789

    ```

    ## What's Working Now

    ## What's working now

    **Convert** - DOCX to PDF with perfect fidelity. That 50-page contract with tracked changes? Converts flawlessly.

    @@ -51,23 +51,23 @@ POST /v1/sign
  
    POST /v1/verify

    ```

    ## What's Coming

    ## What's coming

    `/merge` - Combine documents with formatting intact. <br />

    ## Built for Real Documents

    ## Built for real documents

    This isn't a wrapper around LibreOffice. We built custom document processing that handles:

    This isn't a wrapper around LibreOffice. SuperDoc uses custom document processing that handles:

    - Tables spanning multiple pages

    - Tracked changes from multiple reviewers  

    - Embedded images and charts

    - Complex numbered lists and cross-references

    - Headers/footers with dynamic fields

    Your Word documents work because we built for Word documents. Not markdown. Not HTML - Actual DOCX files.

    Your Word documents work because SuperDoc was built for Word documents. Not markdown. Not HTML — actual DOCX files.

    ## Resources

    **[Status Page](https://status.superdoc.dev)** - Uptime and incidents  

    **[GitHub](https://github.com/Harbour-Enterprises/SuperDoc)** - Examples and issues

    **[GitHub](https://github.com/superdoc-dev/superdoc)** - Examples and issues

apps/docs/api-reference/quickstart.mdx

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -17,7 +17,7 @@ Three minutes to your first response.
  
        ```bash

        curl "https://api.superdoc.dev/v1/auth/verify?email=you@email.com&code=123456"

        ```

        Save this key. We can't recover it.

        Save this key. It can't be recovered.

      </Step>

      <Step title="Convert">

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: fix outdates docs + internal apis #1958

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Original file line number	Diff line number	Diff line change
Expand Up		@@ -23,4 +23,4 @@ See the [AI Actions Quick Start](/ai/ai-actions/overview#quick-start) to get sta

		## Get notified

		Want to be notified when AI Builder launches? [Join our Discord](https://discord.com/invite/b9UuaZRyaB) or [watch on GitHub](https://github.com/Harbour-Enterprises/SuperDoc).
		Want to be notified when AI Builder launches? [Join Discord](https://discord.com/invite/b9UuaZRyaB) or [watch on GitHub](https://github.com/superdoc-dev/superdoc).