Skip to main content

Some tips and tricks when written articles for Docusaurus

ยท 2 min read
Christophe

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.

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 articles have 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.

:::caution[Pay attention to...]
Never give your bank card code to a stranger.
:::

Will be displayed by Docusaurus like this:

Pay attention to...

Never give your bank card code to a stranger.

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 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.

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:

version: '3.9'

name: kingsbridge

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

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

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