Overview
This guide helps you identify and resolve common issues you might encounter while working with your documentation, such as broken links, missing search results, styling conflicts, and build errors.
Troubleshooting Common Issues
Resolving Broken Links and Missing Files
Broken links typically occur when a page URL changes, a file is moved or deleted, or an internal reference cannot be found in the project.
Tip
When referencing other pages within your project, make sure that relative paths point to valid files and that page names match your folder and file structure.
If you are using Obsidian-style links (Wikilinks), verify that target files and heading anchors exist. The system attempts to resolve links using relative paths, absolute paths, or alternative titles (aliases) specified in your frontmatter. If a link fails to resolve, a warning is logged in the console during the build process.
Fixing Missing Search Results
If search results do not appear or queries return empty results, check your search provider configuration and indexing setup.
- Verify Search Indexing: Ensure your build process or content synchronization script successfully generates and uploads search indexes. For cloud search providers like Orama Cloud or Algolia, check that your build script correctly parses and syncs your documents.
- Check API and Client Settings: Ensure your search client is initialized with the correct project credentials and API keys.
- Inspect Content Structure: Make sure your pages contain valid headings and body text so that content processors can properly extract and index searchable data.
Warning
If you change your project's data structure or content paths, remember to re-sync your search indexes so that stale URLs do not persist in your search database.
Resolving Build and Compilation Errors
Compilation errors happen when content files contain invalid syntax, missing frontmatter, or malformed components that the markdown compiler cannot process.
When a compilation error occurs, the system catches the exception and renders an error page displaying the error message and stack trace. Use the following steps to diagnose and fix build errors:
- Look at the error message displayed on the affected page or in your build terminal.
- Open the source file indicated by the error.
- Check for unclosed tags, invalid Markdown syntax, or missing variables in your content.
- Re-run your build or restart your development server to verify the fix.
Note
If a page cannot be found at all, a default 404 error page is displayed indicating that the requested page may have been removed, renamed, or is temporarily unavailable.