Troubleshooting

Solutions for common issues.

Build Errors

“Config file not found”

Docyard requires a docyard.yml file in your project root.

Initialize a new project

docyard init

Or create the file manually

touch docyard.yml

Add minimum required config

    
    docyard.yml
    
title: My Docs

“Unknown configuration key”

Check for typos in your docyard.yml. The error message will show the invalid key and suggest similar valid options.

Build fails silently

Enable verbose output to see detailed error messages:

docyard build -v

Development Server

Port already in use

Another process is using the port.

docyard serve -p 3000

Note

Hot reload uses a separate port (main port + 1). When serving on port 4200, ensure port 4201 is also available.

Hot reload not working

Check that you're editing files in the `docs/` directory

Ensure the file has a supported extension

.md - Markdown files
.yml - Sidebar configuration
.css - Stylesheets
.js - JavaScript

Try restarting the server

# Stop with Ctrl+C, then restart
docyard serve

Changes not appearing

Clear your browser cache with a hard refresh:

Cmd + Shift + R

Search

Search not working in development

Search is disabled by default during development to speed up startup.

docyard serve --search

Note

This generates a search index at startup, which adds a few seconds to the initial load.

Search shows no results

Check pages aren't excluded in config

    
    docyard.yml
    
search:
   exclude:
      - "/draft-*"  # Make sure this isn't matching your pages

Rebuild the search index

docyard build

With sidebar: config (default), pages must be explicitly listed in _sidebar.yml:

    
    docs/_sidebar.yml
    
- getting-started:
    items:
      - quickstart
      - my-new-page  # Add your page here

Tip

Use sidebar: auto to automatically generate the sidebar from your directory structure.

The sidebar follows the order in _sidebar.yml, not alphabetical or file system order. Reorder items in the YAML file to change the display order.

Styling

Custom styles not applying

Place CSS files in `docs/public/`

docs
- public
  - custom.css

Files are automatically included in the build - no import needed

Code blocks look broken

Check for unclosed fences. Each code block needs opening and closing backticks:

```javascript
// Your code here
```

Danger

Missing closing backticks will break rendering for the rest of the page.

Deployment

404 errors on refresh

Docyard generates static HTML for each page, so this usually isn’t needed. If you’re getting 404s:

Ensure all pages are built

docyard build --verbose

Check that your hosting serves `.html` files correctly

Assets not loading

Check your base URL matches your deployment:

    
    docyard.yml
    
build:
  base: https://docs.example.com

Warning

The base URL must exactly match your production URL, including the protocol (https://).

Images not displaying

Files in docs/public/ are copied to the root of your built site. Reference them with root-relative paths (not /public/...).

Place images in `docs/public/`

docs
- public
  - images
    - screenshot.png

Reference from root (not `/public/`)

![Screenshot](/images/screenshot.png)

Performance

Build is slow

For large sites (100+ pages), builds run in parallel automatically. If still slow:

Optimization tips

Optimize images - Compress before adding to docs/public/
Reduce includes - Each include adds processing overhead
Simplify nesting - Deeply nested components are slower to render

Page load is slow