How to elegantly upgrade a Fumadocs project

[fre2d0m]

I started using Fumadocs a few months ago, but before I could even get the documentation website ready, Fumadocs kept releasing new versions. I'm quite bothered by these version updates. Should I just use it directly in my project?
npm install fumadocs-<module>@<version> Is that all?

By the way, there are absolutely no meaningful notes in the releases. 😭

[fuma-nama]

except major releases, you can just see https://github.com/fuma-nama/fumadocs/releases for details

they are mostly bug fixes

[AaronLayton]

Every time I have come to update fumadocs, it is never just bug fixes. Whole integrations change the way they are setup, options removed, how you set them up changes. Honestly it is not a great experience.

When you go to the docs website, you would expect to CTRL+K and search for upgrade or update and get some docs, but there is no docs there at all. The only thing I can find is on the Getting Started guide and that just says to use pnpm and update all the package versions.

Today I am running through an upgrade and up to yet I have had to fully change

• how we generate LLM documentation
• where the APIPage is (create a new component locally) + the settings around it.

* Have to change the `source.config.ts` * ` disablePlayground: true, showResponseSchema: true` have both been removed when doing a `createOpenAPI` * previous sidebar tabs code from fumadocs no longer works

There are just so many things wrong with a simple update to the latest versions. Am I missing something? Was there some other docs?

[AaronLayton]

confirmed - I am going from "fumadocs-mdx": "11.9.0" to "fumadocs-mdx": "14.1.0"

I will run through the link thanks @fuma-nama 💪

I think the biggest annoyance is I am not going to the Blog for the documentation on how to upgrade. Would it make sense to have a dedicated Docs page for it?

[fuma-nama]

Blog would be a better place we can regularly write about improvements & migrations (the same way Next.js documents their migration steps), other frameworks like Tanstack Start use their own GitHub discussion thread to announce changes.

[AaronLayton]

Why not both ? You are right that these announcements should be in Blog form, but then the documentation should also specify migration steps right, same as NextJS do here https://nextjs.org/docs/app/guides/upgrading/version-16

This would create a clean upgrade path for folks going straight to the docs on how to keep updated as the docs are searchable.

On a side note, I am following through the mdx-14 blog post, but my fumadocs-mdx:collections/server is not generating any docs entries. I am still looking into it, but any pointers?

[fuma-nama]

On a side note, I am following through the mdx-14 blog post, but my fumadocs-mdx:collections/server is not generating any docs entries. I am still looking into it, but any pointers?

Do you mean there's no files in .source folder?

[AaronLayton]

Yeah there was nothing in there. It was because I was using async or dynamic in the defineDocs. I think I am past that now. I have everything running except for the OpenAPI endpoints.

Thanks for all the replies today @fuma-nama
I will create a separate Issue for the last remaining thing in a moment

[fre2d0m]

I really like fumadocs. It seems that it can allow me to quickly create beautiful and useful documentation websites, but the upgrade method makes me hesitate. What I'm worried about is that the time consumed by the technical framework itself will be much more than the time I spend writing documents.

[fuma-nama]

We only do breaking changes annually, and migration guides can be found at https://www.fumadocs.dev/blog