Skip to main content

Site creation

ยท 7 min read
Markdown, WSL and Docker lover ~ PHP developer ~ Insatiable curious.

Creation of this blog

  • Updated 2023-11-03, search engine, prism and sitemap added.
  • Updated 2023-11-05, adding giscus.
  • Updated 2023-12-21, adding giscus.json to allow comments to be displayed only on the blog.

Here are the steps I followed to create this blog.

Using Docusaurusโ€‹

Since I really like the simplicity of Docker, I will not install NodeJs on my machine but use the official Docker image

docker run --rm --name blog --user $UID:$GID -it -v ${PWD}/:/project -w /project node /bin/bash

The instruction here above will download NodeJs (the latest version) on my machine if not yet present and create a running instance (called a container of it). The flag --user $UID:$GID is used to start the container using the same credentials than my local one (i.e., reuse my local Unix christophe user so files/folders created in the container will be owned by my local user).

The -v ${PWD}/:/project command line argument will share my current folder on my computer with the container i.e., the /project folder in the container will be my current folder on my computer.

And finally, I run an interactive shell since I have mentioned /bin/bash as entry point.

Now that I have a prompt in the container, I will create my blog using Docusaurus (as explained in the official documentation).

npx create-docusaurus@latest blog classic

After a long time, the blog folder is created and I can take a look on his content:

โฏ tree -d -L 1
โ”œโ”€โ”€ blog
โ”œโ”€โ”€ docs
โ”œโ”€โ”€ node_modules
โ”œโ”€โ”€ src
โ””โ”€โ”€ static

The installation step is now finished, I will exit the container and return to my computer, to do this, from the Docker console, I just type exit.

Run the websiteโ€‹

Back to my computer, I will now go inside my blog folder (cd blog) and run the Docker command again but this time with the -p 3000:3000 extra parameter. This parameter will expose the port 3000 from the container with my machine so I can see the website by surfing to http://localhost:3000.

Instead of running an interactive shell session I prefer to run /bin/bash -c "npx docusaurus start" to run Docusaurus watcher and serve my files:

cd blog
docker run --rm -it --name blog --user $UID:$GID -v ${PWD}/:/project -w /project -p 3000:3000 node /bin/bash -c "npx docusaurus start --host"

After a few seconds, the container is ready to use and I surf to my site by going to http://localhost:3000.



It is really crucial to use the --host flag when calling npx docusaurus start. This will allow external access to the website. If missing, surfing to http://localhost:3000 (or running curl will display an error Empty reply from server.

Some settingsโ€‹

By default (using the standard installation), Docusaurus will create a skeleton of website having two main entries: a blog and a tutorial.

For keeping things manageable, I will only keep the blog and remove the tutorial part. For this, I have followed this official article:

Now, I can remove the /docs folder from my blog directory:

โฏ tree -d -L 1
โ”œโ”€โ”€ blog
โ”œโ”€โ”€ node_modules
โ”œโ”€โ”€ src
โ””โ”€โ”€ static

I will also make some changes to files like docusaurus.config.js or blog/authors.yml to fit my needs.

File docusaurus.config.jsโ€‹

By setting hideOnScroll to true, the navigation bar will be hidden when the user will scroll down but will be displayed back as soon as he scroll up. Idea is to give more place on the screen for the content.

export default {
themeConfig: {
navbar: {
// auto-hide the navbar when the user will scroll down, show again when scroll up
hideOnScroll: true,

Define the default image for social media:

export default {
themeConfig: {
// Default image when sharing a post on social media
image: 'img/social-card.jpg',

Make my first articleโ€‹

With my preferred editor (vscode) I open my blog website (I just type code . in my Linux console to open my blog project).

Now, in the /blog directory, I create a new folder called 2023-11-02-site-creation and there I create the file.


When my blog post only contains text and no images or linked files, I can just create a .md file like /blog/ The creation of a folder is thus not mandatory at all.

In the previous chapter, npx was executed using the docker run --rm -it --name blog --user $UID:$GID -v ${PWD}/:/project -w /project -p 3000:3000 node /bin/bash -c "npx docusaurus start --host" command so, every changes done to the blog will be immediately synchronized with Docker i.e., I just need to save my article and npx will reload my site; very easy and convenient.

Using some layoutsโ€‹

Docusaurus support some Markdown special tags called admonition (see

For instance, to display a paragraph as a tip, like below, just use the following syntax:

Some **content** with _Markdown_ `syntax`.

Some content with Markdown syntax.

To get the entire list of supported features, read Markdown Features.

Adding pluginsโ€‹

Search engineโ€‹

The search engine feature has been added by following this blog article:

Added by running yarn add @cmfcmf/docusaurus-search-local in the Docker container (opened using make bash).

Support for PHP and bash in prismโ€‹

Added by running yarn swizzle @docusaurus/theme-classic prism-include-languages in the Docker container (opened using make bash). Read more at Supported Languages.

Sitemap generatorโ€‹

Added by running yarn add @docusaurus/plugin-sitemap in the Docker container (opened using make bash).

When added, I have also manually created the static/robots.txt file to with this content:

User-Agent: *
Disallow: /*index.xml$
Disallow: /index.json
Disallow: /search/index.json

Image pluginsโ€‹

Added by running yarn add @docusaurus/plugin-ideal-image in the Docker container (opened using make bash). Read more at Supported Languages.

Added by running yarn add docusaurus-plugin-image-zoom in the Docker container (opened using make bash).

Adding a comment areaโ€‹

How to add Giscus comments to Docusaurus

Adding Giscus to allow comments and feedback.

Push to Githubโ€‹

On, I have created a new repository called blog ( This done, back to my console and I run a few git commands:

git init
git add .
git commit -m "Initial commit"
git remote add origin
git push -u origin master

This done, I have thus pushed my files to Github as foresee by Docusaurus i.e., for instance, the /node_modules is not part of my repo; which is fine since we will create that folder later by running some npx command on the web server where the site will be hosted.

Build static version of the blogโ€‹

In order to build static pages, I run docker run --rm -it --user $UID:$GID -v ${PWD}/:/project -w /project node /bin/bash -c "yarn build".

This will create/update the /build folder with a fresh version of the site.

Next step is to start my FTP client (which is WinSCP) and copy my local /blog/build folder to my remote website.

Adding withcabin for GPDR compliant statsโ€‹

By adding the lines below to the docusaurus.config.js as child node of const config, I'm injecting a script into the body part. This will then allow GPDR compliant stats on

scripts: [
src: '',
async: true,
defer: true,

Note: the script is only injected to pages after a yarn build i.e. when the static site is rendered; not during a yarn watch.