Better control over URLs in your API documentation.
Nobody likes a broken link.
As referenced in a recent release roundup, now users can reorganize the files in their project without breaking or changing their docs URLs with new stable IDs and custom slugs.
Stable IDs refer to published API, model, and article URLs, and they also are visible in new, renamed, and imported files. They are visible in the published URL and are automatically set based on the location of the source file within the project file directory.
With a more stable way of generating these identifiers, the new stable IDs are resilient to file system reorganization. All old docs URLs will still work and are transparently redirected.
You can also now control your slugs for published URLs (also known as “permalinks”). A URL slug is the section of the URL after the last backslash.
“A slug can be very powerful for keyword SEO. If a user were to search Google for … the keywords in the URL … [the] structure of your content helps signal to Google that your content should be included on the SERP.” – SEMRush
Add slugs to the Table of Contents file for API and Markdown articles, removing the stable ID from the URL. This gives you the ability to control the URL ending without breaking backlinks or bookmarks.
“When you set a slug for an item, the previous stable-ID-based URL automatically redirects to the new slug-based URL. This allows you to incrementally introduce custom-slug-based URLs to your project without breaking user bookmarks or backlinks that might be pointing to the old stable-ID-based URLs.” Learn more in this documentation.
This update may seem like a simple change, but having stable page IDs and the ability to customize slugs will save a ton of hassle for your documentation (and your SEO strategy).
Here’s an example of the difference between URLs before and after the release.
- April What’s New (pre-release): https://meta.stoplight.io/docs/whats-new/86556a85fb940-april-2022-deployments
- May What’s New: https://meta.stoplight.io/docs/whats-new/may-2022
See how much nicer, and more straightforward the May link is?
To give you the most out of the new stable ID and custom slug functionality, Pam Goodrich, Manager of Tech Writing at Stoplight, shared a few tips.
Plan your approach.
Consider a taxonomy for nested URLs. At Stoplight, we are nesting the URLs for our Platform documentation based on our main TOC dividers: API design, Governance, Documentation, and Administration.
Keep track of the URLs you change.
Because this is a new feature (and just in case), you’ll probably want a record of what URLs you change. For Stoplight projects that are connected to Git, you can get the change history from your Git provider.
Use an external tool to search for link references.
You still need to update relative links, and there’s no automatic way to do this in Stoplight Studio (yet!). Use any text editor with global search and replace to find relative links that need to change in your Markdown files.
Be sure to check links inside files you move or rename.
For example: if you move and rename a file, you can fix the references to this file but don’t forget to check the links to other files inside of it.
Use some sort of automated link checker.
Stoplight uses this open-source tool: https://github.com/gaurav-nelson/github-action-markdown-link-check. It is configured to run after each push to Git, and it’s a lifesaver.
Don’t stress.
Changing slugs is actually pretty easy; once you have your taxonomy defined and do the upfront work, maintenance should be relatively low-key. You’ll have lots of control along with prettier, easier-to-use URLs.
