Mar 1, 2022

Introducing Hyperdocs - The simplest way to build docs for your project

Documentation is one of the main reason why a project or a library becomes popular. It’s very important for a medium to large scale project to have documentation.

The better and beautiful a documentation is, the more popular the project becomes.

But the documenting tools present now require way too much boilerplate, becomes tedious to maintain, loads of configs and require separate deployment pipelines and more.

That is why I came up with Hyperdocs

Hyperdocs is the easiest way one can build documentation site for any project. It requires no config at all!

To show the potential of Hyperdocs, I rebuilt the Hashnode support docs with Hyperdocs. View it here


Generated docs

Before diving into my project, let’s see how the current tooling works.

All the current documentation tools can be broadly categorized into 3 types

What if you could combine the best of all tools?

Introducing Hyperdocs

What is Hyperdocs

Basically, Hyperdocs is a documentation generating tool which fetches markdown files from a docs folder from GitHub, statically generates it on the server and sends html to the client.

But that’s not it. Hyperdocs also provides a blog for each project created so that you can make your new release announcements and other news there.

Hyperdocs also provides many services that is not present in any other tool such as feedback collection, publishing blogs from a dashboard(more on this later), no configuration files need at all. Yet the generated docs are highly customizable.

When you write content for your documentation, you don’t need to just have plain markdown there. Hyperdocs provides many prebuilt components that you can use while authoring your docs.


A brief overview of all the features of Hyperdocs


Feedbacks dashboard

Feedbacks play a vital role in creating a delightful documentation.

Hyperdocs provides a complete feedback collection system for your docs. Every site has a feedback collecting widget that helps you gather feedback from your users.

Feedbacks also come with a rating that’s measured in terms of stars out of five.

All the feedbacks can be seen in the dashboard

No other documentation tools out there provide such a feature.


Blogs dashboard

Hyperdocs lets you add a blog that lives beside the documentation

This is also an other feature which only a few of the documentation generators provide.

Not every project requires a blog. With Hyperdocs, you can just remove the blog link from navbar in dashboard.

With Hyperdocs, you can write the blog post and save it as draft in dashboard. Publish it only when you feel it’s done.

But with other tools such as Docusaurus, there’s high chance of pushing and deploying drafts to GitHub.

I’ve also published this blog in Hyperdocs Blog →


Hyperdocs works without any special configuration. But when it comes to sidebar, there’s no way one can decide in which order you want the files to be.

Every documentation tool requires you to have a sidebar.json or a similar json file that decides the order. But Hyperdocs just asks for a _sidebar.txt. Yes a text file.

Having this file is optional!!. If you don’t add a _sidebar.txt, the links in sidebar will be in a random order.

This file just contains the list of markdown files in a specific order in which you want the links in sidebar to be.

Another thing is an file that will be the /docs/ of the generated website. This is again an optional one.

But wait. As the size of markdown files grow, adding the file to _sidebar.txt everytime can become tedious. That’s where the Hyperdocs CLI can help you.


CLI image

Hyperdocs also has a tiny CLI that helps you write docs. While creating a new page in /docs folder, just use npx hyperdocs-cli new filename and it will update the _sidebar.txt too!

View the docs for CLI

Uff there are a lot more. You can check the Hyperdocs documentation to check out more features and capabilities of Hyperdocs

Tech stack


Comparison image

Hashnode rebuild comparison

Here’s Hashnode support docs’ repo made with Hyperdocs

Hashnode rebuild image

The package.json only contains a single dev dependency Hashnode rebuild package.json image

And here’s the same docs built with Docusaurus

Docusaurus rebuild image

In both of the images, docs/ folder contain same files. In the first one(with Hyperdocs), there’s no frontmatter in every page!

Challenges faced

Building CLI

I’ve never built a CLI before. But when I was comparing all the tools out there, cac seemed to be a great choice. After using cac with tsup, I realized that building CLIs are way easier than I expected them to be.

I’ll be writing a blog about them in near future too. Let me know if you’re interested.

The holy-grail layout

Getting the three column layout with tailwindcss was a bit difficult. After tinkering with tailwind classes for sometime and taking help by inspecting the tailwindcss docs, I was able to get it right.

Markdown processing

I learnt a lot about markdown processors and how to use MDX. I went with Kent C. Dodd’s mdx-bundler for bundling the markdown.

mdx-bundler uses esbuild under the hood. So it’s crazy fast. This translates to faster regeneration of pages on Netlify.

Fetching content from GitHub and generating pages

This was the most difficult part. Getting the content’s easy. But parsing and generating pages posed different problems. But I was able to solve them.


Hyperdocs is not perfect yet. There’s still loads essential features that can be added. Here are some of the features that will be arriving soon


PRs are always welcome.

If you would like to add some components that you think would be useful while writing docs, you can add/contribute here :)


Hope you like my project!
Please let me know what do you think about my project.