# Dokly docs > Official documentation of Dokly. Create stunning documentation websites without the hefty price. 2 minutues setup required. ## Welcome to Dokly URL: https://docs.dokly.co Summary: Beautiful documentation for modern teams. A block editor, a hosted site, and your custom domain — in minutes. Dokly is a documentation platform for product teams who care about how their docs look, how fast they ship, and how easy they are to maintain. You write in a block editor — slash menu, drag handles, live styled previews of every component. Dokly handles the site, the search, the styling, the custom domain, and the boring infrastructure. You get a docs site that looks like Mintlify or GitBook, but without the per-seat pricing or the config-file rabbit hole. ## What's in here Create your first project, write a page, and publish to a live URL in under five minutes. Slash menu, AI actions, drag-and-drop blocks. Callouts, Tabs, Steps, Cards, API Playground — everything you need to make docs scannable. Import an OpenAPI spec and get an interactive playground for every endpoint. ## Built for the way teams actually work No CLI, no local preview, no syntax to memorize. Open the editor, hit `/` to insert a block, and type. Free projects get `yourname.dokly.co`. Pro plans get a custom domain like `docs.yourcompany.com` with HTTPS handled for you. Edit a page, hit Save, the live site reflects it within seconds. No CI, no preview deploys, no build queue. ## Where to go next If you've never used Dokly before, start with the [Quickstart](/get-started/quickstart). If you're migrating from Mintlify, GitBook, or Docusaurus, jump straight to the [Migration guide](/reference/migration). If you're stuck, the [FAQ](/reference/faq) covers the questions we hear most often. Every page in these docs is itself written in Dokly. If something here looks good, you can build the same thing in your own project with the slash menu — no special syntax involved. ## Get Started URL: https://docs.dokly.co/get-started Summary: Pages under Get Started. Everything in this section. What Dokly is, what it isn't, and who it's built for. Sign up, create a project, write your first page, and publish — all in five minutes. The architecture in one page: how content is stored, rendered, and served. ### Introduction URL: https://docs.dokly.co/get-started/introduction Summary: What Dokly is, what it isn't, and who it's built for. Dokly is a hosted documentation platform. You sign up, you create a project, you get a live docs site at a URL you control. You write pages in a visual block editor — no syntax to learn, no files to manage. ## What Dokly does - **Hosts your docs site.** Every project ships at `.dokly.co` the moment you create it. Pro plans add custom domains. - **Gives you a real editor.** A block editor with a slash menu, drag handles for reordering, and inline AI actions. Not a Markdown text box. - **Ships components that look good by default.** Callouts, tabs, steps, cards, API playgrounds — all styled, all dark-mode aware, all accessible. - **Handles search, SEO, and dark mode.** Fuzzy search out of the box. Sitemaps, OG images, and `llms.txt` generated automatically. - **Imports OpenAPI specs.** Drop in an `openapi.yaml` and get an interactive API reference for every endpoint. ## What Dokly is not - **Not a static site generator.** There's no `dokly build` step, no CI integration, no `_site/` folder. Editing is publishing. - **Not a CMS for marketing sites.** Use Webflow or Framer for that. Dokly is purpose-built for technical documentation: SDK references, API docs, product manuals, internal wikis. - **Not a wiki for non-technical teams.** Dokly is built for engineers and product teams. If your audience is sales ops, Notion is a better fit. ## Who it's for SDK docs, CLI references, integration guides. Ship a polished docs site without hiring a docs engineer. OpenAPI import, interactive playground, multi-language code samples. Your reference is always in sync with your spec. Architecture decisions, runbooks, onboarding docs. Search and structure that scale past 50 pages. No infrastructure tax. Free tier covers a small project; $19/mo unlocks search and bigger projects. ## How Dokly compares | Feature | Dokly | Mintlify | GitBook | Docusaurus | |---|---|---|---|---| | Hosted | Yes | Yes | Yes | No (DIY) | | Visual block editor | Yes | No (file-based) | Yes | No | | OpenAPI playground | Yes (Pro) | Yes | No | Plugin | | Custom domain | Pro ($49) | Pro ($150+) | Pro ($65+) | Free (DIY) | | Per-seat pricing | No | Yes | Yes | N/A | | AI write/improve | Yes (built-in) | Yes (add-on) | Limited | No | ## Next steps - [Quickstart](/get-started/quickstart) — five minutes to a live docs site. - [How Dokly works](/get-started/how-dokly-works) — the architecture, in one page. screenshot of a polished Dokly project (e.g., Acme API docs) showing sidebar + page content for the hero of this page ### Quickstart URL: https://docs.dokly.co/get-started/quickstart Summary: Sign up, create a project, write your first page, and publish — all in five minutes. This guide takes you from "I just signed up" to "my docs are live on the internet" in five minutes. No setup, no install, no terminal. Go to [dokly.co](https://dokly.co) and sign up with GitHub or email. You land on the dashboard with no projects yet. screenshot of empty dashboard with "Create your first project" CTA Click **New project**. Pick a name (e.g., "Acme API") and a subdomain (e.g., `acme`). Your project will live at `acme.dokly.co`. Subdomains are lowercase letters, numbers, and hyphens. They have to be globally unique across Dokly — pick something specific to your product. screenshot of "New project" modal with subdomain field filled in The new project opens with a placeholder "Welcome" page. Click into the editor and start typing. Try the slash menu: hit `/` to insert a heading, callout, code block, or any other component. Hit `/callout` to add a tip. Hit `/code` to add a syntax-highlighted code block. screenshot of the editor with the slash menu open, showing block options Save with `⌘S` (Mac) or `Ctrl+S` (Windows). Switch to the **Preview** tab in the toolbar to see how your page will look on the published site. Open `.dokly.co` in a new tab. Your page is live. No build step. No deploy queue. screenshot of the rendered docs site at acme.dokly.co showing the welcome page ## What's next You now have a real, public docs site. From here: Use the sidebar to add pages, drag them into groups, and nest them. Logo, colors, dark mode — all configurable in Settings. Move from `acme.dokly.co` to `docs.acme.com` (Pro plan). Drop in your OpenAPI YAML and get a full API reference auto-generated. You can have 1 project with up to 5 pages on the free plan. The 14-day Pro trial unlocks unlimited pages, custom domains, and AI features so you can evaluate the full product before paying. ### How Dokly works URL: https://docs.dokly.co/get-started/how-dokly-works Summary: The architecture in one page: how content is stored, rendered, and served. If you're going to depend on Dokly for your docs, you should know how it works. Here's the model in one page. ## The mental model Every Dokly project is three things: 1. **A subdomain** (e.g., `acme.dokly.co`) and optionally a custom domain (e.g., `docs.acme.com`). 2. **A tree of pages** — each page has a slug, a title, and a body of blocks. Pages can be nested. 3. **Branding settings** — logo, primary color, social card, dark/light defaults. The dashboard at `dokly.co/dashboard` is where you write and configure. The public site at your subdomain is where readers go. simple flow diagram — Editor (dashboard) → Save → Public site (subdomain) ## How content gets from editor to reader Insert blocks with the slash menu, drag them around, type your content. Hit `⌘S` (or wait for autosave). The page is written to your project, no build step required. Pages are cached at the edge for fast loads. Edits invalidate the cache automatically — changes are usually visible within a second or two. ## What that means for you - **No deploys.** Editing is publishing. There's no preview branch, no PR review, no CI queue. - **No local environment.** Everything happens in your browser. - **Fast pages, always.** Readers hit a cached page, not a database query. - **Search is client-side.** Search runs in the reader's browser — instant results, no extra API calls. ## A fixed component set Dokly ships a curated set of components (Callout, Tabs, Steps, Card, API Playground, etc.). They're styled, accessible, and dark-mode aware out of the box, and they look identical in the editor preview and on the live site. You can't add custom components from outside the platform. This is intentional: it keeps your docs consistent and prevents one-off widgets from making your site feel inconsistent. Enterprise plans can whitelist additions to the set — talk to us. The full list is in [Components → Overview](/components/overview). ## Custom domains and routing Every project lives at `.dokly.co` by default. On Pro plans and above, you can add a custom domain (`docs.acme.com`) — point a CNAME at the value Dokly gives you and TLS is provisioned automatically. You don't manage certs. ## Data and ownership - Your content lives on Dokly's managed infrastructure. - Free-tier projects sit on the same infrastructure as Pro projects — no degraded performance. - If you want to leave, contact us — we'll work with you on a clean export. ## Where to dig in next Learn the editor surface and the slash menu. The full list of components you can use. ## Editor URL: https://docs.dokly.co/editor Summary: Pages under Editor. Everything in this section. A tour of the Dokly editor — the writing surface, the toolbar, and the page tree. How to write pages in Dokly — the block model, the slash menu, and Markdown shortcuts. Every block you can insert with the slash menu, and the keyboard shortcuts that go with them. Inline AI for selected text — improve, expand, summarize, fix, translate. Generate full pages or whole docs sites from a brief. ### Editor overview URL: https://docs.dokly.co/editor/overview Summary: A tour of the Dokly editor — the writing surface, the toolbar, and the page tree. The Dokly editor is where you write and structure your docs. It's a block editor with a slash menu, drag handles, and inline AI actions. This page is a tour. The next pages cover individual features in depth. ## The editor surface annotated screenshot of the editor showing: 1) page tree sidebar (left), 2) main editor canvas, 3) Edit/Preview tabs in the toolbar (top center) - **Page tree (left)** — add, rename, reorder, and nest pages. Drag a page onto another to nest it. - **Editor canvas (center)** — where you write. Each block (paragraph, heading, callout, etc.) has a drag handle on hover. - **Edit / Preview tabs (top)** — switch between the editing surface and a rendered preview that matches the published site. ## Three ways to insert a block Slash menu Markdown shortcuts Paste Type `/` anywhere to open the block picker. Filter by typing — `/cal` jumps to Callout, `/code` jumps to Code Block. See [Slash menu](/editor/slash-menu) for the full list. Standard Markdown shortcuts transform into blocks: `# ` for H1, `## ` for H2, `> ` for blockquote, `- ` for a list, ``` ` ` ``` for inline code, ` ``` ` for a code block. Paste an image and it uploads. Paste Markdown and it parses into blocks. Paste a URL on selected text and it becomes a link. ## Saving and publishing - **Save** — `⌘S` / `Ctrl+S`. Writes to the database. The page is live on your published site within ~1 second. - **Autosave** — every few seconds while you type. You almost never have to think about Save. - **Draft vs published** — toggle in the page settings. Drafts don't show on the live site or in the sidebar. ## AI actions Select any text and click the sparkle button (or hit `⌘K`) to run AI actions: improve, expand, summarize, translate, fix grammar. See [AI actions](/editor/ai-actions). For longer-form generation (a whole page from a brief, or a whole site from a description), see [Generate with AI](/editor/generate-with-ai). ## What gets saved Each page in Dokly stores: - **Title** — shown in the sidebar and tab title. - **Slug** — the URL path (e.g., `editor/overview`). - **Description** — used for the meta description and the in-app page tree subtitle. - **Content** — the page body. - **Published state** — draft or live. - **Order and nesting** — controlled by drag-and-drop in the sidebar. You can edit slug, title, and description from the page settings panel. ## Where next The block model and the Markdown shortcuts that transform into blocks. Every block you can insert with `/`. Improve, expand, summarize selected text inline. Generate a whole page or site from a brief. ### Writing in Dokly URL: https://docs.dokly.co/editor/writing Summary: How to write pages in Dokly — the block model, the slash menu, and Markdown shortcuts. Dokly is a block editor. Every chunk of content — a paragraph, a heading, a callout, a code block — is a block you insert, configure, and rearrange visually. There's no syntax to memorize. ## The block model Every chunk of content in the editor is a **block**: - A paragraph is a block. - A heading is a block. - A callout is a block. - A code block is a block. Blocks have: - **A drag handle** that appears on hover (left of the block). - **A `+` button** to insert a new block above or below. - **Settings** specific to that block type (e.g., callout color, code language) — opened from the block's inline controls or the inspector panel. You can move blocks by dragging the handle, delete by selecting and pressing backspace at the start of the block, and duplicate with `⌘D`. short screen recording or annotated screenshot showing drag-and-drop block reordering ## Inserting blocks There are three ways to insert a block — pick whichever feels fastest in the moment. ### Slash menu Type `/` anywhere to open the block picker. Filter by typing — `/cal` jumps to Callout, `/code` jumps to Code Block, `/api` jumps to API Playground. The slash menu is the right default. See [Slash menu](/editor/slash-menu) for the full block list. ### Markdown shortcuts Type a Markdown shortcut and press space — the block transforms automatically. | Type | Becomes | |---|---| | `# ` | Heading 1 | | `## ` | Heading 2 | | `### ` | Heading 3 | | `> ` | Blockquote | | `- ` | Bullet list | | `1. ` | Ordered list | | `- [ ] ` | Task list | | ` ``` ` | Code block (then type the language) | | `---` | Horizontal divider | These work for fast typing. For everything else (callouts, tabs, cards, FAQs, badges, the API playground), use the slash menu. ### Paste Paste an image and it uploads. Paste Markdown and it parses into blocks. Paste a URL on selected text and it becomes a link. ## What blocks Dokly supports | Category | Blocks | |---|---| | Text | Paragraph, Heading 1/2/3, Bullet list, Ordered list, Task list, Quote, Divider | | Code & data | Code block, Table | | Highlights | Callout (info, warning, error, success, tip) | | Structure | Steps, Tabs, Card, Card Group, FAQ | | Inline | Badge | | Media | Image | | API docs | API Playground | For deep dives on each, see [Components → Overview](/components/overview). ## Next Every block you can insert with one keystroke. The full set of components, with examples. ### Slash menu URL: https://docs.dokly.co/editor/slash-menu Summary: Every block you can insert with the slash menu, and the keyboard shortcuts that go with them. The slash menu is the fastest way to insert any block. Type `/` anywhere in the editor and start typing the block name to filter. screenshot of the open slash menu showing the full block list with icons ## Filtering Type to filter. The match is fuzzy — `/cal` finds Callout, `/cd` finds Code Block, `/api` finds API Playground. Use arrow keys to move, `Enter` to insert, `Esc` to dismiss. ## The full block list ### Text and structure | Block | Slash filter | Markdown shortcut | |---|---|---| | Heading 1 | `/h1` | `# ` | | Heading 2 | `/h2` | `## ` | | Heading 3 | `/h3` | `### ` | | Bullet list | `/bullet` | `- ` | | Ordered list | `/numbered` | `1. ` | | Task list | `/task` | `- [ ] ` | | Quote | `/quote` | `> ` | | Divider | `/divider` | `---` | | Code block | `/code` | ` ``` ` | | Table | `/table` | — | ### Highlights | Block | Slash filter | |---|---| | Info Callout | `/info` | | Warning Callout | `/warning` | | Error Callout | `/error` | | Success Callout | `/success` | | Tip Callout | `/tip` | ### Structure | Block | Slash filter | Notes | |---|---|---| | Steps | `/steps` | Numbered procedure | | Tabs | `/tabs` | Multi-tab content | | Card | `/card` | Linked card with title and icon | | Card Group | `/cardgroup` | Grid of cards | | FAQ | `/faq` | Collapsible question and answer | ### Inline and media | Block | Slash filter | Notes | |---|---|---| | Badge | `/badge` | Inline label (Pro, Beta, etc.) | | Image | `/image` | Upload from your computer or paste | | API Playground | `/api` | Single interactive endpoint (Pro+) | For AI features (improve, expand, fix grammar, full-page generation), see [AI actions](/editor/ai-actions) and [Generate with AI](/editor/generate-with-ai). ## Why slash and not a toolbar Two reasons. First, your hands stay on the keyboard. Toolbars require a mouse trip and a target hunt. The slash menu is one keystroke and a couple of characters. Second, the menu is searchable. Toolbars hide options behind submenus. With slash, you don't have to remember where Callout lives — you just type `/cal`. ## Where next Every component the slash menu can insert, with examples. Every shortcut, organized by purpose. ### AI actions URL: https://docs.dokly.co/editor/ai-actions Summary: Inline AI for selected text — improve, expand, summarize, fix, translate. AI actions are inline edits run on a text selection. Highlight a sentence, click the AI button (or hit `⌘K`), pick an action. The selection is replaced with the result. These are *small* operations — a paragraph, a sentence, a heading. For generating an entire page, see [Generate with AI](/editor/generate-with-ai). screenshot of the AI inline menu open over a selected paragraph, showing the action list ## The actions Tightens prose. Removes filler, fixes awkward phrasing, keeps the meaning. Adds depth. Useful when a paragraph is too terse and needs supporting detail. Compresses a long passage to its essentials. Mechanical corrections only. Doesn't change voice or structure. Translates to a target language while preserving Markdown structure. Shifts to friendly, formal, technical, or casual. ## How to use Drag-select or use `⌘A` for the whole block. Either click the sparkle button that appears above the selection, or hit `⌘K`. Or type a free-form prompt — "make this less formal", "add a code example after this", "shorten by half". The result appears in place of the selection with **Accept**, **Reject**, and **Try again** buttons. ## Free-form prompts The fastest way to use AI actions is to skip the preset and just type what you want: - "Add three more bullet points about error handling" - "Convert this list to a Steps component" - "Make this sound less marketing-y" - "Add a callout warning about rate limits" The AI sees the selected text, the surrounding context, and your prompt. The result drops in as styled blocks in place of your selection. ## Credits and pricing Inline actions are cheap (small input, small output). On the **Free** plan you get a small monthly allowance. **Starter** and **Pro** include monthly credit buckets that cover normal writing — see [AI credits](/account/ai-credits). If you run out of credits mid-session, the action button shows a "Top up" prompt. Refunds are automatic if a generation fails. Bringing your own Anthropic API key (BYOK) is available on Enterprise plans. On Free / Starter / Pro, AI runs on Dokly's API allocation and counts against your monthly credit bucket. ## What the AI sees For privacy and accuracy: - The AI receives **only the selected text plus a small context window** (the few blocks before and after). - The AI does **not** see your other pages, your account info, or any reader analytics. - Prompts and outputs are not used to train any model. If you need stricter handling (zero retention, regional inference), reach out about Enterprise. ## Where next For full-page generation from a brief. How credits work, monthly buckets, top-ups. ### Generate with AI URL: https://docs.dokly.co/editor/generate-with-ai Summary: Generate full pages or whole docs sites from a brief. For full-page or full-site generation, Dokly has two larger AI flows: 1. **Generate page** — turn a brief into a single complete page, ready to edit. 2. **Generate site** — turn a product description into a full docs site outline with stub pages. These are heavier than [inline AI actions](/editor/ai-actions). They consume more credits and take 10–30 seconds. ## Generate page From the page tree, click **+ New page** or hit the slash menu's `/generate` block on a blank page. A few sentences describing what the page should cover. The more specific, the better. Good brief: > A guide for new users on setting up webhooks. Should cover: creating a webhook in the dashboard, signing the payload with HMAC-SHA256, verifying signatures in Node.js and Python, and what to do when delivery fails. Bad brief: > Webhooks page. The generator adjusts structure based on type: - **How-to** — Steps, prerequisites, verification. - **Reference** — Tables, parameter descriptions, examples. - **Concept** — Prose-heavy, diagrams (placeholders), comparisons. - **Tutorial** — Long-form, narrative, end-to-end. Friendly, neutral, technical, or formal. Defaults to your project's brand voice if you've configured one in Settings. The page appears in the editor. Treat it as a first draft — read it, fix what's wrong, add what's missing. The AI is good at structure and bad at the details only you know. screenshot of the "Generate page" modal showing brief field, doc type, tone selector ## Generate site For a brand-new project with no pages yet, **Generate site** scaffolds the whole information architecture. Available on any project with zero pages. Disappears once you've created at least one page. The generator uses this to decide page titles, structure, and section grouping. Templates seed the structure differently — API docs put OpenAPI reference at the top, product docs put a quickstart, internal wikis put architecture decisions. You see a preview of every page that will be generated. Reorder, rename, or delete pages before committing. Each page is generated in parallel. Total time: ~30 seconds for a 10–20 page site. Site generation gets you 70% of the way to a coherent docs site. The other 30% is product-specific knowledge the AI doesn't have. Plan to spend a few hours editing after generation — this is normal and expected. ## Costs | Operation | Approximate credits | |---|---| | Inline action (improve, expand) | 1–3 | | Generate single page | 20–50 | | Generate site (10 pages) | 200–500 | Free plan includes a small monthly allowance — enough for a few inline actions a day. Starter and Pro include enough credits for normal writing flows, including occasional page generations. See [AI credits](/account/ai-credits) for current bucket sizes. ## What works well, what doesn't **Works well:** - Stub pages with the right structure and headings - Boilerplate (prerequisites, "what you'll learn", "next steps") - Code examples in common languages - Migration guides between similar tools **Doesn't work well (yet):** - Anything specific to *your* product (the AI doesn't know your API) - Long technical reasoning (it'll be plausible-sounding but wrong) - Pricing or feature claims (always verify against your source of truth) The right mental model: AI-generated docs are a fast first draft. Your edits are what makes them accurate. ## Where next Inline edits on selected text. Bucket sizes, top-ups, BYOK. ## Components URL: https://docs.dokly.co/components Summary: Pages under Components. Everything in this section. Every component you can use in a Dokly page, with examples and links to the deep-dive pages. Highlight important context with tip, warning, note, danger, and success callouts. Multi-tab content blocks. Common for code-in-multiple-languages and platform-specific instructions. Numbered, titled steps for procedures and tutorials. Linked cards with icons. The right component for hubs, indexes, and 'where to go next' sections. Syntax-highlighted code with a language tag, line numbers, and a copy button. Interactive endpoint runner — readers fill in parameters, hit Send, and see the real response inline. Collapsible question and answer blocks. Useful for FAQ pages and 'common gotchas' sections. Small inline labels — Pro, Beta, Deprecated, New. Drag, paste, or upload — Dokly handles the rest. Optimization, lazy loading, and lightbox are automatic. ### Components overview URL: https://docs.dokly.co/components/overview Summary: Every component you can use in a Dokly page, with examples and links to the deep-dive pages. Components are styled, accessible blocks beyond what plain text gives you. Dokly ships ten of them, all available in the slash menu and all dark-mode aware out of the box. ## The full list Tip, warning, note, danger, success — for highlighting important context. Multi-tab content. Common for showing the same thing in different languages. Numbered procedure with titled steps. Linked cards with icons, often used as a homepage hub. Syntax-highlighted code with language tag and copy button. Interactive endpoint runner. The single-endpoint version of an OpenAPI page. Collapsible question + answer. Small inline label — Pro, Beta, Deprecated. Optimized images with captions and lightbox. ## Why a fixed component set Dokly ships a curated set of components. You can't add your own. This is intentional. **Pros:** - Your docs render identically in the editor preview and on the live site. - No build can break because of a custom component bug. - Components are themed consistently — your docs look coherent without effort. **Cons:** - If you need a one-off custom widget, you can't ship it. For most teams the trade-off is right. If you genuinely need custom components, Enterprise can whitelist additions to the component set — talk to us. ## Inserting a component Use the slash menu — type `/` and start typing the component name. `/cal` filters to Callouts, `/api` filters to API Playground, and so on. The full list is in [Slash menu](/editor/slash-menu). A few components also have Markdown shortcuts that transform into the block (e.g., ` ``` ` for a code block). See [Writing in Dokly](/editor/writing) for the full shortcut list. ## Component settings Each component has a small set of settings (color, type, title, etc.). After inserting, click the block to open its inline controls or the inspector panel — both expose the same options. Each component's deep-dive page documents every setting with examples — see the cards above. ## Where next The most-used component — start here. The most powerful one — for interactive API docs. ### Callouts URL: https://docs.dokly.co/components/callouts Summary: Highlight important context with tip, warning, note, danger, and success callouts. Callouts are the most-used component in Dokly. They draw the reader's eye to information that would otherwise blend into the prose — a warning, a tip, a side note. ## Examples Use callouts sparingly. If every other paragraph is a callout, none of them are. This action is destructive and cannot be undone. Custom domains require a Pro plan or higher. Don't run this command in production without a backup. Your project is now live at `acme.dokly.co`. ## Settings | Setting | Values | Default | Description | |---|---|---|---| | Type | Info, Tip, Warning, Error, Success | Info | Visual style and icon | | Title | text | none | Bold title above the body | | Body | content | required | Anything — paragraphs, lists, code | ## Insert Use the slash menu and pick the variant you want: `/info`, `/tip`, `/warning`, `/error`, or `/success`. The block inserts with a placeholder title and body — click in to edit, or change the type from the inline controls afterwards. ## When to use which type | Type | When | |---|---| | Tip | Optional advice that improves the result | | Info | Context the reader needs but isn't critical | | Warning | Something might go wrong | | Error | Something *will* go wrong if you don't pay attention | | Success | Confirmation of a successful state | ## Nesting Callouts can contain anything — including code blocks and lists. Run this to verify: ``` curl https://api.example.com/health ``` Don't nest callouts inside callouts. It looks bad and confuses the reader. ## Accessibility Each callout has an icon, but the icon is decorative — the type is conveyed by the title and surrounding context, not the icon alone. Screen readers announce the title as a heading. ## Where next For procedures, not warnings. For Q&A blocks. ### Tabs URL: https://docs.dokly.co/components/tabs Summary: Multi-tab content blocks. Common for code-in-multiple-languages and platform-specific instructions. Tabs let you show variants of the same content in one block. Most often used for code samples in multiple languages, or instructions for different platforms. ## Example curl JavaScript Python ``` curl https://api.example.com/v1/users \ -H "Authorization: Bearer YOUR_TOKEN" ``` ``` const res = await fetch("https://api.example.com/v1/users", { headers: { Authorization: `Bearer ${token}` }, }); const users = await res.json(); ``` ``` import requests res = requests.get( "https://api.example.com/v1/users", headers={"Authorization": f"Bearer {token}"}, ) users = res.json() ``` ## Insert Use the slash menu: `/tabs`. The block inserts with two empty tabs. Click a tab label to rename it; click the `+` after the last tab to add another. Each tab can hold anything — code, prose, callouts, even nested blocks. ## Tabs sync across the page If a reader picks "Python" in one tab block, all other tab blocks on the page that have a "Python" tab switch too. This means a reader using Python only ever sees Python examples. Sync is by tab label (case-insensitive). For sync to work, use consistent labels — `JavaScript` everywhere, not `JavaScript` in one and `Node` in another. ## When to use Tabs vs separate code blocks | Situation | Use | |---|---| | Same operation, different languages | Tabs | | Same operation, different shells (bash, PowerShell) | Tabs | | Different steps in a process | Steps, not Tabs | | Showing input vs output | Two code blocks, not Tabs | ## Limits - Maximum 6 tabs per block. More than that and the reader can't scan them. - Each tab can contain anything — code, prose, callouts, even nested components. - Tabs don't show URLs in the address bar. If you need linkable variants, make them separate pages. ## Where next For single-language code samples. For sequential procedures. ### Steps URL: https://docs.dokly.co/components/steps Summary: Numbered, titled steps for procedures and tutorials. The Steps component renders a numbered list with bold step titles and rich content per step. It's the right choice for any procedure where order matters. ## Example ``` npm install @example/sdk ``` ``` import { Client } from "@example/sdk"; const client = new Client({ apiKey: process.env.API_KEY }); ``` ``` const result = await client.users.list(); console.log(result); ``` ## Insert Use the slash menu: `/steps`. The block inserts with a couple of placeholder steps. Hit Enter inside a step to break to a new paragraph; press Enter on an empty step (or use the `+` between steps) to add another step. ## Settings Each Step has one setting: | Setting | Description | |---|---| | Title | Bold title shown next to the step number | The body of a step can hold anything — code, callouts, images, sub-lists. ## When to use Steps vs an ordered list | Situation | Use | |---|---| | Each step has a single short sentence | Ordered list (`1. Do X`) | | Each step has its own paragraph(s), code, or sub-content | Steps | | Steps are independent options | Cards, not Steps | If you find yourself with a Steps block where every step is one sentence, switch to a plain ordered list — Steps is overkill for that. ## Nesting other components Steps work well with code blocks, callouts, and images: Add the API key to your `.env` file: ``` EXAMPLE_API_KEY=sk_live_... ``` Add `.env` to your `.gitignore`. Environment variables only load on startup. ## Long step titles Keep titles short — under 60 characters. The number-and-title row is meant to be scannable. Put the detail in the body. Bad title: "Configure the OAuth callback URL in your app's settings page so that Example can redirect users back to your app after they authenticate" Better: "Configure the OAuth callback URL" (with the rest in the body). ## Where next For showing variants of the same step. For non-sequential options. ### Cards & Card group URL: https://docs.dokly.co/components/cards Summary: Linked cards with icons. The right component for hubs, indexes, and 'where to go next' sections. Cards are visual links — a title, a description, an icon, and a destination. Card groups arrange them in a grid. Use them for the homepage of a section, "next steps" blocks at the end of pages, and any place readers need to pick from a small set of options. ## Example: a 2-column card group Five minutes to a live docs site. Every block you can drop into a page. Make your reference interactive. Move from `*.dokly.co` to your own domain. ## Insert For a single card, use `/card`. For a grid, use `/cardgroup` and add cards inside it. Each card has settings for title, icon, link, and description — edit them from the inline controls or the inspector panel. ## Settings ### Card Group | Setting | Values | Default | Description | |---|---|---|---| | Columns | 1, 2, 3, 4 | 2 | Columns at desktop widths. Always 1 column on mobile. | ### Card | Setting | Description | |---|---| | Title | Bold title at the top of the card | | Icon | Pick from Dokly's icon set — see below | | Link | Destination — internal path or external URL | | Description | The text shown below the title | ## A single card (no group) A card works on its own — useful for a single CTA in the middle of a page. Custom domain, AI generation, and analytics — no payment info required. ## Available icons The icon picker in the editor surfaces a curated set you can search by name. Common ones include `rocket`, `code`, `terminal`, `book`, `users`, `globe`, `palette`, `layout-grid`, `list-ordered`, `image`, `zap`, `sparkles`, `credit-card`, `command`, `settings`, `help-circle`, `alert-circle`, `check`, `arrow-right`. If you don't see what you need, pick the closest match — readers rarely interpret icons literally. ## When to use Cards | Situation | Use | |---|---| | Hub page (homepage of a section) | CardGroup with 4–8 cards | | "Where to go next" at the end of a page | CardGroup with 2–4 cards | | Single highlighted CTA | Bare `` | | Linking sub-pages of the current section | CardGroup | | Linking unrelated external resources | Bullet list of links, not Cards | Cards are heavy visually — every card you add competes for attention. If you have more than 8 options, use a list. ## Where next How the page tree maps to your sidebar. Customize the card colors to match your brand. ### Code blocks URL: https://docs.dokly.co/components/code-blocks Summary: Syntax-highlighted code with a language tag, line numbers, and a copy button. Code blocks in Dokly are syntax-highlighted with VS Code-quality themes. Every block has a copy button and an optional language label. ## Basic example ``` function greet(name) { return `Hello, ${name}!`; } ``` ## Insert Use the slash menu: `/code`. Or type three backticks ` ``` ` at the start of a new line — the block transforms into a code block, and the cursor lands in the language field at the top of the block. ## Specifying the language Set the language from the dropdown at the top of the code block. Common ones: | Tag | Language | |---|---| | `js`, `javascript` | JavaScript | | `ts`, `typescript` | TypeScript | | `tsx`, `jsx` | TypeScript / JavaScript with JSX | | `py`, `python` | Python | | `go` | Go | | `rs`, `rust` | Rust | | `bash`, `sh` | Bash | | `json` | JSON | | `yaml`, `yml` | YAML | | `html` | HTML | | `css` | CSS | | `sql` | SQL | | `text` | No highlighting | If you don't pick a language, the block has no syntax highlighting. Pick `text` explicitly when you want a code block for non-code (e.g., terminal output). ## Title and filename Set a **Title** in the block's settings to show a header above the code (e.g., `components/Button.tsx`). This is the right way to indicate "this code lives in *this* file". ```js title="components/Button.tsx" return {children}; } ``` ## Highlighting lines Highlight specific lines from the block's settings — enter line numbers or ranges (e.g., `2`, `4-5`). ```js {2,4-5} function process(input) { const cleaned = input.trim(); console.log("Processing:", cleaned); const result = transform(cleaned); return result; } ``` ## Copy button Every code block has a copy button in the top-right that copies the raw code (without line numbers or highlighting). The button shows for 1.5 seconds, then fades. There's no way to disable it — copyable code is a baseline accessibility expectation. ## When to use a code block vs inline code | Type | Use | |---|---| | Inline `` `code` `` | A variable name, a flag, a single command | | Block | Anything multi-line, any code with structure, anything you want copyable | If you write more than ~80 characters of inline code, switch to a block. ## Where next For showing the same code in multiple languages. For code that should be runnable inline. ### API Playground URL: https://docs.dokly.co/components/api-playground Summary: Interactive endpoint runner — readers fill in parameters, hit Send, and see the real response inline. The API Playground component renders a single, runnable endpoint inside your page. Readers fill in the parameters, hit **Send**, and see the actual HTTP response — without leaving the docs. It's the building block behind the [auto-generated OpenAPI reference](/api-reference/openapi-import). You can also drop a single playground into any page when you want a focused example. Pro plan or higher ## Example screenshot of the rendered playground showing parameter form, Send button, response viewer ## Insert Use the slash menu: `/api`. After inserting, click the block to open the inspector — that's where you set the method, URL, parameters, body schema, headers, and auth scheme. ## Settings | Setting | Description | |---|---| | Method | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` | | URL | Full URL, with `{path}` placeholders for path params | | Parameters | Path and query params — name, type, required, description | | Body | JSON Schema for the request body (POST/PUT/PATCH) | | Headers | Name/value pairs (Authorization is added automatically) | | Auth | Bearer, API key, Basic, or None — defaults to your project setting | ## Authentication The playground reads project-level auth config from Settings → API → Authentication. Readers see an "Add token" field above the request form; tokens are stored in their browser only — never sent to Dokly servers. Set Auth to **None** on a specific playground to hide the auth field — useful for public endpoints. ## Body schema For `POST`, `PUT`, and `PATCH` endpoints, set the body schema in the inspector. The playground generates a form from the schema; readers can also switch to "Raw JSON" mode to paste a body directly. ## Response viewer The response panel shows: - **Status** — color-coded (green for 2xx, yellow for 4xx, red for 5xx). - **Time** — request duration. - **Headers** — collapsible. - **Body** — pretty-printed JSON with syntax highlighting. Auto-collapsed if longer than 50 lines. If the API returns CORS errors, the playground shows a friendly error explaining why and links to your CORS configuration page. ## CORS configuration For the playground to actually call your API, your API must allow requests from `*.dokly.co` (or your custom domain). Add to your CORS config: ``` Access-Control-Allow-Origin: https://docs.acme.com Access-Control-Allow-Headers: Authorization, Content-Type Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE ``` For development, you can also add `https://localhost:3000` and `https://*.dokly.co`. ## When to use a single playground vs OpenAPI | Situation | Use | |---|---| | One or two endpoints in the middle of a guide | Single `` | | Full API reference (10+ endpoints) | [OpenAPI import](/api-reference/openapi-import) | The OpenAPI import is just a way to generate one playground per endpoint at scale. The component is the same. ## Where next Generate a full reference from a spec. How to wire up Bearer, API key, and OAuth. ### FAQ URL: https://docs.dokly.co/components/faq Summary: Collapsible question and answer blocks. Useful for FAQ pages and 'common gotchas' sections. The FAQ component renders a collapsible question + answer. Multiple FAQ blocks stacked together form an accordion. ## Example Yes — on Pro plans and above. Add your domain in Project Settings → Domains, then point a CNAME at the value Dokly gives you. HTTPS is provisioned automatically within a few minutes. Multi-member teams are on the Scale plan ($99/mo, 5 seats). Free, Starter, and Pro are single-seat. ## Insert Use the slash menu: `/faq`. Each FAQ block holds one question and one answer. Stack multiple FAQ blocks back-to-back to build an accordion. ## Settings | Setting | Description | |---|---| | Question | The question. Shown as the clickable header. | | Answer | The answer body. Anything goes — prose, code, lists. | | Default open | Whether the answer is expanded on first load. Off by default. | ## When to use FAQ vs prose FAQ blocks are right when: - The reader is scanning for one specific answer (FAQ pages). - The page would be too long if every answer was inline. - The information is genuinely optional context (gotchas, caveats). FAQ blocks are wrong when: - The reader needs to read top to bottom (a tutorial). - You're hiding important information that everyone needs to see. Don't use FAQ to hide bad UX. If your readers all hit the same gotcha, the gotcha needs to be a callout in the main flow, not a collapsed FAQ. ## SEO FAQ blocks render with proper `` / `` semantics. Search engines and AI crawlers can read the answers without expanding the block. If you mark up your FAQ page as `FAQPage` schema, the FAQ blocks contribute to the structured data automatically — see [SEO](/site/seo). ## Where next For inline warnings and tips. How FAQ blocks power FAQ schema. ### Badges URL: https://docs.dokly.co/components/badges Summary: Small inline labels — Pro, Beta, Deprecated, New. Badges are inline labels that signal the status of a feature or page. They're small enough to drop next to a heading or in a sentence without disrupting the flow. ## Examples Default   Beta   New   Pro plan   Deprecated ## Insert Use the slash menu: `/badge`. The badge is inline — it lives next to text, not on its own line. Click the badge after inserting to change its color, size, shape, or label from the inspector panel. ## Settings | Setting | Values | Default | Description | |---|---|---|---| | Color | Gray, Blue, Green, Yellow, Orange, Red, Purple | Gray | Background and text color | | Size | XS, SM, MD, LG | MD | Visual size | | Shape | Rounded, Pill | Rounded | Corner radius | | Icon | Lucide icon name | none | Optional inline icon | | Stroke | on/off | off | Outline-only variant | | Label | text | required | Keep it short — one or two words | ## Common patterns - **Plan-gating** — drop a yellow "Pro" badge next to a heading so readers see at a glance that the feature requires Pro. - **New / Beta tags** — green "New" or blue "Beta" next to feature names in your changelog or sidebar. - **Deprecated APIs** — red "Deprecated" next to the API name. Always pair with a callout explaining the replacement: Use `client.users.get()` instead. `fetch()` will be removed in v2.0. ## When not to use a Badge - Don't put more than one Badge on the same heading. It looks busy. - Don't use Badges for marketing language ("Awesome!", "Hot!"). They're informational, not promotional. - Don't use a Badge where a Callout would carry the message better. Badges are flags, not warnings. ## Where next For longer-form warnings. For code-specific deprecations. ### Images URL: https://docs.dokly.co/components/images Summary: Drag, paste, or upload — Dokly handles the rest. Optimization, lazy loading, and lightbox are automatic. Images in Dokly are first-class. Drag a file from your desktop, paste a screenshot from your clipboard, or use the slash menu — they all upload, optimize, and render the same way. ## Three ways to add an image Drag and drop Paste Slash menu Drag any image file from your desktop directly into the editor. Drop where you want it. Upload happens in the background; the image shows a placeholder until done. Take a screenshot (`⌘⇧4` on Mac, `Win+Shift+S` on Windows), then `⌘V` / `Ctrl+V` in the editor. Same result as dragging. Type `/image` to open the file picker. You can also paste an image URL — Dokly will fetch and re-host it on your project's storage. short screen recording showing drag-and-drop image upload from desktop into the editor ## What happens on upload 1. The image is uploaded to your project's storage. 2. Dokly generates optimized variants (modern formats, multiple sizes for responsive serving). 3. The original is preserved — you can always download the source. 4. On the published site, the image is served lazy-loaded with the right size for the reader's screen. You don't see any of this. The image just appears. ## Captions Add a caption by clicking the image and typing in the caption field below it. Captions render small and muted under the image. ## Alt text Click an image and the inspector shows an Alt text field. Fill it in. Alt text is **required** for accessibility — empty alt text gets flagged in the editor. If the image is purely decorative, type `decorative` in the alt field — Dokly tells screen readers to skip it. ## Storage limits | Plan | Image storage | |---|---| | Free | 0 (no uploads) | | Starter | 500 MB | | Pro | 2 GB | | Scale | 10 GB | | Enterprise | Unlimited | If you hit your limit, new uploads fail with a clear error. Existing images stay served. To free up space, delete unused images in Project Settings → Storage. ## Lightbox Clicking an image on the live site opens it in a lightbox at full resolution. There's no setting — it's always on. ## Image best practices - **Crop tightly.** Screenshots with 80% browser chrome and 20% content waste vertical space. Crop to the content. - **Keep file sizes reasonable.** Even with optimization, a 5MB screenshot is a 5MB upload. Compress before uploading if you can. - **Don't embed text-heavy images.** Code, terminal output, and tables should be real text, not screenshots — they're searchable and accessible. - **Use captions for context.** A screenshot without a caption is a screenshot the reader has to interpret on their own. ## Where next The full component list. How alt text and OG images affect search ranking. ## Customization URL: https://docs.dokly.co/customization Summary: Pages under Customization. Everything in this section. Colors, fonts, dark mode defaults, and visual brand controls. Upload your logo and favicon, and configure how they appear in the sidebar and browser tab. Move your docs from a Dokly subdomain to a domain you control — docs.acme.com instead of acme.dokly.co. Hide the 'Powered by Dokly' badge from your published site. ### Theming URL: https://docs.dokly.co/customization/theming Summary: Colors, fonts, dark mode defaults, and visual brand controls. Every Dokly project ships with a clean default theme that works for most products. When you're ready to make it match your brand, theming controls live in **Project Settings → Branding**. screenshot of the Branding settings page with color pickers and font selector ## What you can customize | Setting | Plans | Notes | |---|---|---| | Primary color | All | Buttons, links, accents | | Heading font | Starter+ | One Google Font from a curated list | | Body font | Starter+ | One Google Font from a curated list | | Sidebar background | Pro+ | Light / dark / custom hex | | Default theme | All | Light / dark / system | | Custom CSS | Pro+ | Free-form override | ## Primary color Pick a single primary color in Settings → Branding → Color. Dokly derives the full palette (hover states, dark-mode variants, focus rings) from this one value. ``` Primary: #FF5722 → used for: - Sidebar active link - Inline link color - Button background - Focus rings - Selection highlight ``` If your brand color is too light or too dark for accessible contrast, the editor warns you and suggests a tweaked variant for the affected elements. ## Fonts Two slots: heading and body. Both pick from the same curated list of Google Fonts that work well for technical documentation: - **Sans**: Inter, Geist, IBM Plex Sans, Manrope, DM Sans - **Serif**: Source Serif Pro, Lora, Crimson Pro - **Mono**: JetBrains Mono, Fira Code, IBM Plex Mono (mono is fixed for code blocks; this is the "sans" mono pair) You can't load custom self-hosted fonts on Free / Starter / Pro. Enterprise plans can. The list is curated to keep page weight predictable — every font is preloaded and woff2-compressed. ## Dark mode Three options for the default theme: - **Light** — site loads in light mode. - **Dark** — site loads in dark mode. - **System** — follows the reader's OS preference. Regardless of the default, every reader has a toggle in the top-right of the docs site. Their choice is remembered in localStorage. You don't get to opt out. Dokly assumes a dark mode toggle is non-negotiable for a developer-facing docs site. If you want light-only, the toggle just won't work — you can't remove it. ## Sidebar background Pro plans can override the sidebar background. Default is a subtle off-white in light mode and near-black in dark mode. You can pick: - **Light gray** — default - **Pure white** — for a flatter look - **Subtle tint** — picks up your primary color at low opacity - **Custom hex** — anything The active-link color is always derived from your primary; you can't override it independently. ## Saving changes Hit **Save** in the Branding panel to apply your changes across the whole site. Saves are atomic — your live site updates the moment you save, with no half-themed states. ## Reverting The "Reset to default" button at the bottom of Branding restores all settings to the Dokly defaults. There's no warning — settings are cheap to reset and you can always re-apply. ## Where next Upload your logo and favicon. Move from `*.dokly.co` to your domain. ### Logo & favicon URL: https://docs.dokly.co/customization/logo-favicon Summary: Upload your logo and favicon, and configure how they appear in the sidebar and browser tab. Your logo appears in the top-left of the sidebar on every page. The favicon appears in the browser tab and bookmarks. Both are configured in **Project Settings → Branding → Identity**. screenshot of the Identity section showing logo and favicon upload fields with previews ## Logo Upload a logo as PNG, SVG, or WebP. SVG is preferred — it scales crisply on retina displays and supports separate light/dark variants. ### Light and dark variants If your logo doesn't read well on both light and dark backgrounds (most don't), upload separate variants: - **Logo (light mode)** — used when the reader is on light theme. - **Logo (dark mode)** — used when the reader is on dark theme. Dokly swaps them automatically based on the reader's current theme. ### Recommended size Logos are rendered at ~120px wide in the sidebar. Upload at 2× (240px wide) for retina sharpness. Anything larger is downscaled. If your logo is wider than tall (most are), it'll fit naturally. If it's taller than wide (e.g., a stacked logomark + text), the sidebar will look unbalanced — consider using just the mark in the sidebar. ### Logo as link The sidebar logo links to your project's homepage by default (the `index` page or first published page). On Pro plans, you can override this in Settings → Identity → Logo URL — useful if you want the logo to link back to your marketing site instead. ## Favicon Upload a square PNG, ICO, or SVG. The favicon is shown in: - The browser tab - Bookmarks - The "Add to home screen" icon on mobile - Search results (where the search engine chooses to show one) ### Recommended size 512×512 PNG is the safe choice. Dokly generates the variants browsers actually use (16×16, 32×32, 192×192, 512×512, Apple Touch Icon). If you upload SVG, make sure it has a defined viewBox and renders well at 16×16 — favicons are tiny. ### Favicon vs logo The favicon is *not* automatically derived from your logo. Browsers render favicons at 16px — your full logo will be illegible at that size. Use just the mark, or a simplified version. If you don't have a separate favicon, Dokly uses the first letter of your project name in your primary color as a fallback. ## When to leave the defaults If you're documenting an internal tool or an early-stage project, the default Dokly logo and favicon are fine. They're branded as Dokly, but they don't shout — you can ship a usable docs site without ever uploading anything. For anything customer-facing, upload both. The favicon especially: a default favicon in a customer's bookmark bar looks unfinished. ## Where next Colors and fonts to match your logo. Hide the "Powered by Dokly" badge. ### Custom domain URL: https://docs.dokly.co/customization/custom-domain Summary: Move your docs from a Dokly subdomain to a domain you control — docs.acme.com instead of acme.dokly.co. By default, every project lives at `.dokly.co`. On the Pro plan and above, you can point a domain you own (e.g., `docs.acme.com`) at your project. HTTPS is provisioned automatically. Pro plan or higher ## How it works You add a CNAME record in your DNS provider that points your domain at Dokly's edge. Dokly detects the record, issues a certificate via Let's Encrypt, and starts serving your project from the new domain. Existing readers on `.dokly.co` get a 301 redirect to the new domain — bookmarks and search engine rankings carry over. ## Setup screenshot of the Domains panel showing the "Add custom domain" button Type the full hostname you want to use — e.g., `docs.acme.com`. Apex domains (`acme.com`) are supported but discouraged; subdomains route more cleanly with CNAMEs. Dokly shows you the exact target value to point at. It looks like: ``` Type: CNAME Name: docs Value: tenants.dokly.co TTL: Auto / 3600 ``` Add this record at your DNS provider (Cloudflare, Route 53, Namecheap, GoDaddy — same instructions work everywhere). Dokly polls every 30 seconds. Most DNS changes propagate in 1–5 minutes. The Domains panel shows live status — pending, verifying, certificate issuing, live. Run `dig docs.acme.com CNAME +short` to confirm the record is live globally. If it returns the right value but Dokly still says pending, hit the **Re-check** button. By default, the Dokly subdomain stays accessible alongside your custom domain. Toggle "Set as primary" to redirect the subdomain to the custom domain — recommended once you're confident the custom domain works. ## Apex domains (acme.com instead of docs.acme.com) CNAME records can't be set on apex domains in standard DNS. If you really want your docs at the root, you have two options: 1. **Use Cloudflare DNS** (free) and a CNAME flattening trick. Cloudflare lets you set a "CNAME" on the apex; it resolves to A/AAAA records under the hood. 2. **Use ALIAS / ANAME records** — supported by Route 53, DNSimple, and a few others. For most teams, `docs.acme.com` is the right default — short, conventional, easier to manage. ## HTTPS and certificates You don't manage certificates. Dokly issues a Let's Encrypt cert on first verification and auto-renews every 60 days. There's no manual upload, no annual renewal. If your domain has CAA records, make sure they include `letsencrypt.org`: ``` acme.com. CAA 0 issue "letsencrypt.org" ``` If you have CAA records that exclude Let's Encrypt, certificate issuance will fail with a clear error. ## Removing a domain Settings → Domains → **Remove**. The domain is detached immediately. The certificate is left to expire naturally (it doesn't matter — no traffic is being served). If you re-add a domain you previously removed, the cert is re-issued from scratch. ## Common issues Check that the CNAME isn't behind Cloudflare's proxy (orange cloud). Dokly needs to see the raw CNAME, not Cloudflare's proxied IPs. Set the record to "DNS only" (gray cloud) until verification completes. This usually means Cloudflare's SSL/TLS mode is set to "Flexible" — switch it to "Full" or "Full (strict)". Dokly's edge always serves HTTPS. No. A custom domain maps 1:1 to a project. If you need multi-project routing under one domain (e.g., `docs.acme.com/sdk` and `docs.acme.com/api`), use subpaths inside one project. ## Where next Hide the "Powered by Dokly" badge — Pro feature. What changes when you move to a custom domain. ### Remove branding URL: https://docs.dokly.co/customization/remove-branding Summary: Hide the 'Powered by Dokly' badge from your published site. Free and Starter plans include a small "Powered by Dokly" badge in the footer of the published site. Pro plans and above can remove it. Pro plan or higher ## Where the badge is On Free and Starter, a single line in the site footer: ``` Powered by Dokly ``` It's small, low-contrast, and links to dokly.co. It does not appear in the editor or the dashboard — only on the published site. screenshot of the published site footer showing the "Powered by Dokly" badge ## How to remove it Settings → Billing → Upgrade. The badge removal is included automatically — no separate toggle needed once you're on Pro. Visit your published site and scroll to the footer. The badge is removed within ~10 seconds of the upgrade taking effect (CDN cache). That's it. There's no setting to flip — the badge presence is tied to your plan. ## Why we keep it on lower tiers Two reasons: 1. **It's how indie devs find us.** Most of our growth comes from someone seeing "Powered by Dokly" in a docs site they like and clicking through. 2. **It funds the free tier.** Free has real costs (storage, bandwidth, support). The badge is part of the trade. If you're using the free or starter plan and the badge is a dealbreaker — that's a fair signal you've outgrown the tier. Upgrade to Pro and it disappears, alongside everything else Pro unlocks. ## What's *not* part of the badge The badge is one small footer line. It's not: - A floating widget - A header banner - An interstitial - An ad If you ever see anything more intrusive than a footer line, that's a bug — file an issue. ## Where next The other most-asked-for Pro feature. What else Pro unlocks. ## Site URL: https://docs.dokly.co/site Summary: Pages under Site. Everything in this section. How the page tree maps to your sidebar, how URLs are derived from slugs, and how to organize a big site. Cmd+K fuzzy search — instant, in-browser, no extra setup. Sitemaps, meta tags, Open Graph, structured data, and llms.txt — everything Dokly does for search and AI discoverability. How dark mode works in Dokly — defaults, the toggle, and how to author for both themes. ### Pages & navigation URL: https://docs.dokly.co/site/pages-navigation Summary: How the page tree maps to your sidebar, how URLs are derived from slugs, and how to organize a big site. The page tree in the dashboard *is* your sidebar. There's no separate config file. Reorder pages → the sidebar updates. Nest a page under another → it becomes a sub-item. ## The page tree screenshot of the page tree sidebar in the dashboard, showing nested pages with drag handles Each page in the tree has: - **A drag handle** for reordering and nesting - **A title** (rename inline by double-clicking) - **A status indicator** (draft / published) - **A right-click menu** for duplicate, settings, delete Drag a page onto another page to nest it. Drag it out of the parent to un-nest. The sidebar on the live site mirrors the tree exactly. ## Slugs and URLs Each page has a slug. The slug is the URL path: | Slug | URL | |---|---| | `index` | `/` (the homepage) | | `quickstart` | `/quickstart` | | `editor/writing` | `/editor/writing` | | `api/users/list` | `/api/users/list` | Slugs are independent from the tree structure. You can have a slug like `editor/writing` even if the page isn't nested in the tree — the slug determines the URL, the tree determines the sidebar. That said, **keeping them in sync is a good practice.** If a page is nested under "Editor" in the sidebar, its slug should start with `editor/`. The sidebar will look right and the URL will read right. ### Special slug: `index` The page with slug `index` is your homepage — served at `/`. Every project should have one. If you don't, the homepage shows "No content yet" until you do. ### Slug rules - Lowercase letters, numbers, hyphens, and forward slashes only - No leading or trailing slashes - No spaces, no underscores, no special characters - Maximum 200 characters total The editor enforces these on input. ## Sidebar groups There's no separate "group" concept. A group in the sidebar is just a parent page with children: ``` Editor ← parent page, slug: editor/overview ├ Writing ← child, slug: editor/writing ├ Slash menu ← child, slug: editor/slash-menu └ AI actions ← child, slug: editor/ai-actions ``` The parent is the section's "overview" page. Clicking the parent in the sidebar opens its content; clicking the children opens theirs. ### Collapsible groups Each parent page in the sidebar has a collapse/expand chevron. The expanded/collapsed state is per-reader (stored in localStorage), so each reader picks their preferred view. You can set the *default* collapsed state per page in Page Settings → Display → "Collapsed by default in sidebar". Useful for keeping less-used sections out of the way. ## Reordering Drag a page up or down. The order is saved automatically. The sidebar order on the live site updates within ~10 seconds. If you need to reorder a lot of pages at once (e.g., after a large reorganization), you can also edit the `order_index` of each page in Page Settings — but the drag UI is faster for most cases. ## Drafts vs published Each page has a **published** toggle in Page Settings. - **Draft** — only visible in the dashboard. Doesn't appear on the live site or in the sidebar. - **Published** — live on the site, indexed by search engines, shown in the sidebar. New pages default to draft. Toggle to published when you're ready to ship. ## Bulk operations Right-click any page (or select multiple with `⌘`-click) to: - Publish / unpublish - Move to another section - Duplicate - Delete Delete is soft for 30 days — you can restore from Settings → Trash. ## Where next How readers find pages. Slugs, titles, and meta descriptions. ### Search URL: https://docs.dokly.co/site/search Summary: Cmd+K fuzzy search — instant, in-browser, no extra setup. Every Dokly site (Starter and above) has a search box in the top-right that opens a `⌘K` palette. Search is fuzzy, instant, and runs entirely in the reader's browser. Starter plan or higher screenshot of the open search palette showing typed query, results list with title + snippet, keyboard shortcut hints at the bottom ## How it works When a reader loads any page, Dokly fetches a single JSON index of every published page in the project. The index contains titles, descriptions, and section headings — enough to find any page by keyword. Search runs against that index in the reader's browser. Results show as they type, with no server roundtrip. The whole experience is sub-50ms. ## What's indexed | Field | Weight | |---|---| | Page title | High | | Page description | High | | H1 / H2 / H3 headings within the page | Medium | | Body paragraphs (first 500 chars) | Low | **Not indexed**: code blocks, images, and component metadata. Code blocks are ignored on purpose — searching for `function` shouldn't return every page with a code sample. ## Opening search | Action | Shortcut | |---|---| | Open palette | `⌘K` (Mac) or `Ctrl+K` (Windows) | | Click search box | (also opens) | | Move through results | `↑` / `↓` | | Open result | `Enter` | | Close palette | `Esc` | Mobile readers see a search button in the top bar that opens the same palette. ## Search appearance By default, the search box reads "Search docs..." with a `⌘K` hint. The placeholder, hint, and accent color match your project's theme automatically. You can customize the placeholder text in Project Settings → Search → Placeholder. Useful for branded copy ("Search the Acme docs" instead of "Search docs"). ## Customizing what gets indexed By default, every published page is indexed. To exclude specific pages: - **Page Settings → Display → "Hide from search"** — page is still public via direct URL but excluded from the search index. This is useful for legal pages, internal-only references, or duplicate landing pages that would clutter results. ## Why client-side? A few reasons: - **Speed.** No network roundtrip. Results appear as you type. - **Privacy.** Search queries don't leave the reader's browser. Nothing to log. - **Simplicity.** No search server to run, no Algolia bill, no index re-build job. The trade-off is that search is limited by what fits in the index payload. For projects with hundreds of pages, the index gets big enough to slow down the first page load — see the limits below. ## Limits | Plan | Max indexed pages | Notes | |---|---|---| | Free | 0 | No search | | Starter | 50 | Plenty for most projects | | Pro | 500 | Comfortable for any docs site | | Scale | 2,000 | For large multi-product docs | | Enterprise | Custom | Talk to us if you have more | If you exceed your plan's limit, search still works — but only the first N pages (by `order_index`) are indexed. You'll see a warning in Project Settings → Search. ## Server-side search (coming soon) For projects that genuinely outgrow client-side search (hundreds of pages, frequent search, AI-style natural language queries), we're building a server-side option. It'll be opt-in on Pro+ and use a hosted vector search backend. If you have an immediate need, reach out — we'll work with you. ## Where next See what readers are searching for (Pro+). How search engines find your pages. ### SEO URL: https://docs.dokly.co/site/seo Summary: Sitemaps, meta tags, Open Graph, structured data, and llms.txt — everything Dokly does for search and AI discoverability. Dokly handles the SEO basics automatically. You don't configure a sitemap or write meta tags — they're derived from your page titles, descriptions, and tree. This page documents what's done for you, what you can control, and what to do for the long tail of search and AI traffic. ## What's automatic | What | Where it comes from | |---|---| | `` tag | Page title + project name | | Meta description | Page description (frontmatter) | | Canonical URL | Page slug + custom/primary domain | | Open Graph image | Auto-generated per page (or custom — see below) | | `` | `index, follow` for published pages | | `sitemap.xml` | All published pages, regenerated on save | | `robots.txt` | Allows everything, points to sitemap | | `llms.txt` and `llms-full.txt` | Auto-generated for AI crawlers | You can verify these on any published page — view source and look for the meta tags. ## Page metadata Every page has three SEO-relevant fields, set in Page Settings: - **Title** — used in `` and as the H1. - **Description** — used in meta description, OG description, and search snippets. - **Slug** — used in the URL. The title and description appear in Google search results. Treat them like ad copy — they're often the first impression. ### Title formula Default formula: `{Page Title} – {Project Name}`. Override per-page in Page Settings → SEO → Title (Custom). Pro plans also let you change the default formula site-wide in Project Settings → SEO. Common alternatives: - `{Page Title} | {Project Name} Docs` - `{Project Name}: {Page Title}` - `{Page Title}` (no suffix) ### Description rules - 150–160 characters is the sweet spot - One sentence is fine; two is better - Lead with the value proposition, not "This page contains..." - Include the primary keyword once, naturally ## Open Graph images OG images are what shows up when your URL is shared on Twitter, LinkedIn, Slack, etc. By default, Dokly generates a clean OG image per page using your project name, page title, and brand color. They're regenerated automatically when you change the page title or your branding. To override per page: Page Settings → SEO → Custom OG image. Upload a 1200×630 PNG. To override site-wide: Project Settings → Branding → Default social image. example OG image showing Dokly's auto-generated style — gradient background, project logo, page title ## Structured data Dokly auto-emits JSON-LD structured data for: - **Article** — every page, with title, description, author (project name), datePublished, dateModified. - **BreadcrumbList** — derived from the page tree. - **FAQPage** — pages with one or more `` components are automatically marked up as FAQPage. You can verify with [Google's Rich Results Test](https://search.google.com/test/rich-results). ## llms.txt — for AI crawlers `llms.txt` is the emerging convention for telling LLM crawlers what your docs site contains. Dokly auto-generates two files: - `/llms.txt` — a structured index of every page (title + description + URL). - `/llms-full.txt` — the full text of every page, concatenated. These are served at the root of your domain. ChatGPT, Claude, Perplexity, and other AI tools that respect the convention can find and cite your docs. You don't configure anything. The files regenerate on every save. See [our blog post on llms.txt](https://dokly.co/blog/llms-txt-guide) for more on what it does. ## IndexNow and Search Console Dokly pings IndexNow on every page publish, so Bing and Yandex see your content within minutes. There's no setup. For Google Search Console: 1. Verify your domain in Search Console using the DNS TXT method. 2. Submit your sitemap: `https://your-domain.com/sitemap.xml`. Google indexing is fast for small docs sites — most pages appear in search within 24–48 hours. ## Custom robots and noindex To exclude a page from search engines: - Page Settings → SEO → "Noindex this page". The page still serves at its URL but emits `` and is removed from the sitemap. For site-wide robots.txt overrides (rare), Project Settings → SEO → Custom robots.txt (Pro+). ## Where next Move to a domain you own — better for SEO long-term. See what's actually getting traffic. ### Dark mode URL: https://docs.dokly.co/site/dark-mode Summary: How dark mode works in Dokly — defaults, the toggle, and how to author for both themes. Every Dokly site supports light and dark mode out of the box. Readers toggle between them with a button in the top-right; their choice is remembered. ## Defaults In Project Settings → Branding → Theme, pick the default theme: - **Light** — site loads in light mode. - **Dark** — site loads in dark mode. - **System** *(default)* — follows the reader's OS preference. Most developer-tool docs use **System**. It respects the reader's setup without forcing a choice. ## The toggle The toggle is always present in the top-right of the published site. There's no setting to remove it — readers expect it, and removing it would be hostile. The reader's choice is stored in localStorage on your domain. It persists across pages and visits. If localStorage is unavailable (e.g., private browsing), the choice is lost on reload. ## How components handle dark mode Every component Dokly ships with — Callout, Card, Tabs, Steps, code blocks, badges — has a dark-mode variant baked in. You don't think about it. Code blocks specifically: light mode uses GitHub Light, dark mode uses GitHub Dark. Both are tuned for high contrast and accessibility. ## Authoring for both themes The only thing you need to think about is **images**. A screenshot taken in light mode looks bad on a dark background. A screenshot in dark mode looks bad on a light one. Three options: Use one theme for all screenshots Upload light/dark variants Use neutral images Pick light or dark and stick to it. Most docs use light-mode screenshots even when the docs theme is dark — light screenshots are more legible at small sizes. Upload separate images for light and dark mode. Use the `theme` prop on the image: ``` ![Dashboard light](./dashboard-light.png) ![Dashboard dark](./dashboard-dark.png) ``` More work, better polish. Recommended for marketing-facing screenshots. Use diagrams or illustrations with transparent backgrounds. They look fine on either theme. ## Logos Logos are the other thing to handle. Most logos don't read on both backgrounds. See [Logo & favicon](/customization/logo-favicon) for how to upload light/dark variants. ## Theme detection in custom CSS If you're using custom CSS (Pro+), you can target dark mode with the `dark` class on the root element: ``` .my-class { color: black; } .dark .my-class { color: white; } ``` This matches the convention Dokly uses internally — Tailwind-style `dark:` variants. ## Where next Pick your colors and fonts. Upload light/dark logo variants. ## API Reference URL: https://docs.dokly.co/api-reference Summary: Pages under API Reference. Everything in this section. Make your API reference interactive — readers run real requests from inside the docs. Upload an OpenAPI 3 spec and get a full, interactive API reference auto-generated. How to configure Bearer tokens, API keys, Basic auth, and OAuth in your playground. ### Playground URL: https://docs.dokly.co/api-reference/playground Summary: Make your API reference interactive — readers run real requests from inside the docs. The Dokly API Playground lets readers send real requests to your API from inside the docs. Fill in parameters, hit Send, see the actual response. No copy-pasting curl into a terminal. The playground component is documented in detail in [Components → API Playground](/components/api-playground). This page is about the **bigger picture** — how to structure an API reference section that uses it well. Pro plan or higher ## The two ways to add a playground Drop a single `` block into a guide. Right for tutorials and one-off examples. Upload your spec; Dokly generates one page per endpoint. Right for full API references. ## What a good API reference looks like The reference is the spine of your developer docs. A good one has: Not a list of endpoints — a brief explanation of what the API does, the auth model, the rate limits, and where to start. Link to the quickstart from here. `/users` together. `/projects` together. `/billing` together. Don't sort alphabetically — group by what readers actually do together. With the playground at the top, prose context below, code samples in three or four languages, and a real response example. The first page a developer reads should walk them through their first successful request — using the playground, not curl. The activation moment is when they see a 200 response in the docs. ## Structure your sidebar Common pattern for an API reference section: ``` API Reference ├ Overview ← what the API does, auth, rate limits ├ Authentication ← how to get a token, where to put it ├ Errors ← error format, common codes ├ Users ← group │ ├ List users │ ├ Get user │ ├ Create user │ └ Delete user ├ Projects ← group │ ├ List projects │ └ ... └ Webhooks ← group └ ... ``` OpenAPI import generates this structure automatically from your spec's `tags`. ## Authentication setup The playground needs a way to authenticate against your API. Configure once, applies everywhere. In Project Settings → API → Authentication: | Auth type | What you configure | What readers see | |---|---|---| | **Bearer token** | Header name (`Authorization`) and prefix (`Bearer`) | Token input field above the request form | | **API key** | Header or query param name | Key input field | | **Basic** | Realm | Username + password fields | | **OAuth 2.0** | Authorize URL, token URL, scopes | "Sign in with..." button that opens the OAuth flow | | **None** | — | No auth UI | Tokens entered by readers are stored in browser localStorage only. They never reach Dokly servers. ## CORS For the playground to work, your API must allow cross-origin requests from your docs domain. See the [API Playground component](/components/api-playground#cors-configuration) for the headers you need to send. If CORS isn't set up, the playground returns a clear error explaining what's wrong, with a link to this page. ## Where next Generate a full reference from a spec. Bearer, API key, OAuth — concrete configs. ### OpenAPI import URL: https://docs.dokly.co/api-reference/openapi-import Summary: Upload an OpenAPI 3 spec and get a full, interactive API reference auto-generated. If you have an OpenAPI 3.x spec, you don't need to write API reference pages by hand. Upload the spec to Dokly and it generates one page per endpoint, organized by tag, with the playground wired up automatically. Pro plan or higher ## Setup screenshot of the OpenAPI settings panel showing upload area Drag in your `openapi.yaml` or `openapi.json`. Dokly accepts OpenAPI 3.0 and 3.1. For specs hosted at a URL (e.g., a public spec on GitHub), paste the URL — Dokly fetches and re-validates. Generated pages need to slot into your page tree somewhere. Pick a parent (commonly an "API Reference" page you've already created). OpenAPI specs can list multiple servers (production, staging). Pick which one the playground sends requests to. You can also let readers switch. Dokly creates one page per `path` × `method` combination. A spec with 30 endpoints across 6 tags becomes 30 pages organized into 6 groups in your sidebar. Generation usually takes 5–15 seconds. The pages appear in the tree as they're created. ## What gets generated For each endpoint: | Section | Source | |---|---| | Page title | `summary` | | Description (top of page) | `description` | | Method + URL badge | OpenAPI `path` and `method` | | Parameters table | `parameters` (path, query, header) | | Request body schema | `requestBody.content` | | Authentication | `security` (or project default) | | Response examples | `responses[code].examples` or `examples` | | Code samples | Auto-generated from spec (curl, JS, Python, Go, Ruby) | | Playground | Configured from all of the above | The page is editable. Anything you change is preserved on next sync — see below. ## Re-syncing after spec changes When your API changes, re-upload the spec. Dokly does a 3-way merge: - **New endpoints** — added as new pages. - **Removed endpoints** — pages soft-deleted (recoverable for 30 days). - **Changed endpoints** — auto-generated sections (parameters, schema, codes) are updated; your manual edits (added prose, examples, callouts) are preserved. You'll see a diff before each sync so you can review changes. ## Custom prose around generated content The generated pages have an "Editable narrative" section between the header and the playground. Add anything: when to use this endpoint, common gotchas, links to related guides. This content survives re-syncs. ``` ## When to use this endpoint Use `/users` for CRUD. For bulk operations (>100 users), use the batch endpoint at `/users/batch` — it's optimized for throughput. ## Common errors - `403` usually means the user is on a Free plan. Check `/users/me/plan` first. - `429` from this endpoint is per-account, not per-token. Wait the `Retry-After` window before retrying. ``` ## Multi-language code samples Code samples are auto-generated for: curl, JavaScript (fetch), Python (requests), Go, Ruby. The samples include real placeholders for your specific request shape — they're not generic. A POST endpoint with a body shows the body filled in; a GET with query params shows the params in the URL. You can hide languages your audience doesn't use in Project Settings → API → Code Samples. ## Limitations - **OpenAPI 2.0 (Swagger)** — not supported. Convert to 3.0 first using a tool like [swagger-converter](https://converter.swagger.io). - **AsyncAPI** — not supported. - **GraphQL** — separate import flow, on the roadmap. - **gRPC / proto** — not supported. ## Common issues Dokly uses strict OpenAPI 3.x parsing. Common gotchas: missing required fields (`info.version`, `info.title`), `$ref`s pointing to external files (Dokly resolves only inline `$ref`s today), or `nullable: true` in places it's not allowed in 3.1. Run `npx @redocly/cli lint openapi.yaml` for a strict validation that matches Dokly's behavior. Endpoint order within a tag is the order they appear in the spec. Reorder by editing the spec, or drag the pages in the tree after generation — manual order overrides spec order on re-sync. Yes — upload multiple specs into different parent pages. Common pattern: separate specs for v1 and v2 of an API, each generating into its own section. ## Where next Wire up Bearer, API key, OAuth. Drop a single playground into a non-reference page. ### Authentication examples URL: https://docs.dokly.co/api-reference/auth-examples Summary: How to configure Bearer tokens, API keys, Basic auth, and OAuth in your playground. The playground supports four common auth schemes. Pick whichever your API uses, configure once in Project Settings → API → Authentication, and every endpoint inherits the setup. ## Bearer token The most common pattern for modern APIs. The reader pastes a token; Dokly sends it as `Authorization: Bearer `. ### Configure ``` Type: Bearer Header: Authorization Prefix: Bearer ``` ### What the reader sees A "Bearer token" input field above the request form. The token is stored in browser localStorage; it's never sent to Dokly servers. screenshot of the playground showing the Bearer token input field ### In your OpenAPI spec ``` components: securitySchemes: BearerAuth: type: http scheme: bearer security: - BearerAuth: [] ``` If your spec defines `BearerAuth` like this, the playground picks it up automatically — no manual config needed. ## API key For APIs that use a long-lived key passed in a header or query param. ### Configure ``` Type: API key Location: Header (or Query) Name: X-API-Key (or whatever your API uses) ``` ### What the reader sees An "API key" input field. The key is added to the configured header or query parameter on every request. ### In your OpenAPI spec ``` components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key security: - ApiKeyAuth: [] ``` ## Basic auth Username + password, sent as a base64-encoded `Authorization: Basic` header. Rare in modern APIs; common in admin panels and legacy systems. ### Configure ``` Type: Basic Realm: (optional, shown as a hint to the reader) ``` ### What the reader sees Two input fields — username and password. Dokly base64-encodes them before sending. ## OAuth 2.0 For APIs that require a full OAuth flow. ### Configure ``` Type: OAuth 2.0 Flow: Authorization Code (or Client Credentials) Authorize URL: https://your-api.com/oauth/authorize Token URL: https://your-api.com/oauth/token Scopes: read:users, write:users (one per line) Client ID: (your OAuth app's client ID) ``` ### What the reader sees A "Sign in with..." button that opens the OAuth flow in a new window. After consent, the access token is captured automatically and used for subsequent requests. ### Setting up the OAuth app You'll need to register an OAuth app with your provider and add Dokly's redirect URI to the app's allowed callbacks: ``` https://docs.your-domain.com/api/auth/oauth-callback ``` Or for projects on a Dokly subdomain: ``` https://your-subdomain.dokly.co/api/auth/oauth-callback ``` ## Multiple auth schemes Some APIs support multiple auth methods (e.g., Bearer for users, API key for service accounts). Configure all of them — readers see a tabbed picker above the request form. You can also override per-endpoint by setting the `auth` prop on the playground component: ``` ``` ## Mock authentication for testing For the most common case — letting readers try the playground *without* signing up for your API first — provide a sandbox. A common pattern: 1. Run a sandbox version of your API at `sandbox.your-api.com`. 2. Make the sandbox accept a hardcoded test token (e.g., `Bearer test_token`). 3. Document the test token prominently in your "Authentication" doc. 4. Configure the playground to default to the sandbox URL. Readers go from "find docs" to "first 200 response" in under a minute. That's the activation moment that turns prospects into users. ## Where next Generate a full reference from your spec. Drop a single playground into any page. ## Analytics URL: https://docs.dokly.co/analytics Summary: Pages under Analytics. Everything in this section. What Dokly tracks, what it doesn't, and how to use the data to make your docs better. Per-page traffic, trends, and how to use them to prioritize editing. What readers searched for, what returned no results, and what to do about it. ### Analytics overview URL: https://docs.dokly.co/analytics/overview Summary: What Dokly tracks, what it doesn't, and how to use the data to make your docs better. Analytics give you signal on what's working in your docs — which pages get traffic, where readers land, what they search for, and what sends them away. Pro plan or higher ## What's tracked | Signal | Where to see it | |---|---| | Page views (per page, daily) | [Top pages](/analytics/top-pages) | | Unique visitors | Top pages | | Bounce rate | Top pages | | Search queries | [Search queries](/analytics/search-queries) | | Search queries with no results | Search queries | | Top entry pages | Analytics overview | | Top exit pages | Analytics overview | | Referrer (Google, Twitter, direct, etc.) | Analytics overview | screenshot of the analytics overview dashboard showing the chart of page views, top pages list, referrers panel ## What's not tracked By design: - **No reader identity.** No login required, no fingerprinting, no personalization. - **No reader IPs stored.** IPs are hashed and discarded after the geo lookup. - **No third-party cookies.** Dokly's analytics are first-party only. - **No session recording.** No heatmaps, no rage-click detection, no scroll videos. This is intentional. Docs analytics should be useful enough to make decisions and minimal enough to not require a cookie banner. ## Privacy compliance Dokly's analytics are GDPR-compliant out of the box. No consent banner is required because: - No personal data is collected. - No cross-site tracking. - IPs are hashed at edge. You can disable analytics entirely (Project Settings → Privacy → Disable analytics) if your compliance team prefers. ## Reading the data Three questions analytics should help you answer: ### 1. What are people landing on? Top entry pages tell you what brought readers in. Usually: - Your homepage (direct or branded search) - Pages that rank for specific keywords - Pages linked from your marketing site If a page is a top entry page but has high bounce rate, it's not delivering on the promise of whatever brought the reader there. Often that means the title or meta description over-promises. ### 2. What are they searching for? [Search queries](/analytics/search-queries) tell you what readers expect to find. Two patterns to watch: - **High-frequency queries with no results** — pages you should write. - **High-frequency queries that lead nowhere** (the reader searches, doesn't click) — pages you have but with bad titles/descriptions. ### 3. Where do they get stuck? Top exit pages are pages where the reader leaves the docs. Some exits are good (the reader got their answer and left). Others are bad (the reader hit a dead end). Dead-end signals to watch: - A tutorial step page is a top exit page - A reference page has high views but low time-on-page - A page is the most-viewed *and* the most-exited ## Limits Analytics are retained for: | Plan | Retention | |---|---| | Free | None | | Starter | None | | Pro | 90 days | | Scale | 1 year | | Enterprise | Configurable | For longer retention, export to CSV (Pro+) or pipe to your own analytics warehouse. ## Where next Per-page view counts and trends. What readers are searching for. ### Top pages URL: https://docs.dokly.co/analytics/top-pages Summary: Per-page traffic, trends, and how to use them to prioritize editing. The Top Pages report shows views per page over a date range, sorted by traffic. It's the first place to look when you're deciding what to improve. Pro plan or higher screenshot of the Top Pages table showing page title, views, unique visitors, bounce rate, average time on page, with a date range picker at the top ## Columns | Column | What it means | |---|---| | Page | Title and slug | | Views | Total page views in the date range | | Unique visitors | Distinct sessions (24h window) | | Bounce rate | % of sessions that viewed only this page and left | | Avg. time on page | Median time before navigating away or closing the tab | | Δ vs prior period | Change vs the previous date range of the same length | Sortable by any column. ## Date ranges Default is the last 30 days. Other quick ranges: 7 days, 90 days, 12 months. Custom ranges are supported on Scale and Enterprise. The "Δ vs prior period" column compares to the same length immediately before the current range. So if you're viewing "last 7 days," it compares to the 7 days before that. ## How to use this ### Triage the top 10 Spend time on the pages that get traffic. The top 10 pages typically account for 50–80% of all views. Improving them is the highest-leverage work you can do. For each top page: 1. Read it as a new reader. 2. Check the bounce rate. High bounce + high views = the page isn't doing its job. 3. Check the time on page. Short time + technical content = readers aren't finding what they need. ### Find the orphans Sort by views ascending, ignore drafts. Pages with zero or near-zero views over 30 days are candidates for: - **Promotion** — link from higher-traffic pages. - **Consolidation** — merge into a related page. - **Deletion** — if no one's reading it and no one's looking for it. Be careful with deletion — sometimes a page has zero views because no one knows it exists, not because it's not useful. ### Track a launch When you publish a new feature, watch the related docs page over the following 7 days. View counts tell you whether the launch is reaching the target audience. Bounce rate tells you whether the docs are landing. ## Filtering Filters at the top of the table: - **By section** — only show pages under a specific parent (e.g., only API Reference). - **By referrer** — only show pages that received traffic from a specific source. - **Search** — find a specific page by title or slug. Filters combine. "Pages under API Reference, from Google, in the last 30 days" works. ## Export Click **Export** for a CSV of the current view (filtered, date-ranged, sorted). Useful for sharing with your team or piping into your own analytics tool. CSV exports include all columns plus a `date` column with daily breakdowns. ## What "view" means A view is counted when: - A page renders in the browser (server- or client-side). - The reader is human (basic bot filtering applied). - The reader hasn't viewed the same page in the last 30 minutes. Repeated views in a single session by the same reader count as one. Refreshes within 30 minutes don't double-count. ## Where next What readers wanted but couldn't find. The dashboard view. ### Search queries URL: https://docs.dokly.co/analytics/search-queries Summary: What readers searched for, what returned no results, and what to do about it. The Search Queries report tells you exactly what readers expect to find in your docs. It's often more useful than page-view analytics — page views tell you what's *there*, search tells you what's *missing*. Pro plan or higher screenshot of the Search Queries view: tabbed switcher for "All queries" / "No results", a table with query, count, click-through rate, last seen ## Two tabs ### All queries Every search executed in the date range, sorted by frequency. Columns: - **Query** — what the reader typed - **Count** — how many times searched - **CTR (click-through rate)** — % of searches where the reader clicked a result - **Last seen** — most recent search A query with high count and low CTR means readers are searching for something but not finding the right page. Either the query is genuinely missing content, or you have a page about it but the title/description doesn't match the intent. ### No results Queries that returned zero results. These are the highest-signal source of "what should I write next." Common patterns: - **Misspellings of existing concepts** — your search index might be too strict. Add common misspellings to the page's title or description. - **Related concepts you don't cover** — readers expect coverage and you don't have it. Write the page. - **Outdated terminology** — readers searching for an old name. Add a redirect or mention the old term in the new page. ## Date ranges and filters Same controls as [Top Pages](/analytics/top-pages). Default is 30 days; you can filter by section (only show searches that happened on pages under a specific parent — useful for diagnosing missing API docs vs missing concept docs). ## Privacy Search queries are stored verbatim. They could contain sensitive info if a reader pastes a token or PII into the search box (rare but possible). If you're concerned, you can disable query logging in Project Settings → Privacy → Disable search logging. The search itself still works; only the analytics trail goes away. ## How to act on this A weekly 15-minute ritual that compounds: Sort by count descending. For each one, ask: - Is there a page that should match this query? - If yes, why didn't the search find it? (Probably a title/description mismatch — fix it.) - If no, should I write a new page? Add it to your queue. Look for queries with high count but low CTR. Read the page that *should* match and ask whether the title and first paragraph make it clear. Most fixes are 5-minute edits. Batch them. This single ritual is the highest-leverage docs work I know. ## Export Click **Export** for a CSV of the queries with all columns. Useful for keyword research, prioritization meetings, or piping into your team's planning tool. ## Where next What pages are getting traffic. How the search itself works. ## Account URL: https://docs.dokly.co/account Summary: Pages under Account. Everything in this section. Free, Starter, Pro, Scale, Enterprise — what's in each, and which one to pick. How AI usage is metered, what your monthly bucket covers, and how top-ups work. Every new account gets 14 days of Pro features automatically. Here's what's included and what happens at day 14. ### Plans & pricing URL: https://docs.dokly.co/account/plans Summary: Free, Starter, Pro, Scale, Enterprise — what's in each, and which one to pick. Dokly's pricing is plan-based, not per-seat. You pay for capability, not for chairs. ## The plans | Plan | Price | Best for | |---|---|---| | **Free** | $0 | Side projects, evaluation, OSS docs | | **Starter** | $19/mo | Indie hackers, early-stage startups, small APIs | | **Pro** | $49/mo | Growing startups, real product docs, API references | | **Scale** | $99/mo | Multi-product teams, larger orgs | | **Enterprise** | Custom | Compliance, SSO, dedicated support | ## What each plan unlocks | Feature | Free | Starter | Pro | Scale | Enterprise | |---|---|---|---|---|---| | Projects | 1 | 3 | 10 | 25 | Unlimited | | Pages per project | 5 | 25 | Unlimited | Unlimited | Unlimited | | Custom subdomain | Yes | Yes | Yes | Yes | Yes | | Custom domain | — | — | Yes | Yes | Yes | | Search (Cmd+K) | — | Yes | Yes | Yes | Yes | | Analytics | — | — | Yes | Yes | Yes | | API Playground | — | — | Yes | Yes | Yes | | OpenAPI import | — | — | Yes | Yes | Yes | | Image storage | — | 500 MB | 2 GB | 10 GB | Unlimited | | Remove "Powered by Dokly" | — | — | Yes | Yes | Yes | | AI credits/month | Trial only | Small bucket | Medium bucket | Large bucket | Custom | | Custom CSS | — | — | Yes | Yes | Yes | | Team members | 1 | 1 | 1 | 5 (+$10 each) | Unlimited | | Support | Community | Email (48h) | Priority (24h) | Priority (12h) | Dedicated | | BYOK (your own AI key) | — | — | — | — | Yes | | SSO/SAML | — | — | — | — | Yes | ## Which plan is right **Free.** No card required. 5 pages is enough to see whether Dokly fits your workflow. The 14-day Pro trial unlocks the full feature set so you can evaluate. **Starter ($19/mo).** Search, 3 projects, 25 pages each. Right for a personal project or a single product up to ~25 pages. **Pro ($49/mo).** This is the plan most paying customers are on. Custom domain, unlimited pages, OpenAPI playground, analytics, AI credits. **Scale ($99/mo).** 25 projects, 5 team members, more storage. The right tier when you have a product suite or a docs team larger than one. For Enterprise (SSO, BYOK, custom retention, SLAs), [book a call](https://dokly.co/contact). ## Trial Every new account gets **14 days of Pro features** automatically. No card, no sign-up step. After 14 days, you drop to Free unless you've upgraded. The trial covers everything Pro includes — custom domains, AI generation, analytics — so you can see whether it changes how you work before paying. See [Trial](/account/trial) for what happens at day 14. ## Annual discount Pay annually for 2 months free. The toggle is on the [pricing page](https://dokly.co/pricing) and in Settings → Billing. ## Switching plans Upgrade: instant. Downgrade: takes effect at the end of your current billing period. Your data is preserved on downgrade — pages over the new limit are hidden, not deleted, until you upgrade again or remove them. ## Where the money goes You're paying for: - Hosted infrastructure (database, CDN, edge compute) - TLS certificates and custom domain provisioning - Storage and bandwidth - AI inference (your monthly credit bucket) - Product development - Support You're *not* paying for: - Per-seat fees - "Premium support" tiers - Locked features at higher AI usage caps (top-ups are linear, not artificially gated) ## Where next How AI usage and credits work. What happens at day 14. ### AI credits URL: https://docs.dokly.co/account/ai-credits Summary: How AI usage is metered, what your monthly bucket covers, and how top-ups work. Every AI action in Dokly — inline edits, page generation, site generation — costs credits. Each plan includes a monthly credit bucket. If you run out, you can top up. ## How credits work - Credits are denominated in roughly "small-AI-action" units. - Each plan includes a fixed monthly bucket that resets on your billing date. - Unused credits don't roll over. - When you run an action, credits are reserved upfront and refunded if the action fails. ## Monthly buckets | Plan | Monthly credits | Approximate usage | |---|---|---| | Free | 50 | A handful of inline edits per month | | Starter | 500 | ~10 generated pages or 200 inline edits | | Pro | 2,500 | ~50 generated pages or 1,000 inline edits | | Scale | 10,000 | A small docs team's worth of generation | | Enterprise | Custom or BYOK | See below | These are working numbers — actual cost varies by input/output length. ## Action costs Approximate cost per action: | Action | Credits | |---|---| | Inline edit (improve, expand, fix grammar, etc.) | 1–3 | | Continue writing | 2–5 | | Translate a paragraph | 3–8 | | Generate single page | 20–50 | | Generate site (10 pages) | 200–500 | | Generate site (30 pages) | 600–1,500 | The editor shows the cost preview before you confirm any large action. ## Where to see your usage **Settings → Account → AI usage** shows: - Current month's bucket and remaining - Daily usage chart for the past 30 days - Recent actions (per-action cost log) screenshot of the AI usage panel showing the bucket meter, daily chart, and recent actions log ## Topping up If you exhaust your monthly bucket, the editor shows a "Top up" prompt instead of running the action. Top-ups are linear — pay for what you need, no minimums. Approximate top-up pricing: | Top-up | Price | |---|---| | 500 credits | $5 | | 2,500 credits | $20 | | 10,000 credits | $70 | Top-ups are added to your current bucket and don't expire until the next billing reset. ## Why we meter AI separately Two reasons: 1. **AI is expensive.** A power user generating 100 pages a month would otherwise drag down everyone else's plan price. Metering lets light users pay light prices. 2. **It's transparent.** You see what AI costs, not what we wrap and resell. If you want to compare to running raw API calls, you can. ## BYOK (Bring Your Own Key) On the Enterprise plan, you can connect your own Anthropic API key. AI actions then bill against your Anthropic account directly, and your Dokly bill drops the AI metering line item. BYOK is enterprise-only because: - It needs key management infrastructure (encryption, rotation, scoping). - Most users don't have an Anthropic account or want to manage one. - For smaller usage, our pooled allocation is cheaper than a direct AnthropicAPI bill. If you're a Free / Starter / Pro customer with high AI usage, the right move is usually a top-up or moving to Scale, not BYOK. ## Refunds and failures If an AI action fails (network error, model timeout, validation error), the credits are refunded automatically. You can verify in the recent actions log — failed actions show with a strikethrough and "refunded" tag. If you ever see a charge for an action that didn't run, file an issue and we'll refund manually. ## Where next The inline AI menu. Page and site generation. ### Trial URL: https://docs.dokly.co/account/trial Summary: Every new account gets 14 days of Pro features automatically. Here's what's included and what happens at day 14. When you sign up, your account is in **Pro trial mode** for 14 days. Every Pro feature is unlocked. No card required. After 14 days, you drop to the Free plan unless you've upgraded. ## What's unlocked during trial Everything Pro includes: - Unlimited pages per project (10 projects max) - Custom domain - Search - Analytics - API Playground and OpenAPI import - AI generation (with the Pro credit bucket) - Custom CSS - Remove "Powered by Dokly" badge - 2 GB image storage The trial is **functionally identical to a paid Pro subscription**. The intent is to let you evaluate the actual product, not a stripped version. ## How to see your trial status **Settings → Account → Plan** shows: - Current effective plan (e.g., "Pro — Trial") - Days remaining in trial - What changes at day 14 The dashboard also shows a small banner with days remaining once you're under 7 days. screenshot of the dashboard banner showing "5 days left in your Pro trial" with an Upgrade button ## What happens at day 14 If you haven't upgraded: - Your plan changes to **Free**. - Pro features become unavailable in the editor (e.g., AI generation, OpenAPI import, custom domain). - Your existing data is **not deleted**: - Pages over the new 5-page limit are **hidden** from the live site, not removed from the database. - Custom domains are detached but the configuration is preserved. - The "Powered by Dokly" badge reappears on your published site. If you upgrade later, hidden pages return automatically and custom domains can be reattached with one click. ## Can I extend the trial? Reach out at [hello@dokly.co](mailto:hello@dokly.co) before your trial ends. We're flexible — if you're mid-evaluation and need another week, that's fine. We'd rather you make the right decision than rush it. ## Can I trial again on a new account? Trials are per-account, not per-email. Creating a second account to get another trial isn't supported and is likely to get both accounts flagged. ## What if I just want to use Free? Totally fine. Sign up, ignore the trial features, and when day 14 hits you'll be on Free with no surprise. You can always upgrade later if your needs grow. ## Annual upgrade discount If you decide to upgrade before the trial ends, picking annual saves you ~17% (2 months free). This is the same discount available outside the trial — there's no special trial-conversion offer. ## What we recommend Use the trial for what it's for: build a real docs site. Pick a project that matters, write 10–20 pages, ship it on a custom domain, watch the analytics for a few days. By the end of two weeks, you'll know whether Pro is worth $49 a month for you. If you're not sure, downgrade and stay on Free. Come back to Pro when you have a clearer use case. ## Where next What each plan includes. How AI usage is metered. ## Reference URL: https://docs.dokly.co/reference Summary: Pages under Reference. Everything in this section. Title, slug, description, and SEO controls — set per page in the editor. How to move docs from Mintlify, GitBook, Docusaurus, ReadMe, or Notion into Dokly. Editor and formatting shortcuts wired into Dokly. Recent changes to Dokly. Newest first. Common questions about Dokly — pricing, limits, migrations, and how it works. ### Page settings URL: https://docs.dokly.co/reference/page-settings Summary: Title, slug, description, and SEO controls — set per page in the editor. Every page in Dokly has a small set of settings: a title, a URL slug, a description, where it sits in the sidebar, and a few SEO controls. You set them in the editor's page settings panel — there's no config file to edit and no syntax to remember. screenshot of the page settings panel open on the right side of the editor, showing title / slug / description fields ## Required: Title and Slug | Setting | Description | |---|---| | **Title** | Shown in the sidebar, the browser tab, and as the page's H1. | | **Slug** | The URL path. Example: a slug of `editor/writing` lives at `/editor/writing` on your site. | A page can't be saved without these. ## Description A short summary of the page. Used as: - The meta description (what shows up under the page title in Google). - The sidebar subtitle in the dashboard tree. - The default snippet in social previews. Keep it under ~160 characters. Write it for a human skimming search results. ## Sidebar placement | Setting | Description | |---|---| | **Parent** | Pick a page to nest this one under. The sidebar mirrors the tree. | | **Order** | Position within siblings — lower numbers appear higher in the sidebar. | | **Sidebar title** | Optional override of how the page name appears in the sidebar (use when the full title is too long). | You can also reorder pages by dragging them in the page tree — you don't have to manually edit the order. ## Publish state | Setting | Description | |---|---| | **Draft / Published** | Drafts are visible only in the dashboard. Published pages are live on your public site. | New pages default to draft. Flip to published when you're ready to ship. ## SEO controls | Setting | Description | |---|---| | **SEO title** | Override the `` tag used by search engines and browser tabs. Defaults to your page title. | | **SEO description** | Override the meta description. Defaults to your page description. | | **Social image** | Custom Open Graph image (1200×630). If empty, Dokly auto-generates one from your title and theme. | | **Noindex** | Tell search engines not to index this page. Useful for legal pages, internal references, and duplicate content. | | **Hide from search** | Page is still public via direct URL but excluded from your in-product search index. | | **Hide from sidebar** | Page is published at its URL but doesn't appear in the sidebar. Useful for footer-linked legal pages. | ## The homepage The page with slug `index` is your project's homepage — served at `/`. Every project should have one. If you don't, the homepage shows "No content yet" until you do. ## Slug rules - Lowercase letters, numbers, hyphens, and forward slashes only - No leading or trailing slashes - No spaces, no underscores, no special characters - Slashes create URL hierarchy (e.g., `editor/writing` → `/editor/writing`) The editor enforces these on input. ## Where next How the page tree maps to your sidebar. Sitemaps, social images, and search rankings. ### Migration URL: https://docs.dokly.co/reference/migration Summary: How to move docs from Mintlify, GitBook, Docusaurus, ReadMe, or Notion into Dokly. If you have docs somewhere else, you can move them. The shortest path: get your existing content out as Markdown, then paste it into a new page in the Dokly editor — Markdown converts to blocks automatically. This page covers the common sources. If yours isn't listed, the general approach at the bottom applies. ## The shape of every migration Most platforms have an export option. Aim for one Markdown file per page. In your project's page tree, click **New page** and pick a title and slug. Paste the body into the editor. Markdown — headings, lists, links, code blocks, blockquotes — converts to blocks as it lands. Anything your old platform did with custom syntax (admonitions, tabs, callouts) won't auto-convert. Insert the Dokly equivalent from the slash menu — see the mappings below for each source. Open the page settings panel and fill in description, parent, and SEO fields. See [Page settings](/reference/page-settings). ## From Mintlify Mintlify stores pages as Markdown files in a Git repo. Migration is mostly copy-paste plus a few component swaps. | Mintlify | Dokly equivalent | |---|---| | `` | Info Callout | | `` | Warning Callout | | `` | Tip Callout | | `` | Info Callout | | `` | Tabs | | `` | Plain image (Dokly auto-frames images) | | ``, `` | Card, Card Group (same names) | | ``, `` | Steps, Tabs (same names) | For Mintlify-specific frontmatter (`mode: wide`, `sidebarTitle`, `iconType`): - `sidebarTitle` → set the sidebar title field in page settings. - `mode: wide` → not yet supported (pages are responsive by default). - `icon` on a card → keep it; Dokly accepts the same icon names. ## From GitBook GitBook exports Markdown via Settings → Export. The output is a zip of `.md` files mirroring your sidebar tree. Replace these GitBook constructs: | GitBook | Dokly equivalent | |---|---| | `{% hint style="info" %}` | Info Callout | | `{% hint style="warning" %}` | Warning Callout | | `{% tabs %}` | Tabs | | `{% code-group %}` | Tabs | GitBook exports don't include slugs. Generate one per page based on its path and set it in page settings. ## From Docusaurus Docusaurus pages are Markdown in a `docs/` folder. | Docusaurus | Dokly equivalent | |---|---| | `:::tip ... :::` | Tip Callout | | `:::warning ... :::` | Warning Callout | | `` with `` | Tabs | | Custom imported components | Pick the closest Dokly block; complex widgets may need a rewrite | Docusaurus's `sidebar_position` becomes the **Order** field in page settings. `sidebar_label` becomes **Sidebar title**. `slug` works the same way. If your Docusaurus pages have `import` statements at the top, drop them — Dokly's blocks are available everywhere. ## From ReadMe ReadMe doesn't expose Markdown directly. Two options: 1. **Manual rewrite.** For small docs (under ~30 pages), the fastest path is to read each ReadMe page and rewrite it in Dokly. You'll improve a lot of pages along the way. 2. **HTML scrape + cleanup.** For larger docs, scrape the rendered HTML and convert to Markdown with a tool like Pandoc, then paste each page in. Plan for significant cleanup — automated conversion produces ugly Markdown. ReadMe Recipes don't have a direct equivalent — convert them to a Steps block with code blocks inside. ## From Notion Notion exports as Markdown via Workspace Settings → Export. The output is messy — Notion's blocks don't map cleanly. The realistic path: 1. Export to Markdown. 2. Use the export as a raw source you'll edit heavily. 3. Or use **Generate with AI** in Dokly with the exported text as the brief, and let it produce a cleaner first draft you can refine. You'll spend less time on a half-broken automated conversion than on a clean rewrite. ## General approach For any source not listed: 1. Get your content out as Markdown or HTML (one file per page). 2. Convert HTML to Markdown if needed (Pandoc, Turndown). 3. Paste each page into a new Dokly page. 4. Replace platform-specific syntax with Dokly blocks via the slash menu. 5. Set title, slug, description, and sidebar placement in page settings. For 50+ page migrations, talk to us — we can sometimes provide a one-off importer or do the migration as a paid service. ## After migration Run through the [SEO checklist](/site/seo) to make sure: - Slugs match the URL patterns from your old site (preserves SEO rankings). - Set up redirects from old paths to new paths if slugs changed. - Submit the new sitemap to Google Search Console. - Update any external links pointing at the old docs. ## Where next How to organize the migrated pages. Preserve search rankings during the move. ### Keyboard shortcuts URL: https://docs.dokly.co/reference/keyboard-shortcuts Summary: Editor and formatting shortcuts wired into Dokly. Shortcuts shown for Mac. On Windows/Linux, replace `⌘` with `Ctrl`. ## Block actions | Shortcut | Action | |---|---| | `/` | Open the slash menu | | `⌘D` | Duplicate the selected block | | `⌘⌫` | Delete the selected block | | `⌘↵` | Confirm/exit a block (e.g., escape a code block) | | `Tab` | Indent (in lists) | | `⇧Tab` | Outdent (in lists) | ## Markdown shortcuts Type these at the start of a new line and press space — the block transforms. | Shortcut | Block | |---|---| | `# ` | Heading 1 | | `## ` | Heading 2 | | `### ` | Heading 3 | | `> ` | Blockquote | | `- ` | Bullet list | | `1. ` | Ordered list | | `- [ ] ` | Task list | | ` ``` ` | Code block (then pick a language) | | `---` | Horizontal divider | ## Text formatting | Shortcut | Action | |---|---| | `⌘B` | Bold | | `⌘I` | Italic | | `⌘Z` | Undo | | `⌘⇧Z` | Redo | ## AI | Shortcut | Action | |---|---| | `⌘K` | Open the AI menu (with text selected) | ## Saving | Shortcut | Action | |---|---| | `⌘S` | Save the current page | Autosave runs in the background — you almost never need to think about Save. ## Where next Every block insertable with `/`. Tour of the editor. ### Changelog URL: https://docs.dokly.co/reference/changelog Summary: Recent changes to Dokly. Newest first. This is the public changelog. We ship most weeks; major changes get a dedicated entry, smaller ones get rolled up. For real-time updates, follow [@dokly_co](https://x.com/dokly_co) on X. keep this changelog updated as features ship — the dates and entries below are templates to replace ## 2026 ### v1.4 — May 2026 **New** - **Site generation** — generate a full docs site outline from a 2–3 sentence product description. Available on Pro+. - **OpenAPI 3.1 support** — full nullable + JSON Schema 2020-12 compatibility. - **Search analytics** — see what readers searched for, and what returned no results. Pro+. **Improved** - Editor performance: large pages (5,000+ words) load 3× faster. - Dark mode color tuning across all components. **Fixed** - Custom domain verification no longer stalls if a Cloudflare proxy is enabled mid-verification. - API Playground correctly handles `application/x-www-form-urlencoded` request bodies. - Long page titles wrap correctly in the sidebar instead of truncating mid-word. ### v1.3 — April 2026 **New** - **AI inline actions** — improve, expand, summarize, fix grammar, translate. ⌘K to open. - **FAQ component** — collapsible Q&A blocks with auto FAQPage schema. - **Badge component** — small inline labels for plan-gating, beta tags, etc. **Improved** - 2× faster page load via response streaming on the published site. - Better error messages when OpenAPI imports fail. ### v1.2 — March 2026 **New** - Auto-generated `llms.txt` and `llms-full.txt` for AI crawlers. - IndexNow integration — pings Bing/Yandex on every publish. - Custom OG image per page (Pro+). **Improved** - New default Open Graph image template — cleaner, more legible at small sizes. ### v1.1 — February 2026 **New** - Custom domains on Pro plans, with auto-issued Let's Encrypt certs. - Image storage tiers: 500 MB / 2 GB / 10 GB by plan. ### v1.0 — January 2026 Initial public launch. Core features: - Browser-based block editor with slash menu and live preview. - Multi-tenant subdomains (`*.dokly.co`). - Components: Callout, Tabs, Steps, Card, Card Group, Code Block, API Playground, Image. - Fuzzy search, dark mode, sitemap, robots.txt. - OpenAPI 3.0 import for API references. - Free / Starter / Pro pricing. ## Subscribing to updates There's no email list for the changelog yet. The best ways to stay current: - Follow [@dokly_co](https://x.com/dokly_co) on X. - Watch [the GitHub repo](https://github.com/dokly/dokly) for releases (if/when public). - Bookmark this page. ## Where next What we're building next. Request a feature or report a bug. ### FAQ URL: https://docs.dokly.co/reference/faq Summary: Common questions about Dokly — pricing, limits, migrations, and how it works. If your question isn't here, [reach out](https://dokly.co/contact) and we'll either answer or add it to this page. ## Account and pricing Yes. The Free plan includes 1 project with up to 5 pages, on a `*.dokly.co` subdomain. No card required. Every new account also gets a 14-day Pro trial unlocking all paid features. When you sign up, your account is on Pro for 14 days automatically. After 14 days you drop to Free unless you upgrade. Your data is preserved either way — pages over the Free limit are hidden, not deleted. No. Pricing is plan-based. Free, Starter, and Pro are single-seat. The Scale plan ($99/mo) includes 5 team members; additional seats are $10/mo each. Yes — annual saves ~17% (2 months free). Toggle on the [pricing page](https://dokly.co/pricing) or in Settings → Billing. Your subscription continues to the end of your billing period, then your account drops to Free. Your data is preserved. You can resubscribe anytime. ## Editor and content It's a block editor. Each chunk of content — paragraph, heading, callout, code block — is a block you insert from the slash menu and configure visually. Markdown shortcuts (typing `# ` for a heading, `> ` for a quote) transform into blocks as you type, but you never edit raw syntax. You can use Markdown shortcuts as you type (`# `, `**bold**`, ` ``` `, etc.) — they transform into the matching blocks. You can also paste Markdown and it converts to blocks automatically. Yes. See [Migration](/reference/migration) for guides specific to Mintlify, GitBook, Docusaurus, ReadMe, and Notion. Not yet. Dokly is browser-only today. A CLI for bulk import / export is on the roadmap. Not on Free / Starter / Pro / Scale — you're limited to the built-in block set, which keeps your docs consistent. Enterprise plans can whitelist additions. ## Hosting and domains On Dokly's infrastructure. Pages are rendered with Next.js ISR and cached at the edge. You don't manage servers. Yes — on Pro plans and above. Add a CNAME at your DNS provider, Dokly issues a TLS cert automatically. See [Custom domain](/customization/custom-domain). Supported but discouraged. Most DNS providers don't allow CNAMEs on apex; you'd need ALIAS/ANAME records or Cloudflare's CNAME flattening. Subdomains route more cleanly. Not currently. Dokly is a SaaS product. If you have a hard self-hosting requirement (compliance, air-gapped environment), reach out about Enterprise options. ## Search and SEO Yes — `⌘K` opens fuzzy search across your docs. Available on Starter and above. No setup needed. Yes — sitemaps, meta tags, OG images, structured data, and llms.txt are all auto-generated. See [SEO](/site/seo). Dokly auto-generates `llms.txt` and `llms-full.txt` at the root of your domain, which AI crawlers use to find and cite your docs. Nothing to configure. ## AI Inline actions (improve, expand, fix grammar, translate) and full-page or full-site generation from a brief. See [AI actions](/editor/ai-actions) and [Generate with AI](/editor/generate-with-ai). Claude (Anthropic). We pick the best model for each action — small fast models for inline edits, larger models for full-page generation. Only on the Enterprise plan. On Free / Starter / Pro / Scale, AI runs on Dokly's allocation and counts against your monthly credit bucket. No. Prompts and outputs are sent to Anthropic with zero-retention settings and not used for training. ## Data and privacy On Dokly's managed infrastructure. Pages, projects, and uploaded images are stored on Dokly's hosted backend — you don't manage servers, databases, or buckets. Reach out and we'll work with you on a clean export. We don't believe in data lock-in — if you decide to leave, we'll help you take your content with you. Yes. No identity tracking, no fingerprinting, no third-party cookies, no IP retention. GDPR-compliant out of the box. Not yet. SOC 2 Type II is in progress for late 2026. Enterprise customers requiring it should reach out to discuss timeline. ## Where next The quickstart. Question not answered here? Reach out.