Skip to main content

· 3 min read
Faycal Alami-Hassani

This is the first time that I am facing issues with unmet dependencies in Docusaurus after a Yarn Upgrade.

What is Docusaurus?

Docusaurus is an SSG (short for Static Site Generator). Static Site Generators are software frameworks that generate static HTML webpages using templates, components, and plain-text files.

The plain-text files make use of markup languages such as Markdown. Since there are neither databases nor dynamic content involved, the static HTML files load pretty fast.

There are many SSGs on the web to choose from. Docusaurus, Hugo, and Eleventy are just some of the most famous ones among them. It is up to you to select the brand that best suits your needs.

Docusaurus offers some very interesting features, including:

  • versioning capabilities
  • contextual and faceted navigation based on a integrated search engine
  • built-in support for the standard file format MDX, which allows you to embed the JavaScript extension syntax JSX into your Markdown

These and other features make it a great fit to create beautiful static documentation sites.

What is Yarn?

Yarn is a JavaScript package manager that was developed to address some shortcomings of its predecessor npm, the default package manager for Node.js.

Packages, Manifests, and Package Managers

Developers use packages to share their code. In addition to the actual code, each package contains a manifest file, also called package.json.

The manifest file describes the package itself using a lightweight data-interchange format called JSON (JavaScript Object Notation).

Here is an excerpt of a manifest:

{
"name": "@anycli/manifest-file",
"description": "base json file wrapper used inside anycli",
"version": "0.3.9",
"author": "Jeff Dickey @jdxcode",
"bugs": "https://github.com/anycli/manifest-file/issues",
"dependencies": {
"cli-ux": "^3.3.13",
"debug": "^3.1.0",
"fs-extra": "^5.0.0",
"load-json-file": "^4.0.0",
"lodash": "^4.17.4",
"proper-lockfile": "^3.0.2"
}

Source code available on GitHub under: oclif / manifest file

A package manager relies on the manifest to determine the properties of each specific package, e.g. name, version, and dependencies.

To avoid any future conflicting packages in your project, you are better advised to select a specific package manager right from the start and stick to it.

If you want to learn more about the differences between yarn and npm, I suggest you read the following article: npm vs. yarn: Which Package Manager Should You Choose?

Troubleshooting Yarn Upgrade in Docusaurus

Yesterday, I got a warning message prompting me to upgrade Yarn while I was testing Docusaurus on my local development environment.

After running the upgrade with the following command:

$ yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest

I got several warning messages regarding unmet peer dependencies:

$ warning "@docusaurus/core > react-dev-utils > fork-ts-checker-webpack-plugin@6.5.0" has unmet peer dependency "typescript@>= 2.7".
$ warning "@docusaurus/preset-classic > @docusaurus/theme-search-algolia > @docsearch/react@3.0.0" has unmet peer dependency "@types/react@>= 16.8.0 < 18.0.0".

To resolve the issue, I had to install the latest versions of the following packages inside my project:

$ yarn add typescript@2.7.2
$ yarn add "@types/react@>= 16.8.0 < 18.0.0"

Once the installation has completed, I wanted to make sure that the problem was resolved, so I regenerated the content with the command:

$ yarn run build

Then I used the following command to test my build locally:

$ yarn run serve

That's it! Everything is working fine now ☀️.

Copyright © GlobalTech Translations 2022.

· 2 min read
Faycal Alami-Hassani

Besides having some external accounts on federated social networks such as Mastodon, I am also running my own instances on a VPS sever for my digital company.

One of these instances is dedicated to GNU Social, a social communication software for public and private communications. GNU Social is an old, but robust platform that supports the protocols OStatus and ActivityPub.

Fediverse - Federated Social Networks
Picture by Eukombos on Wikimedia Commons under CC BY-SA 4.0 license

GNU Social comes with some default stable themes. However, the look and feel of those themes is very 90's to me. If you want to give your GNU Social instance a brand-new look, you can use something more exciting such as Qvitter.

I am very happy with Qvitter and its intuitive design. Nevertheless, I wanted to customize the initial welcome text that appears on the main page:

We are a federation of microbloggers who care about social justice and solidarity and want to quit the centralised capitalist services.

Initial Welcome Text on GNU Social&#39;s Main Page

To modify the text indicated above, go to your site root directory, then navigate to the folder locale under the following path:

$ cd plugins/Qvitter/locale 

Once in the locale folder, open the file en.json with your preferred text editor. In this case, I am using nano:

$ sudo nano en.json 

Look for the line that starts with welcomeText, or use the shortcut Ctrl-W in your terminal to search for the text if you are using nano.

Replace with the text you would like to see on your welcome screen, then save and close your file. 😎 The result should look like this:

New Welcome Text on GNU Social&#39;s Main Page

If you want to learn more about the fediverse, you can also read my other blog article on the topic: Random Thoughts About the Federation/Fediverse.

Copyright © GlobalTech Translations 2022.

· 4 min read
Faycal Alami-Hassani

In localization, RTL (Right-to-Left) refers to languages that read from right to left, such as Arabic and Hebrew.

As someone who grew up in a bilingual environment, i.e. Arabic and French, making the difference between languages with opposite script directions is the most natural thing in the world. That being said, I recently had an amusing incident that I would like to relate here.

Labyrinth and directions
Picture by the Electronic Frontier Foundation under CC BY 2.0 license

It all began when I attended a webinar about the role of pictures in intercultural communication some weeks ago. The speaker, who was using a Japanese brochure to illustrate an example of non-Latin scripts, started talking about RTL languages and confusing both directions, which in fact are opposite to each other.

During five minutes that seemed like an eternity, our speaker kept using the acronym RTL to refer to a Right-to-Left layout while erroneously telling the audience that RTL was an acronym for Left-to-Right.

RTL or LTR
Right-to-Left or Left-to-Right? Help is on the way!
Picture by Wikimedia Commons under CC BY-SA 3.0 license

To my surprise, nobody from the attendees called his attention to the mistake. It seemed like the participants had the autocorrect function turned on in their brain, correcting by themselves the inaccurate information.

So, what about the Japanese language? Is it an RTL or an LTR script? Well, both answers are true. 😎 In Fact, you can write Japanese in both directions depending on the writing system you are applying:

  • Tategaki (vertical writing): starting at the top of the right-hand column, then moving to the next vertical column on the left;
  • Yokogaki (horizontal writing): from left to right like European Romance languages.

If you are curious to know more about the reading direction in Japanese, I suggest you read the article Is Japanese Read from Right to Left or Left to Right? by Team Japanese.

Getting back to our presentation, it was quite interesting, but it had some flaws from the intercultural standpoint. Allow me to explain why.

At a certain stage of the presentation, the speaker showed an antique artwork from the Arab-Islamic World, and pointed out that artists from the aforesaid region used ornaments because drawing human beings is not allowed for religious reasons.

While it is partly true that artists from the Arab-Islamic World have used biomorphic design at a later stage as an integral part of their artwork (e.g. use of vegetal shapes and forms, also known as al-Tawrīq), the major part of these artistic creations is based on calligraphy and geometry by deriving patterns from basic geometric shapes, such as circles and squares.

A little introduction to this topic is the article Geometry - The Language of Symmetry in Islamic Art by Richard Henry.

The second shortcoming in the presentation consisted in the examples used to reflect cultural differences in technical documentation.

It was striking to see that the examples were too ethnocentric, to say the least. Judging by the names appearing in the attendees list, I presume that I was the only non-European in the meeting room.

Personally, I think that the choice of the examples was an unfortunate faux pas. The supporting materials would cause real indignation among the attendees if the presentation were to be held in front of a non-European audience (e.g. in an Asian or African country).

Dear speaker, you are shooting yourself in the foot with such examples. If you have any non-European students, ask them for their input. You may need to adapt your content as soon as possible to avoid any misunderstandings with international audiences.

After all, your presentation is supposed to address intercultural challenges in technical communication.

Copyright © GlobalTech Translations 2022.

· One min read
Faycal Alami-Hassani

Docusaurus blogging features are powered by the blog plugin.

Simply add Markdown files (or folders) to the blog directory.

Regular blog authors can be added to authors.yml.

The blog post date can be extracted from filenames, such as:

  • 2019-05-30-welcome.md
  • 2019-05-30-welcome/index.md

A blog post folder can be convenient to co-locate blog post images:

EFF Data Privacy
Picture by the Electronic Frontier Foundation under CC BY 2.0 Licence

The blog supports tags as well!

If you don't want a blog: just delete this directory, and use blog: false in your Docusaurus config.