Crealanta Magazine

Make and modify the Docusaurus Website (With Blog feature)

Feb 17, 2023
Docusaurus

Docusaurus is a static site generator which is rapidly growing in recognition in the community of developers.

In this post this article, we'll deep review of the benefits of using Docusaurs as your static site generator, and the reasons it's becoming a popular choice for the developers.

What's Docusaurus?

What makes Docusaurus apart, however, is its ability to help you build and maintain a site . It lets you quickly and efficiently build a fully-fledged site -- including blog features which highlights your posts immediately.

These are only a few highlights which make Docusaurus an excellent choice:

  • Created using React
  • Support for MDX version 1
  • Support for React component embedding via Markdown
  • Document versioning
  • Compatibility with Git, Crowdin, and other managers of document translation and large or single deployment

Who uses Docusaurus?

Here are just a few of the biggest brands that are that are using Docusaurus today (with more soon to come as Docusaurus' popularity is growing):

More and more join their ranks on a daily basis.

How To Install Docusaurus

Docusaurus is easy to install , and it only takes just a couple of minutes. In this guide we'll create documentation sites with a blog, and we'll modify how the site looks.

And here's the coolest part: It will take us less than an hour to spin everything up.

Let's dive in!

Requirements

Also, we'll use the example Docusaurus site from the GitHub repository. You can use it, or fresh installation of Docusaurus for this lesson.

Installation Process

For you to start the Docusaurus installation process, you must first to use the following command:

npx [email protected] classic

It will make a folder that you can use to build your website and also scaffold the traditional theme within it. The classic theme already contains certain pre-configured functions, such as a blog, custom pages, and the CSS framework.

Following installation, you need to run the following command to start the server locally:

NPM begin

If you want to build an optimized version that is suitable for deployment, you should run this instead

npm run build

Structure

When you've successfully installed your Docusaurus instance after which you'll be able access your project directory to examine your "skeleton" of your brand new website.

This is how the file structure is like:

my-website
 +-- blog
 | +-- 2019-05-28-hola.md
 | +-- 2020-05-30-welcome.md
 +-- docs
 | +-- doc1.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

A few points to note regarding a few of these folders and files:

  • Blog: Contains all the blog related files. blog.
  • /docs: Contains all the files associated with your docs. The order can be customized in your sidebar.js file.
  • /src: Contains all non-documentation files like pages or customized components.
  • /src/pages: All the MDX/JSX/TSX/JSX files will be changed into pages.
  • static: Static files which will be transferred into the build folder.
  • docusaurus.config.js: Docusaurus configuration file.
  • packaged.json: Each Docusaurus site is created as a React application, and there are all dependencies and scripts which it utilizes for React.
  • sidebar.js: Here you can specify the order of documents in the sidebar.

Customizing Your Docusaurus Installation

Let's go over the options for customization available from the beginning.

Home Page

First thing you're likely to be itching to do is customize the default homepage , so it shows your personal project. It's not difficult to make any changes you'd like in the Docusaurus homepage.

Configuration File

We'll then dive into the vital docusaurus.config.js file and modify some crucial details to our particular instance.

Name and Description

In the configuration file, you'll discover:

const config = {
 title: 'My Site',
 tagline: 'Dinosaurs are cool',
 url: 'https://your-docusaurus-site.com',
 baseUrl: '/',

Just change these details according to the needs of your website, then save the file.

To edit your navigation bar, locate the navigation bar item.

For our example here for this example, we would like to include an option to link, change the name of the "Tutorial" item to "Starter documentation," as well as add a logo.

This is how we'd do this:

navbar: 
 title: ' starters',
 logo:  
 alt: ' Logo',
 src: 'img/-logo-alpha-purple.png',
 ,
 items: [
 
 label: ' starters',
 to: '/docs/intro',
 ,
 to: '/blog', label: 'Blog', position: 'left',
 
 href: 'https://github.com/',
 label: 'GitHub',
 position: 'right',
 ,
 ],
 ,

The footer's customization feature in Docusaurus is made up of two sections that are the content of the footer as well as the links to the footer.

Footer Content

The majority of your footer's content (not not including links lists) could be put in your themeConfig.footer file. This is the ideal spot to include a logo as well as an informational notice about copyright.

Here's how we've modified our footer configuration:

module.exports = 
 themeConfig: 
 footer: The, the,
 ,;

The footer link changes are similar to altering the top navigation bar: Find this footer section within docusaurus.config.js and edit to make sure it meets your requirements.

Here's what we've changed our footer section to look to look like:

footer: 
 style: 'dark',
 links: [
 
 title: 'Docs',
 items: [
 
 label: ' starters',
 to: '/docs/intro',
 ,
 ],
 ,
 
 title: 'Talk with us',
 items: [
 
 label: 'Discord',
 href: 'https://discord.gg/vjRPMhFaBA',
 ,
 
 label: 'Support',
 href: 'https://.com/-support/',
 ,
 
 label: 'Twitter',
 href: 'https://twitter.com/',
 ,
 ],
 ,
 
 title: 'More',
 items: [
 
 label: 'Application Hosting',
 href: 'https://.com/application-hosting/',
 ,
 
 label: 'Database Hosting',
 href: 'https://.com/database-hosting/',
 ,
 
 label: 'WordPress Hosting',
 href: 'https://.com/wordpress-hosting/',
 ,
 
 label: 'Dev',
 href: 'https://.com/dev/',
 ,
 ],
 ,
 ],
 ;

CSS and colors

The default for classic style in Docusaurus utilizes an Infima CSS framework. With this in mind, Docusaurus creators made a extremely useful tool on the web that lets you alter the color scheme and also various CSS elements and declarations.

When you've completed your selections on the page it will then generate an custom.css file -- complete with a lovely range of complementary tones- in a matter of seconds. You can then copy this brand new CSS file to the project's /src/css directory to be used as a use as a reference.

Docusaurus' custom CSS tool.
A portion of the Docusaurus official documentation, showing their custom CSS tool, which includes fields for users for putting in hex code changes for each individual element in the Docusaurus design.

Documentation

Everything you need to know about your website will be stored within the documents folder. Of course, you can change the folder name in docusaurus.config.js.

---ID: the-idtitle"title"# The rest of document

Based on the ID, Docusaurus builds the URLs for the articles in that subfolder: yourdomain.com/docs/id

We can also create subfolders to separate our documentation into different, logical sections. But, we'll have to do a little extra work in order for these folders to work the way we'd hope.

Let's say we make a brand new document folder that is named "Starters." If we want to refresh the homepage and click on the newly created "Starters" link automatically in our sidebar we'll get an error -- because there is no index page yet in the folder we've created.

The easiest method to correct this issue is to make the _category_.json file that produces an index of every page within this folder. It is all you need to do is add the following code:


 "label": "Starters",
 "position": 2,
 "link": 
 "type": "generated-index",
 "description": "All Starters"
 ,
 ;

As you can see, the sidebar changes to fit the structure of your files. This is because the sidebar.js file contains this tutorialSidebar: [ype autogenerated', dirName:. '],

If you'd rather take charge of this yourself You can modify this into something like this:

tutorialSidebar: [
 'intro',
 'hello',
 
 type: 'category',
 label: 'Tutorial',
 items: ['tutorial-basics/create-a-document'],
 ,
 ],

Blog

Docusaurus has a simple blog module. The presence of a blog in conjunction with your primary website may be very useful to inform your users about changes happening in your project, or to create project notes that can be used as an example of a change log.

Every post is comprised of a frontmatter part such as:

---
 slug: docusaurus-starter
 title: Docusaurus Starter
 authors: palmiak
 tags: [starters, docusaurus]
 ---

...and, of course, the content itself. Additionally, it has a helpful