More documentation improvements!

So many improvements: Token block variants, a newly designed site, new search functionality, and more! Plus some extra bugfixes, because we’re perfectionists.

This version was released on July 21, 2022

 

With this version, we heavily focused on improving your experience and options when creating the documentation. So many bugs squashed, and so many nice things added!

Apart from focusing on Docs, we are also bringing the improved import flow to handle larger files and larger sets of linked files. We have also introduced better way how we resolve custom domains, which makes configuring your custom domains even easier and supports all different edge cases you have reported us! Now, without further ado, let's look at what this release has in store.

New token block variants

Token blocks are one of the most critical pieces of any documentation and we made them 10 times better. Previously, token blocks (detail, grid, list) were limited to a specific mode of rendering, but that is not the case. It is now possible to select from several variants of each block from the variant menu:

Each token block now has 5 different modes to choose from

Each token block now has 5 different modes to choose from

 

And because this documentation is created using Supernova, let's look at how they look like when you use them in your documentation site!

Variant: Table

With tables, you can show a lot of information quickly, and bring attention to the values instead of the visual representation. Great for long lists of tokens and overviews of styleguides in general.

#6b62cc
Purple 700
Token set
-
Themeable
Status
-
In settings
React Name
-
#7d73e2
Purple 600
Token set
-
Themeable
Status
-
In settings
React Name
-
#8d84ed
Purple 500
Token set
-
Themeable
Status
-
In settings
React Name
-
#9e95ec
Purple 400
Token set
-
Themeable
Status
-
In settings
React Name
-
#c0c2f3
Purple 300
Token set
-
Themeable
Status
-
In settings
React Name
-
#d8d8f6
Purple 200
Token set
-
Themeable
Status
-
In settings
React Name
-

Variant: 1 column

1 column variant allows you to highlight detail of one specific token in its full glory:

#3a79bd

Blue 700

Token set
-
Themeable
Status
-
In settings
React Name
-

Variant: 2 columns

2 column variant is great to highlight difference between foreground and background color!

#453e96

primary.activeBackground

Token set
-
Themeable
Status
-
In settings
React Name
-
#ffffff

primary.color

Token set
-
Themeable
Status
-
In settings
React Name
-

Variant: 3 columns

For the times when 2 is just not enough.

#b6403b

Red 800

Token set
-
Themeable
Status
-
In settings
React Name
-
#78c767

Green 500

Token set
-
Themeable
Status
-
In settings
React Name
-
#aad2f4

Blue 300

Token set
-
Themeable
Status
-
In settings
React Name
-

Variant: 4 columns

Similarly to table 4 column variant can accomodate lot of data and is ideal for long lists with lot of information.

Palette / Pink

#281821

Pink 1100

Token set
-
Themeable
Status
-
In settings
React Name
-
#4f1930

Pink 1000

Token set
-
Themeable
Status
-
In settings
React Name
-
#872647

Pink 900

Token set
-
Themeable
Status
-
In settings
React Name
-
#a43b5b

Pink 800

Token set
-
Themeable
Status
-
In settings
React Name
-
#be4466

Pink 700

Token set
-
Themeable
Status
-
In settings
React Name
-
#cf517c

Pink 600

Token set
-
Themeable
Status
-
In settings
React Name
-
#de638b

Pink 500

Token set
-
Themeable
Status
-
In settings
React Name
-
#ee7fad

Pink 400

Token set
-
Themeable
Status
-
In settings
React Name
-
#f19bc0

Pink 300

Token set
-
Themeable
Status
-
In settings
React Name
-
#f4b8d4

Pink 200

Token set
-
Themeable
Status
-
In settings
React Name
-
#f7dcea

Pink 100

Token set
-
Themeable
Status
-
In settings
React Name
-
#fbeaf2

Pink 0

Token set
-
Themeable
Status
-
In settings
React Name
-

Bonus: Now with aliases!

There were several improvements to how the data show in your styleguide, and we are also bringing something you asked for a lot - showing whether token is aliased or not. If the token is reference, additional information will be shown under the token for each of the rendering modes.

 

Voila, reference shows up right away!

Documentation site design overhaul

We have also significantly improved the design of the exported site. We have basically touched every aspect and made it a little bit better - modified spacing here, aligned images there, updated typography, made stuff more readable and so on. Here is a full list of what we improved:

  • Fonts
  • Header section rendering
  • Typography, headings and paragraph stylings and offsets
  • Default margins and paddings for all sections
  • Spacing and styling for tab elements (pills and tabs)
  • Table spacings
  • Lists, both ordered and unordered, their rendering and margins
  • Quote block paddings
  • Callout spacings
  • Border radii for images and other elements
  • Finally, we have improved behaviors of newlines between blocks, so you don't have to, in most cases, create extraneous newlines inside the editor. Just write the text how you'd expect, and docs will do the rest.

 

Our design team worked tirelessly to show you what all was improved, here is their masterpiece:

It is a joke of course - we'd need many more arrows to point out all the improvements.

It is a joke of course - we'd need many more arrows to point out all the improvements.

While isolated changes will not be noticable immediately, all of them result in much more readable, crisp documentation site that shouts out "polished", and that is what matters the most at the end.

Search 2.0

We have additionally reworked how the search work in our documentation! You can now search for pages, sections and texts, everything is insanely fast and we have added several new conveniences for you:

  • It is now possible to use Cmd+K/Ctrl+K to open up the search dialog in published docs
  • It is now possible to use ESC to clear up the search query and search again right away
  • If there is no search query, ESC will close search immediately
  • It is now possible to go through results using Arrow up, Arrow down
  • It is now possible to go directly to the result by pressing (enter/return)
  • It is now possible to link directly to the search result link, for pages, sections and even specific blocks, by selecting search result (click or enter) and copying resulting URL in the browser
  • New notes about available shortcuts were added so your consumers know about it

 

And finally, we had a lot of fun reworking it and added lot of fun effects to it. You can try it right now, by clicking search icon on this site!

New search experience, with all bells and whistles.

New search experience, with all bells and whistles.

Additional improvements

Here are few of additional improvements that are more technical for specific users that reported it:

  • Import flow was improved to use polling — this prevents multiple unnecessary refreshes at the same time.
  • Resolve request for custom domain settings was replaced with a more specific request to resolve only CNAME records.
  • We have reworked how content menu works. It will now properly track categories, and will highlight multiple categories at once

Bugfixes

Finally, lot of annoying things were resolved. Enjoy!

  • It is now possible to log into private Docs on custom domain properly again.
  • Having Storybook or Markdown links behind VPN no longer causes Docs to fail to deploy.
  • SDK resolution chain has a proper resolution priority now, which prevents a very rare bug with triple aliases resulting in failed export from happening.
  • LESS and SCSS exporters export properly indented code for all token types now.
  • Trying to publish some Component with Status option containing empty color no longer results in Docs failing to deploy.
  • H1, H2 and H3 headers are now properly indented in the Contents section of Docs.
  • Calling the header Content and clicking on it in published Docs no longer takes you to the top of the page.
  • HTML in Custom Footer code no longer contains the extra " in the code.
  • Divider in Tabs block rendered as Pills displays properly now.
  • Multiple lines in the Frame block description no longer result in one line description in published Docs.
  • Docs footer in published Docs fits the mobile screens properly now.
  • Putting the page title or header into pointy brackets <Like This> no longer results in the Docs page rendering as empty.
  • Clicking on content menu with multiple same titles will no longer break the menu anchors. We have adjusted the generation of anchors to acommodate for this situation by adding small hex at the end of the anchor

 

As always, if you would like see something new, fixed or improved, join our Discord community - we are always there. Thank you for your support!