🚀 Releasing Docz v2
Since the creation of Docz, the biggest bottleneck that we have is that we need to handle a lot of bundler tasks and this generates so many issues for us. This is bad because instead of creating new features for our users, we need to solve bugs and try to improve our bundler performance. Because of that couple of months ago in a partnership with Gatsby, we started to move our core and all our internal resources to work using Gatsby behind the scenes.
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.
Gatsby as Bundler
In the last major version, we introduced static render using gatsby-theme-docz, now since the v2 Docz is entirely built using Gatsby under the hood. This is the biggest change in the project since its creation and one of the best things that we could make for the tool.
Gatsby is a blazing fast modern site generator for React and one of the greatest modern tools of the new frontend era. It has a huge ecosystem and community around it and a very concise team behind. Using Gatsby as bundler behind the scenes we won a lot of benefits like:
- Stay focused on creating features instead of lead with bundler management
- Static and optimized builds by default
- Fast dev-experience and better workflow
- Huge ecosystem of tools, plugins and community
- Better and easy way to customize things inside Docz
- More power in order to create your documentation
Gatsby API and Hooks
Gatsby has a pretty damn good API for developers and a lot of hooks and life cycle methods that you can use in order to customize the process of
your bundle. Indeed you can hook into it in a lot of ways and all these hooks
and properties you can use with Docz.
Check all Gatsby API references here
So, if you want to use any of those Gatsby configurations file inside your Docz project, just create it in the root and we’ll lead with them for you.
Like, if you want to make some change in the webpack configuration, you can use the onCreateWebpackConfig hook inside the gatsby-node.js file:
Or if you want to change your Babel configuration you can use onCreateBabelConfig hook for this:
Customizing components
Components shadowing is one of the best things included in the new Gatsby theme feature, with it is possible to replace theme files just by creating your own file following a file naming convention.
Example: If you’re using our gatsby-theme-docz which has a <Header> component located at src/components/Header/index.jsyou can override the component by creating src/gatsby-theme-docz/components/Header/index.js.
Adding your logo
So, now that you know about how component shadowing works on Gatsby themes if you don’t want to override the entire <Header>component
but just change your logo inside it, you can shadow the <Logo> component used in the header just by creating your own at src/gatsby-theme-docz/components/Logo/index.js
Easy right?
New theme system
One of the coolest things about Docz is that you can create your own theme if you want from scratch and use all the benefits of it. The oldest way to accomplish that is by using the theme property inside the doczrc.js file. Now, if you want to create your own theme, just create a file located at src/gatsby-theme-docz/index.js
Theme UI integrated
As default theme system now we are using the Theme-UI, it’s a library to build consistent, themeable React apps based on constraint-based design principles.
You can modify our based theme creating your own style, combining these modifications with the component shadowing and creating totally different documentation.
Check our base theme object to see all the properties available.
To create your own theme definition use the doczrc.js and set your properties in the themeConfig like that:
Or, to create your own theme it’s easy, just create this file in the root of your project: src/gatsby-theme-docz/theme/index.js:
Conclusion
As mentioned earlier, using Gatsby as the main bundler gives us many benefits and from now on we can focus on creating new features and integrations with the entire Gatsby ecosystem.
We have a whole new world of possibilities!
Thank you
I want to thank especially Kyle Mathews, John Otander, Chris Biscardi, Brant Jackson 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.
