How do I create versioned API docs?

[jay4]

Hi, I am trying to create a simple site with the following requirements:

1. I have a landing page at https://my-site/ that should just be the latest build
2. I have versioned docs that should be “frozen” after they are built at https://my-site/docs/v0.0.1 - these should ideally be built when a new git tag is pushed to GitHub and can only be updated manually
3. I need a redirect from special tags such as https://my-site/docs/latest to specific versions (e.g. the latest tagged version, or the latest build on main)

This doesn’t seem like an uncommon pattern but I’m struggling to understand how to get Netlify to do this for me. Specifically, I am not sure how to:

• Create “tagged” deploys on new GitHub git tags
• Proxy specific paths to specific deploys (e.g. */v0.0.1/*)
• Get a list of available “tagged deploys” (for display to my users)
• Proxy a specific path (e.g. */latest/* to a given deploy

A platform such as ReadTheDocs provides this nicely like so, with a javascript-powered sidebar menu:

[nathanmartin]

@jay4

This doesn’t seem like an uncommon pattern but I’m struggling to understand how to get Netlify to do this for me.

It wouldn’t be uncommon in the documentation space, but it also isn’t something that Netlify is specifically geared towards solving, (unlike ReadTheDocs), so I don’t believe they have a recommended way of achieving it.

I did find this old post concerning similar:

Versioned netlify deploys

Hi there, I don’t have a good example implementation, since they’d depend quite heavily on how you handle and publish releases. Two workflows I am aware of people using: use semver directory structure and duplicate unchanged content in /1.1, /1.2, /1.3 . This would require that you have a git workflow where you do this already, since I’m not trying to suggest you restructure your repo or release process. Then the deploy just works. You might have “default” be the last stable version by po…