Troubleshooting

pnpm issues

Approve build scripts

If you encounter build or dev errors when using pnpm, especially related to better-sqlite3, you may need to approve certain packages for building.

Run the following command and select better-sqlite3 and sharp from the list:

Terminal

pnpm approve-builds

Enable shameful hoisting

If you see errors like Can't resolve 'tailwindcss' or similar resolution failures, apply a flat node_modules layout by creating a .npmrc file:

.npmrc

shamefully-hoist=true

My site starts, but the landing page is missing

Docd treats content/index.md as the landing page only when you do not provide your own app/pages/index.vue.

Check for these cases:

• content/index.md is missing
• you created app/pages/index.vue, which overrides the content-based landing page
• the file exists but is outside the project's content/ directory

If you want the Markdown landing page, keep:

content/
└── index.md

If you want a custom Vue landing page, add:

app/pages/index.vue

That behavior is intentional.

My docs are appearing at /docs/... unexpectedly

Docd checks whether a content/docs/ folder exists.

If it does, documentation pages are mounted under /docs.

For example:

content/
├── index.md
└── docs/
    └── getting-started.md

This produces:

• / for index.md
• /docs/getting-started for docs/getting-started.md

If you want routes like /getting-started instead, move the files out of the docs/ subfolder and place them directly under content/.

Frontmatter dates are failing validation

Docd's content schema expects publishedAt and modifiedAt to be valid ISO timestamps.

publishedAt: 2026-04-24
modifiedAt: 2026-04-24

Avoid vague or inconsistent formats if you want predictable parsing and sorting behavior.

My Markdown component is not rendering

When using components in Markdown content:

• component names should be lowercase and kebab-case
• only globally available components can be used

For example:

::prose-card{title="Example" description="Rendered from MDC"}
::

If a component does not render, check:

• the component name is correct
• the props use valid MDC syntax
• the component is globally available

The content page exists, but navigation looks wrong

Navigation is generated from your content structure and frontmatter.

Check these first:

• the page has a title
• navigation is not set to false unless you want it hidden
• the file is inside the expected content tree

If a page is intentionally hidden from navigation, this is valid:

navigation: false

create-docd fails while initializing a project

If initialization fails, common causes are:

• network access to GitHub is blocked
• the destination directory already exists and is not empty
• your local Node or package manager setup is incomplete

Try again in a fresh empty directory:

The MCP server is not available

Docd exposes its built-in MCP server at /mcp.

If it is not available:

• make sure the site is actually running
• make sure the app extends docd
• confirm the deployment includes the layer's server files
• verify that MCP has not been disabled in Nuxt configuration

In local development, the URL is usually:

http://localhost:3000/mcp

My sitemap, canonical links, or llms.txt point at localhost

Docd needs to know your public URL to build absolute links. It looks for site.url in nuxt.config.ts, then for environment variables such as NUXT_SITE_URL. If it finds neither, production builds log No site URL configured, and llms.txt falls back to http://localhost:3000.

Set the URL in nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  site: {
    url: "https://docs.example.com",
  },
});

Or provide it when you build:

NUXT_SITE_URL=https://docs.example.com

I changed content, but the page still looks stale

Try the usual Nuxt cleanup steps:

1. Stop the dev server
2. Remove generated caches if needed
3. Restart the dev server

Still stuck?

When debugging a Docd issue, reduce it to these questions:

1. Is this a content problem, a layer problem, or a consumer-app override?
2. Is the file in the right directory?
3. Is the route affected by content/index.md, content/docs/, or app/pages/index.vue?
4. Is the frontmatter valid for the collection schema?

Most Docd issues fall into one of those buckets.