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.
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
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
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
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"
},
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
---
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.
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",
}
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
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.