Skip to content

FAQ

Jump to bottom
GitHub Copilot edited this page May 12, 2026 · 1 revision

FAQ & Troubleshooting

General

Is mdedit.io free?

Yes. The live app at mdedit.io is free and requires no account. The source code is open under Apache 2.0 — self-hosting is free and permitted.

Do I need an account?

No. Open the editor and start writing. Your documents are stored in the browser session.

Are my documents private?

Yes by default. Documents are stored server-side and tied to your session cookie. Only documents you explicitly share (via the Share menu) are publicly accessible via permalink.

Does the app work offline?

No — the editor requires a server connection (either the live app or your own Docker instance).

PDF Export

PDF export is slow or hangs

PDF export uses Pandoc with either XeLaTeX or paged.js. This is a heavyweight process. Allow 10–30 seconds for complex documents.

If it times out repeatedly:

  • Check that the Docker container has enough RAM (PDF export uses ~500 MB per job)
  • Reduce MAX_CONCURRENT_EXPORTS in .env if running on a low-resource server
  • Check server logs: docker compose logs -f

The PDF layout looks wrong

Make sure you have a preset set in your YAML front matter:

---
preset: scientific
---

Without a preset, the default layout is used. See Layout Presets for all options.

Math / Mermaid diagrams don't appear in PDF

  • KaTeX and Mermaid rendering depend on Chromium being available in the container
  • Check if CHROMIUM_BIN is set correctly in .env, or leave it unset for auto-detection
  • Run the smoke test to confirm: docker compose exec -T md-tree env CHROMIUM_BIN=/usr/bin/chromium node scripts/visual-smoke.js

AI Assistant

The AI panel is not responding

  1. Check that you have set a valid API key in .env (e.g. GROQ_API_KEY)
  2. Restart the container: docker compose up -d --force-recreate
  3. Check logs: docker compose logs -f
  4. Verify the key is valid at the provider's dashboard (console.groq.com, platform.openai.com)

Which AI provider should I use?

Start with Groq — it has a free developer tier and fast inference. See AI API Configuration for all supported providers.

Alt+Space doesn't open the AI panel

On some Linux desktop environments, Alt+Space is reserved for the window manager. Use Ctrl+Space as an equivalent fallback.

Docker & Self-Hosting

Port 3210 is already in use

Change the port mapping in docker-compose.yml:

ports:
  - "3211:3210"  # use 3211 on the host

Container starts but app is not reachable

docker compose ps          # check container status
docker compose logs -f     # check for startup errors
curl http://localhost:3210/health

Data is lost after restarting the container

Make sure the ./data directory is mounted as a volume in docker-compose.yml:

volumes:
  - ./data:/app/data

How do I update to the latest version?

git pull origin main
docker compose build
docker compose up -d --force-recreate

Citations

Citations are not rendered in the PDF

Make sure your front matter includes:

---
citation-source: embedded
---

And that your document contains a valid mdedit-bibliography code block. See Citations and References for the full setup.

Reference list is missing

Add reference-section-title to your front matter:

---
reference-section-title: References
---

Reporting Issues

If none of the above helps, please open an issue at the GitHub issue tracker. Include:

  • The exact error message or behavior
  • Browser and OS
  • Docker version and container logs if self-hosting

See Also

Clone this wiki locally