This content originally appeared on Bits and Pieces - Medium and was authored by Fernando Doglio
How can you have multiple versions of the same page living inside your documentation?
Astro is very popular right now, and rightfully so if you ask me. The framework allows developers to create static websites with great flexibility and power.
The ability to integrate multiple rendering libraries alone helps with adoption when you’re migrating from somewhere else.
And while creating a documentation site is probably trivial at this point, I wanted to cover a problem that I had to solve recently: adding multi-version support for your documentation site.
So let’s get going.
The problem
Building a documentation site is nothing more than building a static site with lots of pages.
Again, trivial if you’re using Astro.
However, what happens if those pages change when the version of your product changes?
There are two main problems to solve when that happens:
- The easy one: add the version to the routing process. You need to be able to switch between versions and since Astro uses file-path-based routing, you’ll have to create folders for each version.
- The tough one: handle all relative links to adapt them to the current version and keep internal navigation consistent (the same link should redirect to different versions, based on the currently selected version).
While they might not seem like much, solving these issues is not trivial.
Let’s take a look at how one could implement both features.
Solving the problem
We have two problems to tackle, so let’s go one by one.
Adding the version to your routing process
The easy part is making sure we go from routes like /docs/getting-started to /docs/1.1.0/getting-started .
That way, we can still reference the getting-started.mdx file that we’ll use for the content of that page, and to get to it, we’ll have to put it inside a folder called 1.1.0 .
That seems simple, all we have to do is change our folder structure, so it goes from:
/
|_ docs
|_ getting-started.mdx
To something like this:
/
|_ docs
|_ v1.0.0
| |_ getting-started.mdx
|
|_ v2.0.0
|_ getting-started.mdx
With that change, we’re now letting Astro know where it can find our content, and it will. If you run npm run build now, it’ll correctly build everything, but under the new folder.
We’re not done though, this is only half of step 1, we’re still missing a big part of our version support: the version switcher.
We need to add a way for the user to change versions, so let’s look at that code:
This is a simple component that you can add anywhere you want. I would personally add it on the header, since that’s where most documentation sites add it. But you can do whatever you want with it.
As you can see from the code, the component will draw a version dropdown based on the versions listed inside the VERSIONS array. From there it’ll get the label to show, and the path.
Notice how the latest version has no path, that way you can keep your latest version on the root under the docs folder, and only use version folders when there is a version specified.
Then the selectCurrentVersion function gets executed as part of the JavaScript code, this function takes the version number from the URL and finds the right option element to select.
Finally, with the onChange event from the dropdown, we call the updateLocation function. This function takes care of overwriting the current version with the selected one inside the current path. Then it simply redirects the user to the new URL.
But wait a second, does this mean now that every time you release a new version, you have to go through all your documentation links and update the internal links to keep them from moving the user between versions?
That would be a pain, especially if your documentation is big enough, so let’s try to do something about that.
Handling all relative links
We have to find a way to avoid keeping the actual version of the documentation inside the hard-coded routes we add to the docs.
This is because if we do it like that, every time we release a new version and we duplicate the latest version of the docs, we’ll have to run a search&replace process.
And if we forget to do it, or if for some reason, our search pattern doesn’t catch all URLs, then we’ll release a faulty documentation site.
We have to find a way to ensure we write our documentation always thinking about the current version, and linking to other sections of it as if there were no alternative versions of the docs.
The solution I came up with, was to add a script to fix the URLs directly on the browser:
I put that script at the bottom of my main layout file. That way the script runs when the content is loaded.
That code will run through all links, and it’ll look for the ones that redirect to a place within the site’s domain (ideally, something like “docs.yourdomain.com”) and only for those links, it’ll recreate them with the current version in them.
In other words, it’ll take /docs/getting-started and dynamically transform it into /docs/v1.0.0/getting-started without you having to do anything.
That way all relative links (the ones used for navigation) are automatically fixed for the currently selected version.
And that’s all there is to it, Astro allows for a great deal of flexibility when it comes to creating components and adding JavaScript to an otherwise static site.
These examples show two different use cases, one where the component created has a dynamic part, so even though the dropdown is rendered on the server, we still need to add extra JS code to make it work.
And on the other hand, all server-side rendered links need to be dynamically updated (actually, only the internal navigation ones), so we added a script to the page that does just that. And we didn’t need to work with any other UI library out there.
Have you run into this type of problem before? How did you solve it?
Build Apps with reusable components, just like Lego
Bit’s open-source tool help 250,000+ devs to build apps with components.
Turn any UI, feature, or page into a reusable component — and share it across your applications. It’s easier to collaborate and build faster.
Split apps into components to make app development easier, and enjoy the best experience for the workflows you want:
→ Micro-Frontends
→ Design System
→ Code-Sharing and reuse
→ Monorepo
Learn more
- How We Build Micro Frontends
- How we Build a Component Design System
- Bit - Component driven development
- 5 Ways to Build a React Monorepo
- How to Create a Composable React App with Bit
- Sharing JavaScript Utility Functions Across Projects
Adding Multi-Version Support to Your Astro-based Documentation was originally published in Bits and Pieces on Medium, where people are continuing the conversation by highlighting and responding to this story.
This content originally appeared on Bits and Pieces - Medium and was authored by Fernando Doglio
Fernando Doglio | Sciencx (2023-01-25T07:16:28+00:00) Adding Multi-Version Support to Your Astro-based Documentation. Retrieved from https://www.scien.cx/2023/01/25/adding-multi-version-support-to-your-astro-based-documentation/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.