Building Stunning Docs: Diving Deep into Docusaurus Customization

In the realm of web development, documentation stands as a cornerstone for successful projects. Enter Docusaurus—a streamlined, open-source documentation framework designed to simplify the creation of elegant and intuitive documentation websites.

Docusaurus offers a powerful yet straightforward approach to crafting documentation. With Markdown-based content creation and user-friendly workflows, it empowers developers to focus on content without the hassle of intricate HTML, while ensuring flexibility and ease of navigation.

In this comprehensive guide, we delve into the intricacies of Docusaurus, exploring its features, setup, customization options, and advanced functionalities. Join us on this journey as we uncover the art of leveraging Docusaurus to create compelling and effective documentation sites.

Docusaurus

Docusaurus functions as a static-site generator that constructs a single-page application, enabling rapid client-side navigation and harnessing React's robust capabilities to imbue your site with interactivity. While it comes equipped with pre-built documentation features, its versatility extends to the creation of diverse sites, including personal websites, products, blogs, marketing landing pages, and more.

Installation

To create Docusaurus run the command below in your terminal, it will scaffold the new Docusaurus project with its latest version (currently v3)

npx create-docusaurus@latest my-website classic --typescript

There are more templates to choose from when you create the Docusaurus app but we stick with the standard documentation, a blog, and custom pages which is a classic template, and to use with typescript add the flag --typescript to the end of the command.

Note/ make sure you have installed node v18 or above

Project Structure

After running the command you have your project structured like this,

├── blog
│ ├── 2019-05-28-hola.md
│ ├── 2019-05-29-hello-world.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

• /blog/ - This directory contains all the markdown files, of your site blogs, you can simply add a new blog by using markdown, or simply remove a blog file by deleting its file, you can combine the markdown with MDX, resulting a well-written blog post.

• /docs/ - Just like the blog directory you can create markdown files for your docs, the order of the sidebar is sequential based on your file, but you can customize the order in sidebars.ts.

• /src/ - Here we can add all the pages and components of our application, under the pages directory you can easily create any other pages of your website, the root is pages/index.tsx add another page like pages/showcase now showcase page is available under http://localhost:3000/showcase.

• /static/ - Static directory. Any contents inside here will be copied into the root of the final build directory

• /docusaurus.config.js - This is the site configuration file, where you can add the metadata, navbar links, footer links, and title, etc...

• /sidebars.js as we mentioned above used to specify the order of documents in the sidebar

You can run the app by running
npm run start


Congratulations! You have just created your first Docusaurus site, let's see what we can do with it.

Docursaurus config

The Docusaurus configuration file serves as the control center for shaping and customizing your Docusaurus-powered website. This essential file, often named docusaurus.config.js, encapsulates various settings and options that govern the behavior, appearance, and functionality of your site.

Within this configuration file, developers wield the power to define crucial parameters, such as site metadata, navigation structure, theme customization, plugin integration, and more. It acts as the foundation upon which the entire website is built, allowing users to tailor and fine-tune their site to meet specific project requirements and preferences.

By editing the Docusaurus configuration file, developers can seamlessly adjust the site's branding, manage navigation menus, enable or disable features, configure SEO settings, and incorporate plugins to enhance the site's capabilities. This centralized file not only simplifies the customization process but also provides a structured approach to efficiently manage and scale the website.

With its comprehensive yet accessible structure, the Docusaurus configuration file empowers developers to shape their website's identity and functionality, ensuring a tailored and polished online presence aligned with their vision and objectives.

Override Theme Components

One of the coolest things that I like is Overriding components from an existing theme or building your own theme from the ground up.

This process is called Component Swizzling.

[Swizzling] comes from Objective-C and Swift-UI: method swizzling is the process of changing the implementation of an existing selector (method). For Docusaurus, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.

What does this mean in practice? for example, you want to have a different footer rather than using a config file to add footer items, so for that, you can create a /theme directory under the /src directory, and create /Footer/index.tsx now Docusaurus will no longer use its default Footer that comes from the classic template.

But there is one step left we have to run a command to swizzle the footer away for that run the command below
npm run swizzle @docusaurus/theme-classic Footer -- --eject

By cloning the component from the Docusaurus package into our workspace, we've gained complete control over the appearance and style of the site's footer. This allows us the freedom to customize this specific element while retaining the ability to utilize other components from the theme, ensuring compatibility with future updates as well.

Using ThemedImage

Docusaurus supports themed images: the ThemedImage component (included in the themes) allows you to switch the image source based on the current theme.

import ThemedImage from '@theme/ThemedImage';

<ThemedImage
  alt="Docusaurus themed image"
  sources={{
    light: useBaseUrl('/img/docusaurus_light.svg'),
    dark: useBaseUrl('/img/docusaurus_dark.svg'),
  }}
/>;

Conclusion

As we conclude this journey, it's clear that Docusaurus isn't just a documentation framework; it's a catalyst for developers seeking streamlined, elegant, and effective solutions in presenting their projects. Its user-centric approach, rich features, and adaptability make it an indispensable asset in the toolkit of developers, teams, and organizations striving for excellence in their online presence.

Comments

[Hana Mohammad Abdullah]

Well done