🚀 Releasing Docz v1

Pedro Nauck
Mar 21, 2019 · 6 min read

When you're starting a project, the first thing that you want to focus in order to get success is getting user validations to make them approve your product. Usually, concerns about performance came up after the initial validation. This is not an absolute truth, but in most cases, this is how it happens.

With Docz wasn't different, right after its launch what we would like was to validate and create an easy-to-use and highly customizable tool that could feel an existent gap in the community. Our first releases were totally focused on features and how we could improve our user experience. However, even with a well-done architecture and trying to think optimally about performance and optimizations, it would be inevitable that issues related to this will arise later.

What you read above it's the base to our announcement. We work hard months on this release optimizing and improving our tool, but not only this. We also bring tools that can improve even more your results when writing your documentation.

⚠️ Migration Guide

It's import to warn that this release isn't compatible with old versions of docz, so keep in mind that if you want to migrate your project to the new version, please follow the Migration Guide.

Static Rendering with Gatsby Themes

Surely the best feature that we have in this newest version is the integration with Gatsby using the new theme features. If you don't know yet what is this new Gatsby feature, here a short explanation:

Gatsby themes is one of the coolest features of all times in Gatsby, with the introduction of theming in Gatsby, it’s easier than ever to get started building a Gatsby site. Shared functionality, data sourcing, and design can all be prepackaged as a Gatsby Theme that’s an NPM install away.

Basically, you can create your Gatsby config preset and publish it as a package to be consumed just by setting it on your gatsby-config.js .

You can check more about themes here:

So, now we are introducing our gatsby-theme-docz, a Gatsby theme that brings Docz into the Gatsby development environment, allowing you to enjoy all the power of the tool and all its features. This way, you can create just the documentation part of your website using Docz and all secondaries pages using Gatsby, everything in the same project. Cool, right?

And to usegatsby-theme-docz it's very simple. First of all, just install the dependencies:

Image for post
Image for post
Installing dependencies

Then just add your theme inside your gatsby-config

Image for post
Image for post
Setting the theme in Gatsby config

That's it, now you just need to create your .mdx files inside your project and you'll see Docz running inside your Gatsby project

Below you can check an example of a library built with Docz and Gastby.

Now imagine that you want to add a blog inside your library site. You can simply add another theme to running together with gatsby-theme-docz :

Image for post
Image for post

React with Hooks

In this version, we made a huge refactoring inside our packages removing all React classes components and using the new React Hooks spec instead. This enables us to generate more clearly API's for you that want to create your own theme inside Docz.

Previously, if you were developing your theme and needed to access the list of documents parsed by Docz, you should have something like this:

Image for post
Image for post

Now, with hooks, you just have this:

Image for post
Image for post

If you are interested in knowing which hooks were introduced in the new version, you can check this link.

Goodbye <PropsTable>, Hello <Props>!

One of the biggest problems that we'd in our oldest version was related to the <PropsTable> component, because of the way that it was built, besides damaging much in terms of performance, it had a lot of problems related to the props parser using react-docgen and a not so good UI.

In this version, we made a lot of improvements with the props parser algorithm, bringing it inside our core structure and, with this, gaining a lot on performance issues. These changes decrease substantially our initial build time and also we removed the table format of the component. So, we are introducing now a new component called <Props> :

Image for post
Image for post
MDX file using new <Props> component

And now, it works very well with styled-componentstoo 🎉

Performance Improvements

As previously mentioned, in this release we're focused a lot on improving Docz performance, including improvements in our webpack bundle and in the React rendering too. Basically, now we have an almost 50% smaller and 4.5x times faster build.

See some benchmark building the same project, but with different versions:

Image for post
Image for post

Spectrum instead of Discord

Another great point in this release, it's now we have our Official Community on Spectrum and we aren't more with Discord. So, if you have any questions, please talk with us there 🙏🏻

What's next?

We want more and more of those who use Docz to have an easy, powerful and highly flexible tool to create their documentation. So, for future versions we want to further improve the performance of our packages, create features that create small pieces of your documentation without great efforts and also be closer of Gatsby, since we believe it's the best tool for static websites buildings. We really want to get closer to be able to give you the best tools to create fantastic documentation.

Become a Core Developer

I think that this is the sad part of the release 😕. Today, basically Docz it's a project of one man and as you know, is very hard to keep and maintain a project alone and even harder if it's a big project. So, if you want to be a core developer and help to develop and maintain Docz, I’d be very happy. Please, talk with me on my twitter, I really want your help 🙏🏻

Become a Sponsor

So, if you're using Docz on your business, or even you want to use it later, considering to support us or make a simple donation to keep the project alive. We have so many great benefits for people that support us and it may be the chance your company appears and stand out even more in the community.

Check some of our current numbers:

Image for post
Image for post

Thank you

I want to thank especially Kyle Mathews, John Otander, Chris Biscardi and the whole Gatsby team that help and support me so much in the last month. Without them, this version would certainly be far from being released. So, that's it, thank you, guys.


Posts about features and other things with the docz!

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store