Last updated: March 2026
Task-based guides for the most common DocCraft workflows. Each guide is self-contained — follow the steps in order, and you'll have a working result by the final step.
Produce a complete, publishable API reference in under five minutes.
You need an OpenAPI 3.x specification in .yaml, .yml, or .json format. OpenAPI 2.x (Swagger) files work but produce less detailed output because Swagger lacks the schema depth of OAS 3.x. If you only have a Swagger file, consider upgrading it with the Swagger Editor before proceeding.
From the DocCraft Dashboard, click New Document. The input panel opens on the right side of the screen.
If you already have an open project, you can also click + New in the top navigation bar.
In the input panel, select the Upload tab. Drag your spec file into the upload zone, or click Browse to select it from disk.
DocCraft validates the file on upload. A green checkmark confirms the spec is valid. If validation fails, an error summary appears — the most common causes are an invalid YAML structure or unresolved $ref paths.
Specs with more than 150 endpoints take longer to process (typically 30–60 seconds). DocCraft handles large specs fully — it does not truncate or skip endpoints. If you're uploading a spec this size, keep the browser tab active during processing.
In the Document Type dropdown, select API Reference. This template generates:
info.description field in your specsecuritySchemes definitions4xx and 5xx response definitionsExpand Advanced options to adjust how DocCraft writes the output. For API references, these options are most relevant:
Generated code samples are syntactically correct and structurally accurate, but they use placeholder values for API keys and base URLs. Review the authentication section and replace placeholders before publishing.
Click Generate. Generation typically completes in 20–45 seconds for an average-size spec. The document opens in the editor when ready.
Review the output in this order:
info.description was sparse, DocCraft fills in context — verify it's correct.Click Export in the editor toolbar and choose your target format:
Your exported file downloads immediately. It is also saved to your project's Exports tab for 30 days.
A complete, publish-ready API reference with an overview, authentication guide, full endpoint reference, and multi-language code samples.
Produce a complete, well-structured README from a public GitHub repository.
The repository must be publicly accessible. Private repository support requires a GitHub OAuth connection under Settings → Integrations → GitHub. Repositories with at least some inline code comments, existing README text, or a package.json / pyproject.toml file produce better output.
Open a new document from the Dashboard. In the input panel, select the URL tab and paste the GitHub repository URL — for example, https://github.com/your-org/your-repo.
DocCraft reads the repository's file structure, README (if any), code files, and configuration files. It does not clone the repository — it reads via the GitHub API, which means it respects public/private access controls.
In the Document Type dropdown, select README. This generates a GitHub-convention README with the following sections:
package.json, requirements.txt, Gemfile, etc.)DocCraft generates badge markup using standard shields.io patterns. After generation, verify that badge URLs are accurate — particularly:
Replace any placeholder values in the badge block before publishing. Select the badge block in the editor and use Regenerate Section to ask DocCraft to update specific badges if you have additional information to provide.
Click Export → Markdown. The downloaded .md file is ready to replace or supplement your repository's existing README.md.
The exported README is a standalone file — it does not automatically update in the repository. Commit the file to your repo as you would any other markdown file. If you connected the GitHub integration, you can push the file directly from the Export panel using Export → Push to GitHub.
Revise a section of a generated document without regenerating the entire document.
You need an existing generated document open in the editor. This workflow applies to any document type — API references, READMEs, user guides, and admin guides all support section-level regeneration.
In the editor, click anywhere inside the section you want to regenerate. The section highlights with a subtle border — this is the active selection indicator. You can also select a section from the Outline panel on the left by clicking its name.
DocCraft treats the content between two headings as a single section. If you want to regenerate only a paragraph within a section, highlight that paragraph with your cursor instead.
With the section selected, click the Regenerate button in the editor toolbar (the circular arrow icon). The Regenerate panel slides in from the right side.
The panel shows the current section content and an instruction field. You can provide natural language instructions to guide the revision — for example:
Type your instructions in the field and click Apply Revision. DocCraft regenerates the selected section based on your instructions, preserving the surrounding document structure.
Regeneration for a single section typically completes in 5–15 seconds.
More specific instructions produce more predictable results. Vague instructions like "make this better" are less effective than targeted instructions like "shorten to two paragraphs and add a callout box noting the 60-second timeout limit". DocCraft works best when you describe the desired outcome, not just the quality judgment.
The regenerated section appears with a yellow highlight to indicate it's a pending revision. Review the change:
Accepted revisions are saved to the document immediately and included in the next export.
Connect DocCraft to your Confluence workspace and publish documentation directly.
You need a Confluence account with Create Page and Edit Page permissions on at least one space. If you're connecting to a company Confluence instance, confirm with your administrator that API token access is permitted for your account.
In a separate browser tab, go to id.atlassian.com/manage-profile/security/api-tokens. Click Create API token, give it a label (such as "DocCraft integration"), and copy the token value.
Atlassian shows the API token value only once. Copy it before closing the dialog. If you lose it, you must revoke the token and generate a new one.
In DocCraft, go to Settings → Integrations → Confluence. Fill in the three required fields:
https://yourorg.atlassian.net. Do not include a trailing slash or a space path.Click Test connection. DocCraft makes a test call to the Confluence API to verify the credentials. A green success message confirms the connection is working.
Open the document you want to publish in the editor. Click Export → Publish to Confluence. A dialog prompts you to select:
Click Publish. DocCraft converts the document to Confluence storage format and creates the page. A confirmation message with a direct link to the new Confluence page confirms success.
If you publish to a space and parent page where a page with the same title already exists, DocCraft creates a new version of that page — it does not create a duplicate. Confluence's version history tracks the previous versions. To publish to a specific existing page by ID instead of title, use the Page ID option in the advanced publish settings.
Restructure an existing document to match a preset template — without regenerating from source.
Templates are useful when you need documentation to conform to an internal style guide — for example, when all your API references must start with an overview, follow a specific authentication section format, and end with a support contact block. Templates enforce structure without changing the generated content.
With a document open in the editor, click Templates in the toolbar (the grid icon). The template browser opens in a side panel.
Templates are organized by document type — API Reference, README, User Guide, Admin Guide, and Release Notes. There are also industry-specific templates (for example, Financial API Reference or Healthcare Integration Guide) that include compliance callout sections.
Click any template to preview its section structure and a sample rendering. The preview shows the section order, default callout positions, and example content blocks so you can compare it to your current document structure before applying it.
If you have custom templates saved in your team's Template Library, they appear at the top of the list marked with a team badge.
Click Apply template. DocCraft maps your existing document sections to the template structure:
DocCraft saves a snapshot of your document before applying a template. If the result isn't what you expected, click Undo template in the toolbar to restore the previous structure. Undo is available until you navigate away from the document or export it.
Trigger automatic documentation generation every time code is pushed.
Add DOCCRAFT_WEBHOOK_SECRET to your Vercel environment variables (or .env.local for local development). This secret authenticates incoming webhook requests.
In your GitHub Actions workflow (or any CI tool), add a step that posts to the webhook endpoint after a successful build or push:
The webhook returns a JSON response containing the generated document, repo metadata, and source file list. Optionally include "publishToGithub": true with a githubToken to auto-commit the output back to the repository.
See exactly what changed between your original draft and the current version.
Before making edits, click Save Snapshot in the editor toolbar. This saves the current state so you can compare against it later. The initial generation baseline is always available automatically.
Click the Version Diff button (GitCompare icon) in the editor toolbar. A side-by-side comparison panel appears below the editor.
Use the dropdown to choose any saved version — the original baseline or any snapshot. The diff highlights added lines (green), removed lines (red), and changed lines (amber). A badge shows the total number of changed lines.
Create your own governance checks beyond the built-in MSTP compliance.
In the Document Editor, click the Custom Rules button (ShieldPlus icon) in the toolbar.
Fill in the rule fields:
Click Add Rule. Rules are saved in your browser and persist across sessions.
Click the Compliance Check button (ShieldCheck icon). Your custom rules are applied alongside the built-in MSTP checks. Results show each issue with its severity and the line where it was found.