docs: improve documentation build and upgrade guide #52634
Conversation
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
- Add detailed build verification steps - Document common build issues and solutions - Add framework upgrade guidelines - Improve broken link handling documentation Co-Authored-By: Aaron <AJ> Steers <[email protected]>
devin-ai-integration
bot
requested review from
ian-at-airbyte and
aaronsteers
🤖 Devin AI EngineerOriginal prompt from Aaron: I'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
⚙️ Control Options:
|
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
octavia-squidington-iii
added
area/documentation
|
|
||
| 1. **Broken Links and Anchors** | ||
| - Links must match the exact case of the target file/heading | ||
| - Anchors are generated from headings: spaces become hyphens, special characters are removed |
There was a problem hiding this comment.
This is true, but it's also possible to specify anchors manually. This is important when creating headings you want to link to from other places, because it prevents anchor links from breaking if a heading is rewritten later.
| 3. **Build Performance** | ||
| - First builds may take longer due to dependency installation | ||
| - Use `pnpm clear` before `pnpm build` to ensure a clean build | ||
| - The development server (`pnpm start`) may take 1-2 minutes to initially compile |
There was a problem hiding this comment.
This is not the right place for this information. This section is about production builds, but this information talks about a development build.
| - Use production builds to catch all link issues | ||
| - Fix the most critical navigation paths first | ||
| - Update internal cross-references systematically | ||
| - Consider adding redirects for moved content |
There was a problem hiding this comment.
Clarify that this is done with the redirects.yaml file.
| 2. **Resolution Steps** | ||
| - Use production builds to catch all link issues | ||
| - Fix the most critical navigation paths first | ||
| - Update internal cross-references systematically |
There was a problem hiding this comment.
What do you mean by this?
|
|
||
| 3. **Prevention** | ||
| - Test links in both development and production builds | ||
| - Use relative paths for internal documentation |
There was a problem hiding this comment.
I think you mean: use relative paths when linking to content within the site. This is not internal documentation.
| - Test links in both development and production builds | ||
| - Use relative paths for internal documentation | ||
| - Follow consistent heading case conventions | ||
| - Document any intentionally external references |
There was a problem hiding this comment.
I don't think that's necessary. We can easily scan for these.
| 3. **Prevention** | ||
| - Test links in both development and production builds | ||
| - Use relative paths for internal documentation | ||
| - Follow consistent heading case conventions |
There was a problem hiding this comment.
This is incorrect. Firstly, this has nothing to do with preventing broken links. Secondly, follow the guidance in the Google Developers Style Guide, as this article already specifies.
| - Note any custom components or plugins that might be affected | ||
|
|
||
| 2. **During the Update** | ||
| - Update dependencies incrementally if possible |
There was a problem hiding this comment.
Generally, yeah this is good practice. But upgrading the core Docusaurus library and running pnpm install will update dependencies for you. You do not need to incrementally update anything with Docusaurus unless this is a complex, major, breaking change. This is incredibly rare and Docusaurus will issue guidance for this.
Description
This PR improves the documentation around building and upgrading the documentation site, based on recent experiences with the Docusaurus upgrade process. The changes include:
Type of Change
Link to Devin run
https://app.devin.ai/sessions/c0c18bdaabc246119ec3b36f8b67e751
Test Instructions
/docusaurusdirectorypnpm installpnpm clear && pnpm buildpnpm startand verify the development server worksDocumentation
This PR is a documentation improvement.