DEV Community

Cover image for How I build a Documentation site using Docz
Suraj Vishwakarma for Documatic

Posted on


How I build a Documentation site using Docz


I use any dev tools or library on the basis of its documentation. I use their documentation to know about the tools and how to integrate them into different setups. If the documentation is not that good I’ll pass on the tool because it will take a longer time for me to figure out it’s working through other articles and videos.

Documentation is the original source of knowledge about the tool and it later extends to form articles and videos on a specific topic. So, having well-structured and formatted documentation is necessary. At the same time, building documentation from scratch can take a lot of time. That’s why using a tool/framework to create documentation is preferred. Docz is one such tool to create a documentation site.

I have used Docz to create a documentation site for my awesome-web3.0(A collection of awesome resources to learn Web 3.0) GitHub repository. You can take a look at the website here.


It is quite good-looking and has support for light and dark themes. Building a beautiful website using Docz is easy. The documentation is written in markdown which is the preferred way of writing the text for most of the developers.

I hope this excites you as we are going to build such a website with all these features. Let’s get started.

Setting up the environment

We need to have the following things pre-installed before we start builduing:

  • NodeJS: It is a JavaScript runtime that allows the JavaScript to run in the terminal. It will come with npm that will allow the running of commands to install necessary libraries.
  • Gatsby CLI: As Docz is made on top of Gatsby, we need to install the Gatsby CLI. For installing it, you can run the below command after installing the NodeJS.
    npm install -g gatsby-cli
Enter fullscreen mode Exit fullscreen mode

They are changing it to Astro soon.

This is all we require now, let’s set up the Docz.

Setting up the Docz

Navigate to the directory in which you want to create your project. First, open the terminal and run the below command to create a package.json file that will manage our dependencies and scripts.

    npm init -y
Enter fullscreen mode Exit fullscreen mode

Now, it's time to install the dependencies of our project. Let’s look into them.

  • docz: It is the library that will add the docz functionality to our application.
  • react and react-dom: Since docz is based on Gatsby which is a framework of React, we need to install react.

You can install all the above dependencies with the below command:

    npm install docz react react-dom
Enter fullscreen mode Exit fullscreen mode

Now, we need to add a few scripts in the package.json file that will be used to run and build the application. Here are those.

      "scripts": {
        "dev": "docz dev",
        "build": "docz build",
        "serve": "docz build && docz serve"
Enter fullscreen mode Exit fullscreen mode

Creating the first page

For displaying a page, Docz wants a.mdx file. It’s an extension to markdown that allows JSX in markdown with other cool features. You can learn more about it here. You can add a markdown file in the root directory but I recommend adding all your files in an src/ directory in the root. You can name the file whatever you want with an extension .mdx.

At the top of every file, we need to define some properties. Let’s discuss some of them.

  • name: It is a mandatory property that will have the name of the page as the value.
  • route: Here you can define the route to which the page will be rendered. If not defined, it will use the file path as the route.
  • menu: You can create sub-pages of any main page. For instance, In Installation, we can have an installation guide for Windows, macOS, and Linux.

All these properties are defined within two triple hyphens (---). You can look into it below.

    name: Web3
    route: /web3
    menu: Web2 Vs Web3
Enter fullscreen mode Exit fullscreen mode

Below the closing triple hyphen, you can add the content of the page in the markdown format. Let’s add some of that too.

    # Blockchain

    > Blockchain is a non-modifiable ledger system that records the transaction and it is shared across the node i.e, the computer participating in the network.

    ![Blockchain Development\](
Enter fullscreen mode Exit fullscreen mode

Project Configuration

You can configure the project for a variety of features. You can learn about it here. We are going to add some of those to our project. First, we need to create a file with the name doczrc.js in the root directory. Here, we will add the properties of the configuration. Let’s look into them.

  • title: It is the heading of our page which will be displayed at the top of the documentation page.
  • description: As the name suggests, It is the description of the documentation.
  • menu: This is interesting, you can arrange your page in the order in which you want to display it. It is an array of names of the document that we added in every document.

This will make our doczrc.js file look like this:

    export default {
        title:'Awesome Web3.0',
        menu: [
          'Web3 Roadmap with free resources',
          'Web2 VS Web3',
          'Decentralized Application(dApp)',
          'Smart Contract',
          'Remix IDE',
          'Crypto Wallet',
          'Interaction with Blockchain',
          'Local blockchain development environment',
        description:"Web3 Roadmap and free Resources to learn and ace",
Enter fullscreen mode Exit fullscreen mode

Note: The file name in the menu are from my documentation site.

Running the server

It is quite easy to run the server at localhost. You can run the below command.

    npm run dev
Enter fullscreen mode Exit fullscreen mode

Documenation webpage

You can change the theme from the top-right button. By default, it will be according to your browser's default.


Building a documentation site is quite easy with Docz as we have seen. You don’t have to build your frontend and Docz is customizable to make it your own. Time and money will all be saved when using a documentation-building framework.

Docz has a feature that they call Playground. It allows you to render your component in an editable code editor. This component will also have a live output to see the change. This is will be very useful for component-based libraries documentation. You can explore it more.

I hope, this article has helped you understand Docz and its feature of building documentation sites. Thanks for reading the blog post.

Oldest comments (27)

surajondev profile image
Suraj Vishwakarma

You can use Docz to create more than just documentation. What will you build using it?

renancferro profile image
Renan Ferro

Niice, I didn't know "Docz". It's so cool! Unfortunately they don't have angular support yet. 😭 Do you know something like this to do with Angular?

sergiocomputerx profile image
Sérgio Bessa is amazing to generate doc in angular apps

surajondev profile image
Suraj Vishwakarma

Docz is awesome and they are re-buidling the tool with Astro to make it more faster.

jcubic profile image
Jakub T. Jankiewicz • Edited

You documentation doesn't have to be in same framework as your application.

guscarpim profile image
Gustavo Scarpim

Nice article!

surajondev profile image
Suraj Vishwakarma

Happy to help you 😊

riju_bro profile image

How do you make that awesome cover image 🤔?

surajondev profile image
Suraj Vishwakarma


sm0ke profile image


surajondev profile image
Suraj Vishwakarma

I am glad that you like it

ethand91 profile image

Cool. Thanks for sharing :)

surajondev profile image
Suraj Vishwakarma

Awesome that you like it

ynwa profile image
Abhishek Pokhrel

Any recommendations for .net projects?

surajondev profile image
Suraj Vishwakarma • Edited

Don't know about .net bro. I hope someone who knows reply you

jhonatasmatos profile image
Jhonatas Matos

Nice! Thanks for sharing, I have a question about deploy. Can I use vercel or netlify as I would use in other projects react?

surajondev profile image
Suraj Vishwakarma

You can use any of them for deploying. I have used the Netlify for hosting my project made up of Docz.

jhonatasmatos profile image
Jhonatas Matos

Perfect. Thanks again!

deotyma profile image

Thank you. I've just looked for something like this.

surajondev profile image
Suraj Vishwakarma

Glad that you find it helpful

codevictor profile image
Hamzat Victor Oluwabori

Does docz playground support typescript?

yukikimoto profile image
Yuki Kimoto - SPVM - Perl Club

We are creating our site using Perl and Giblog. I know Docz at first time. Thank you for your information.

tasin5541 profile image
Miftaul Mannan

Any way to make the docs editable for business personnel?

surajondev profile image
Suraj Vishwakarma

As it provides you with a framework from which you can build anything. The support of MDX is awesome that will let you have a lot of options to add to the page. You can use it for business purposes too.

andrewbaisden profile image
Andrew Baisden

That's a really cool project, thanks for sharing. One of these days I will have to give astro a try people keep mentioning it. Like supabase and medusa its always in conversations.

surajondev profile image
Suraj Vishwakarma

Thanks, Adrew for your words. Give it a try to and make a post about it. Will love to see your perspective on it.

The JavaScript Brief

Dive into the world of JavaScript with these three trendworthy articles that you cannot miss this week!

7 JavaScript Web APIs to build Futuristic Websites you didn't know

Explore the world of overlooked Web APIs that can bring your next project to new heights 🌕🚀. Some of the best Web APIs include Screen Capture API, Clipboard API and Web Workers API. Get informed and cast a glance at some of the future stars of web development.

10 GitHub Repositories You Should Know as a JavaScript Developer

Elevate your skills as a JavaScript developer with these 10 top GitHub repositories. Ranging from NodeJS best practices to diverse libraries and collections, these repositories are a must-know for any dedicated JS dev.

20 Killer JavaScript One-Liners That’ll Save You Hours of Coding

Multiply your coding agility with 20 essential JavaScript one-liners 🚀 that save both time and energy when developing. Discover amazing one-liners for finding max value in an array, capitalizing the first letter of a phrase, generate secure ID, among many others.

Get inspired, and level up your JavaScript game with this week's top reads! 🎢🧗