Some tips and tricks when written articles for Docusaurus

If you're writing for Docusaurus, there are a few tips to know.

This article is by no means exhaustive, but for me, it's a reminder of the features that are really essential and must not be forgotten. Two more authoring habits worth adopting early: keeping your tags under control and displaying related posts below each article.

Read more​

Official documentation

In blog mode, your article is divided into two parts: the introduction with a Read More link, and then the main part of the article.

To activate this feature, simply add the line <!-- truncate --> (preceded and followed by an empty line) where you wish to distinguish between the introduction and the main part.

If you go to my blog page, each article has an introduction followed by a <!-- truncate --> line in my Markdown source.

Admonitions​

Official documentation

Used to highlight a paragraph in your document, f.i. a Pay attention to... or Tip: Did you know that... box.

<AlertBox variant="caution" title="Pay attention to...">
Never give your bank card code to a stranger.

</AlertBox>

Will be displayed by Docusaurus like this:

Inline style​

Docusaurus supports inline style by the use of a <span> ... </span> notation.

The notation <span style={{color: 'blue'}}>I'm written in blue</span> will give I'm written in blue.

Used very occasionally, this is a very simple way of changing the style of content on your page.

Highlight component​

If your ambition is to highlight some text, there is a better solution: the Highlight component.

Please create the src/components/Highlight/index.tsx file:

/**
 * Highlight Component
 *
 * A simple React component used to emphasize inline content with a custom background color.
 * Typically used in blog posts or documentation pages within a Docusaurus site.
 *
 * Example usage:
 * <Highlight color="#ff4081">Important note</Highlight>
 */

import type { JSX, ReactNode } from "react";?

interface Props {?
  children: ReactNode;
  color: string;
}

export default function Highlight({ children, color }: Props): JSX.Element {?
  return (
    <span
      style={{?
        backgroundColor: color,
        borderRadius: "2px",
        color: "#fff",
        padding: "0.2rem",
      }}
    >
      {children}
    </span>
  );
}

Then edit (or create) the src/theme/MDXComponents.js file. If the file already exists, just add the highlighted lines below. If not yet present, create the file with the content below:

import React from "react";

import MDXComponents from "@theme-original/MDXComponents";

// [...]

import Highlight from "@src/components/Highlight";

export default {
  // Reusing the default mapping
  ...MDXComponents,

  // [...]

  Highlight
};

Docusaurus green and Facebook blue are my favorite colors.

Source: MDX and React

Highlight lines​

Official documentation

The // highlight-next-line is really useful when you wish to put in evidence changes you've done to a give code block. When the code lives in a real file rather than inline, I use my own code snippets component, which reads the file at build time so the article can never fall out of sync with it.

Imagine you've already written something like Dear reader, please create a file on your disk with this content... and you provide a code block with that content.

Later in your article, you ask 'Please edit the file and make this and please edit the file and add this and that line, here and there.

With // highlight-next-line, it's really easy to highlight changes, for instance:

name: kingsbridge

services:
  joomla:
    image: joomla
    restart: always
    ports:
      - 8080:80?
    environment:
      - JOOMLA_DB_HOST=joomladb
      - JOOMLA_DB_PASSWORD=example
    # highlight-next-line
    user: 1000:1000?
    # highlight-next-line
    volumes:
      # highlight-next-line
      - ./site_joomla:/var/www/html?

  joomladb:
    image: mysql:8.0.13
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=example
    # highlight-next-line
    user: 1000:1000?
    # highlight-next-line
    volumes:
      # highlight-next-line
      - ./db:/var/lib/mysql?

You can immediately see where I've made some changes in the file's content.