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

Introduction

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.

awesome-web3

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\](https://img.freepik.com/free-vector/security-concept-illustration-people-holding-chain_53876-43028.jpg?t=st=1652793493~exp=1652794093~hmac=56d57921d4f37f94370ef406fb5327b90da8af413bf90286bf2553de7feeae1c&w=740)
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',
          'Web3 Roadmap with free resources',
          'Web2 VS Web3',
          'Blockchain',
          'Ethereum',
          'Decentralized Application(dApp)',
          'Smart Contract',
          'Solidity',
          'Remix IDE',
          'Crypto Wallet',
          'Interaction with Blockchain',
          'Local blockchain development environment',
          'Framework'
        ],
        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.

Conclusion

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)

Collapse
 
surajondev profile image
Suraj Vishwakarma

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

Collapse
 
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?

Collapse
 
sergiocomputerx profile image
Sérgio Bessa

compodoc.app/ is amazing to generate doc in angular apps

Collapse
 
surajondev profile image
Suraj Vishwakarma

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

Collapse
 
jcubic profile image
Jakub T. Jankiewicz • Edited

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

Collapse
 
guscarpim profile image
Gustavo Scarpim

Nice article!

Collapse
 
surajondev profile image
Suraj Vishwakarma

Happy to help you 😊

Collapse
 
riju_bro profile image
riju_bro

How do you make that awesome cover image 🤔?

Collapse
 
surajondev profile image
Suraj Vishwakarma

Canva

Collapse
 
sm0ke profile image
Sm0ke

nice

Collapse
 
surajondev profile image
Suraj Vishwakarma

I am glad that you like it

Collapse
 
ethand91 profile image
Ethan

Cool. Thanks for sharing :)

Collapse
 
surajondev profile image
Suraj Vishwakarma

Awesome that you like it

Collapse
 
ynwa profile image
Abhishek Pokhrel

Any recommendations for .net projects?

Collapse
 
surajondev profile image
Suraj Vishwakarma • Edited

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

Collapse
 
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?

Collapse
 
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.

Collapse
 
jhonatasmatos profile image
Jhonatas Matos

Perfect. Thanks again!

Collapse
 
deotyma profile image
Deotyma

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

Collapse
 
surajondev profile image
Suraj Vishwakarma

Glad that you find it helpful

Collapse
 
codevictor profile image
Hamzat Victor Oluwabori

Does docz playground support typescript?

Collapse
 
yukikimoto profile image
Yuki Kimoto - SPVM Author

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

Collapse
 
tasin5541 profile image
Miftaul Mannan

Any way to make the docs editable for business personnel?

Collapse
 
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.

Collapse
 
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.

Collapse
 
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.