Adding Optimized Images to Docs in Docusaurus

Introduction

In product development, documentation is essential. It provides in-depth explanations on interacting with a product. However, creating a comprehensive documentation website from scratch and implementing features like localization, SEO, and media files can be time-consuming and difficult.

Docusaurus is a static site generator that provides various features for creating and maintaining documentation. It is an open-source project built and maintained by Meta. It has native support for React, markdown files (.md, .mdx), and document versioning. It also comes with pre-configuration for Algolia search and localization.

In this article, you will learn how to spin up a Docusaurus project and add an optimized image to your documentation through Cloudinary.

CodeSandbox & GitHub Repo

Get the complete demo for this article on CodeSandbox.

The source code is also available on Github.

Prerequisites

You do not need a lot of in-depth coding knowledge because Docusaurus is beginner-friendly. However, you should at least have:

Knowledge of writing markdown content in a .md or .mdx file
Basic understanding of creating and implementing React components
A Cloudinary account for storing and delivering your optimized images (Create a free one here)
Installation of Node.js on your computer should come with npx for spinning up a new Docusaurus project and npm for running the project

Create a Docusaurus Project

In your terminal, navigate to your preferred directory and run the command below:

1npx create-docusaurus@latest <project-name> classic

This command spins up a new Docusaurus project with your preferred <project-name> and a classic theme. For this article, the <project-name> is docusaurus-demo.

Wait for its dependencies to install. Please note that there is no progress bar indicator, so this stage’s process might look static, but it is installing:

After successfully installing the dependencies, you will see these messages below in your terminal:

Open the project folder in your preferred code editor to view its code, and run npm start in your project’s terminal to view it on localhost:3000.

On the header of your Docusaurus website, you will see the site name My Site, the documentation page Tutorial, and the blog page Blog. Click on Tutorial to view the documentation page.

Upload Images to Cloudinary

In your browser, open the Media Library tab in your Cloudinary dashboard and create a new folder:

Navigate into your new folder and upload your preferred images into it:

Take note of the public id of each image you upload:

For example, the public id of the sample image above is docusaurus-demo/photo-1648737155328-0c0012cf2f20_axwjc8 because you got the image from the docusaurus-demo folder you created in your Media Library.

Create a Custom Image Component

In your terminal, run the command below to install some Cloudinary packages for image optimization and transformation:

1npm i @cloudinary/url-gen @cloudinary/react

In your code editor, navigate to the src/components/ folder, create an OptimizedImage/index.js file and fill it with the code below:

1import React from 'react';
2import { AdvancedImage } from '@cloudinary/react';
3import { Cloudinary } from '@cloudinary/url-gen';
4import { scale } from '@cloudinary/url-gen/actions/resize';
5
6export default function OptimizedImage({ publicId }) {
7  const cld = new Cloudinary({
8    cloud: {
9      cloudName: '<CLOUDINARY_CLOUD_NAME>',
10    },
11  });
12
13  const myImage = cld.image(`${publicId}`);
14
15  myImage.quality('auto').format('auto').resize(scale().width(480));
16
17  return (
18    <div>
19      <AdvancedImage cldImg={myImage} />
20    </div>
21  );
22}

In the code above, you did the following:

Imported AdvancedImage component from @cloudinary/react and Cloudinary from @cloudinary/url-gen
Created an OptimizedImage component that takes publicId as its prop
Initialized a new Cloudinary variable with your cloud name as its parameter
Created a myImage variable which gets an image from Cloudinary through its public id
Optimized myImage with transformation settings from Cloudinary
Added myImage to the <AdvancedImage /> component

Import Custom Image Component

In your docs/ folder, update intro.md with the code below:

1---
2sidebar_position: 1
3---
4import OptimizedImage from '../src/components/OptimizedImage';
5
6# Tutorial Intro
7Let's discover **Docusaurus in less than 5 minutes**.
8
9## Optimized Image
10<OptimizedImage publicId="docusaurus-demo/photo-1648737155328-0c0012cf2f20_axwjc8" />

Here, you imported the OptimizedImage component and added your Cloudinary image’s public id. On your browser, this will be the result:

Conclusion

In this article, you learned how to spin up a documentation website using Docusaurus quickly and add an optimized image to it using Cloudinary. If you want to explore how to use Docusaurus or Cloudinary, check out the helpful resources below.