Documentation Preview & Slugs
Summer is here... and so are the most sought-after documentation improvements, all in one, neat release.
This version was released on June 5, 2023.
The long-awaited documentation preview is finally here, so you can catch those pesky typos before someone else does. We've also added documentation slugs. Plus, we've made inviting new team members to your workspace even more accessible, so you can easily share your new, improved documentation with more viewers!
We all know that sinking feeling when you release your carefully crafted new documentation page, only to discover a glaring typo or formatting error. We've got your back — introducing our new documentation preview!
You can now preview your new (or updated) documentation site before publishing anything, so you can make sure everything is as perfect as can be before sending it out into the wider world.
And importantly, your preview site is password protected, so even if your published site is public, only logged-in Viewers (or Editors, or Admins) with the link can see your work in progress.
The documentation preview works as a second destination for your docs, which means you can share links to both production and preview site separately and can move with different velocities.
We have also made preview the primary documentation action, so you don't accidentally publish the work you don't want others to see.
Ever wanted to move the documentation page to some other place, but got worried that your old links will break everywhere? With this release, we got you covered. We have changed the URL so that it always contains unique identifier of the documentation page — and if users accesses old URL, we'll gracefully redirect them to its new destination, so, move away!
The only exception to this is if you delete the page and create it again, in which case the persistent link between them will be deleted as well.
For teams using the custom exporters, you need to merge the upstream changes and update your exporter, otherwise the old system of generating URLs will be used instead.
We're also introducing page slugs for your documentation domains!
So far, we've been hosting published documentation using your workspace slug as the subdomain, and then your slugified design system name in the path. We're now defining the subdomain by the simple design system slug instead to make domains easier to read for you.
If you're on a Free plan, your slug is randomly generated based on your design system name. You can edit the slug to your liking if you're on a Team plan. Company plans can still use custom domains, or they can use the editable design system slug.
Many of you mentioned that inviting team members could be a slow process as invites had to be sent one by one. We listened to your feedback, so you can now paste multiple emails separated by either , , ; or |, for example:
firstname.lastname@example.org; email@example.com; firstname.lastname@example.org
And they will be split into separate invites like this:
The Publish button in your documentation editor now opens a popover with information about your documentation site. You'll be able to see the website URL, when your documentation was last published, and the new Build documentation button, which creates a new build of your docs.
Documentation hosting and serving was also moved to a new server technology for better resilience and availability. As part of this change, we have also greatly improved the way consumer documentation is loaded and cached, resulting in loading much less data on average and improving the documentation UX.
- Accessing private docs hosted on a custom domain now takes you straight to the documentation instead of showing you a list of available design system documentation sites.
- We've fixed the issue with syncing overrides for measure, typography, shadow, and other tokens through CLI.
- We've resolved issues with syncing certain transformed tokens through CLI.
That's it for this release, and we'll be back with more soon. As always, if you'd like to see something new, fixed, or improved, join our Discord community — we're always there. You can also request a feature via our Feature Request Portal. Thanks for your support!