Troubleshooting and FAQ
Each heading below is a symptom or a question. Find yours, then read the cause and the fix.
Troubleshooting
A PDF gives empty or almost empty Markdown
The PDF is probably a scan: pictures of pages with no text layer. Markdrop reads the text layer and does not run OCR on PDFs. Run the PDF through an OCR tool first, or, on Android, take photos of the pages and convert those; the Android app reads text from photos.
The YouTube transcript is missing
- The video has no captions, so there is no transcript to fetch. The title and description still convert.
- Markdrop reads captions from YouTube's pages, which is not an official interface. If YouTube changes its pages, transcripts can stop working until Markdrop is updated.
The extension says This page cannot be converted
Browsers do not let extensions read some pages, such as chrome:// pages and the extension store. Open a normal web page and try again.
Article mode leaves out part of the page
Article keeps what it thinks is the main text. Use Full page to keep everything, or Pick element to choose the exact blocks.
The Firefox add-on is gone after a restart
An add-on loaded from about:debugging is temporary and is removed when Firefox closes. Load it again, or install it from addons.mozilla.org once it is listed.
Convert link target says to set the endpoint
Convert link target to Markdown (via API) needs your own Markdrop Web server. Enter its address in the extension's Options under Conversion API endpoint (optional), and the key under API key (optional) if you set one.
Markdrop Studio shows engine error
The built-in conversion engine did not start. Reinstall the package for your architecture: an amd64 package will not run on an arm64 machine, or the other way round. If it still fails, start markdrop from a terminal and include its output in an issue.
The Studio package will not install on my distribution
The packages are built on Ubuntu 24.04 and need a system at least as new: Fedora 39 or newer, openSUSE Tumbleweed or current Arch. RHEL 9 and openSUSE Leap 15 are too old. Use the Flatpak, which brings its own runtime.
A PowerPoint file fails on my Android phone
Some of the newest phones use 16 KB memory pages, and the PowerPoint converter does not work on them yet. The app shows a message when this happens. Convert the file with Markdrop Studio instead.
The web API returns 401
The server has MD_API_KEY set, and your request has no X-API-Key header or the wrong value.
The web API refuses my URL
The server blocks links to private and local network addresses, so it cannot be used to reach machines on an internal network. For local testing only, start it with MD_ALLOW_PRIVATE_URLS turned on.
The bot says the file is too big
Telegram limits files that bots receive to 20 MB. Use the web page of your Markdrop Web server for larger files.
Questions
Which tool should I use?
| You want to | Use |
|---|---|
| Save web pages as you browse | Browser extension |
| Convert many PDFs or Office files on a Linux computer | Desktop app |
| Convert on your phone, or from photos | Android app |
| Convert from scripts or other programs | Web app and API |
| Convert by chatting in Telegram | Telegram bot |
| Have an MCP client convert files for you | MCP connector |
Are my files uploaded anywhere?
The extension, Markdrop Studio and the Android app convert on your own device. Markdrop Web, the bot and markdrop-mcp run on computers you control. Converting a URL or a YouTube video fetches it from that website. Files sent to the bot pass through Telegram.
Is there a Windows or macOS version of Markdrop Studio?
Not yet. Markdrop Studio is released for Linux on x86-64 and arm64.
Is the Android app in the Play Store?
No. Install the APK from the release page.
Can I turn off the front-matter?
In the extension, untick Include front-matter block (title / source / date) in Options.
Where do I report a problem?
Open an issue on the Markdrop issues page. Say which tool and version you use.