Contents
Introduction
Hey there! I'm Francesco known as Airscript on the web.
Today I want to share with you how to use Docusaurus in order to document your next awesome project.
Docusaurus comes as an all-in-one tool, meaning that you can create front pages, blogs and more with it.
I'll be covering only the documentation part with this blog post.
Requirements
Before even starting the next section, be sure to have installed on your machine the only requirement needed: Node.js.
The suggested version goes from 16.14 and above and you can check which one you have just typing node -v inside of your terminal of choice.
Installation
After you got all the requirements, you can easily install docusaurus inside one of your projects by simply running these simple commands:
npx create-docusaurus@latest documentation classic
# If you prefer TypeScript, you can pass an argument for that.
npx create-docusaurus@latest documentation classic --typescript
With the commands above we can create a fully classic docusaurus project, both with or without the usage of TypeScript.
There are more templates such as facebook instead of classic but we're not covering them in this article.
After running that command, you should have a situation like this in the documentation folder:
documentation
├── blog
│ ├── file.md
│ ├── ...
│ └── ...
├── docs
│ ├── file.md
│ ├── ...
│ ├── ...
│ └── ...
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock
Running
Now that you have a fully scaffolded project, let's try a simple first run.
It can be done easily following this commands:
cd documentation
npm run start
Configuration
Regarding the configuration part, you may have seen that our documentation right now has some examples in it.
We have to change that in order to reflect our project.
Before all of that, we have to configure how our documentation will be presented.
Inside the project you'll find a docusaurus.config.js file.
This file contains every configuration needed by your documentation site.
Here you can choose if your site needs to have only docs or even a blog!
Or simply change its title or logo.
For more information on what you can do here, just take a look to this documentation page.
Pages
As last, let's see how it's possible to add documentation pages or even edit the existing ones.
Start creating a Markdown file inside the inner docs folder:
touch docs/hello.md
The folder structure will be something like this:
documentation
├── docs
│ └── hello.md
├── src
│ └── pages
├── docusaurus.config.js
├── ...
Then you can start editing that Markdown file, adding some rich content:
---
description: "Hello Page."
---
# Hello
Hey there! I'm a documentation page.
Simple, isn't it?
In this file you can simply use Markdown and everything will be rendered with a rich content inside your documentation site.
I've also provided a description in order to add metadata to this page.
For doing this I've used Front Matter.
Conclusion
And we're at the end of our journey.
We have seen how to install Docusaurus, how to configure it and even how to create our first documentation page.
If you're interested, we can talk about deploying this actual documentation to your preferred site in a later article.
Until then, thank you kindly.
Share Support
If you have liked this post, just come and tell me!
Are you too shy for doing this? No problem. Just visit airscript.it and share your support following me on your preferred social platform.
If you want to make me even happier, just follow, share or star me and my projects on GitHub.
Top comments (0)