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: