Troubleshooting

Start with doctor:

npx accept-md doctor

It reports detected framework paths, handler files, config, and version compatibility.

Why do Markdown requests return HTML?

Check that your request includes the header:

curl -sI -H "Accept: text/markdown" https://your-site.com/

If the response is still HTML, verify that rewrites, middleware, or SvelteKit hooks are active and that the route is included by accept-md.config.js.

Why does the handler return 404?

Confirm the generated handler exists in the expected location:

• App Router: app/api/accept-md/route.js or .ts
• Pages Router: pages/api/accept-md/index.js or .ts
• SvelteKit: src/routes/api/accept-md/[...path]/+server.js or .ts

JavaScript handler files are supported and should not be converted to TypeScript-only syntax.

Why does the Markdown include too much navigation?

Add selectors to cleanSelectors:

module.exports = {
  cleanSelectors: ["nav", "footer", ".cookie-banner", ".related-posts"],
};

Prefer removing layout chrome before conversion instead of cleaning large chunks of Markdown afterward.

Why does Next.js start fail after build?

Run:

npx accept-md fix-routes

If it fixes the issue, add it as a postbuild script.

What if CLI and runtime versions do not match?

Run:

npx accept-md version-check

If the CLI and accept-md-runtime differ, reinstall with the latest CLI:

npx --yes accept-md@latest init
pnpm install