Markdrop Guides FAQ and troubleshooting

What's the difference between Markdrop Guides and the Markdrop docs?

Markdrop Guides, at markdrop.in/guides, is where you build guides for your own product. The Markdrop docs, at docs.markdrop.in, are Markdrop's own documentation: the site you're reading. The pages in its Markdrop Guides tab explain the product; everything else here is about Markdrop's documents, files, sharing and workspaces.

What does it cost?

Markdrop Guides is free while it's in beta. During the beta there are limits on how many guides a workspace can have and how much each guide can do; when you reach one, the app tells you.

Do my readers need an account?

No. Every published guide is public and opens in any browser. Password-protected and members-only guides are coming soon.

Can I keep my guide out of search engines?

Yes. Turn off Let search engines index the guide in Settings and publish. The guide stays public for anyone with the link, but asks search engines not to index it.

Can readers ask questions about my guide?

Yes, with Ask AI. Turn it on in Settings and publish: readers get answers from your published pages, with links to the sections they came from. Each guide has a monthly number of answers during the beta.

Can I generate an API reference from an OpenAPI file?

Yes. Upload an OpenAPI 3.0 or 3.1 file, or give its address, in Settings › API reference and publish: every endpoint gets a page with code samples and Try it. See API reference from an OpenAPI file.

Can I use my own domain?

Yes. Add a subdomain such as help.acme.com under Settings › Your own domain, then add one CNAME record at your DNS provider. The certificate is handled for you, and the free <address>.guides.markdrop.in address keeps working. See Use your own domain.

Can I keep my pages in Git?

GitHub sync is coming soon. Until then the editor's Markdown mode shows each page as a file, and the engine can be self-hosted from a folder.

Can I get my content out?

Every published page is available as Markdown at its address plus .md, and the whole guide is in /llms-full.txt. In the editor, Markdown mode shows each page's source.

• It hasn't been published. New guides are drafts: the home page card says Draft and the Publishes tab says Nothing is public until the first publish. Publish it.
• The publish is still running or failed. Check its row on the Publishes tab.
• It's waiting for a review. The card says In review. A reviewer or admin has to approve it.
• It was unpublished. The card says Unpublished. Publish again to put it back.
• You changed the address. The new address goes live with the next publish, and the old one stops working.

See When a domain doesn't go live. Most often the CNAME record has a typo, its name was doubled by the DNS provider, or another record already uses that name.

Saved drafts aren't public until you publish. The page tree marks pages with unpublished changes with a dot, and the Publishes tab lists every change since the last publish. Theme, Ask AI, redirect and sidebar changes also need a publish.

The publish is marked Failed with the reason, and readers keep the last live version. Common causes:

• "Add a page before publishing." The guide has no pages.
• The day's publishes are used up. Try again tomorrow (UTC), or restore an earlier publish, which doesn't count.
• "Password and members-only guides are coming soon." Set Who can read it back to Anyone in Settings.
• "This guide is too large to publish in one snapshot." Split very long pages.

If it fails again with the same reason, contact Markdrop using the address in the privacy policy, with the guide's address.

Your API doesn't allow requests from the guide's address (CORS), or it couldn't be reached. Allow your guide's address, like https://acme.guides.markdrop.in, in your API's Access-Control-Allow-Origin, along with the headers the request sends. Until then, readers can copy the request as a curl command. See Try it and CORS.

The card says why. The usual reasons: it's Swagger 2.0 (convert it to OpenAPI 3 first), it's larger than 5 MB or has more than 1,000 endpoints, or the address isn't a public https:// address. See the limits.

The import screen says The import stopped with the reason. Check that the address is the GitBook site's public address (https://…), that it opens in a private browser window, and that it's a GitBook site. Then choose Start again. A private GitBook space can't be imported.

That's what the report is for: check the report before you publish. Its rows link to each page.

Someone else has it open: the banner and the page tree show who. It opens for editing when they're done, or two minutes after they close their browser. A Guides admin can Take over. If the bar says View only, your role is Viewer: ask an admin for the Editor role.

Your Guides role there is No access, or a guide gives you No access. Workspace membership alone doesn't give access: a Guides admin of the workspace has to give you a role.

In a workspace, only Guides admins create guides. The workspace may also have its most guides for the beta: delete one to make room, or create a personal guide.

Save design, then publish. Custom CSS that has a problem can't be saved: the box says what's wrong. See Custom CSS.