Madrus's Webdings Blog

Implementing Right-to-Left (RTL) Support in a Tailwind CSS React Application

2025-06-16T00:00:00.000Z

TL;DR I was developing a project for my friends when we started discussing which languages to support. "It would really be great if we had Arabic!" they said. That's when I realized I'd never dealt with Right-to-Left (RTL) languages before - and honestly, it felt a bit intimidating at first. But hey, we love a good challenge, right?

Building a web application with RTL support requires more than just translating labels and text - it requires adapting the entire user interface to be able to swap text directions. This article describes the key changes I made to seamlessly supports both LTR and RTL language like Arabic. Spoiler alert: it's actually quite doable with Tailwind CSS!

Understanding the Challenge

When adding RTL support to an existing LTR application, we need to consider:

Text direction: Content flows from right to left
Layout mirroring: UI elements should mirror horizontally, including paddings, margins, and positioning (left/right properties need to swap)
Icon placement: Icons and interactive elements should also be repositioned inside their containers
Typography: Different fonts and sizing may be needed for optimal readability
Form inputs: Input fields and labels need proper alignment

Compare the following two screenshots:

LTR Layout

RTL Layout

Setting Up the Foundation

1. RTL Utility Functions

The first step is creating utility functions to detect RTL languages and provide direction-aware helpers:

// app/utils/rtlUtils.ts
export const isRTL = (languageCode: string): boolean => ['ar'].includes(languageCode)

export const getDirection = (languageCode: string): 'ltr' | 'rtl' =>
  isRTL(languageCode) ? 'rtl' : 'ltr'

export const getTypographyClass = (languageCode: string): string =>
  isRTL(languageCode) ? 'text-arabic' : ''

Key Benefits:

Centralized language detection
Type-safe direction handling
Easy to extend for additional RTL languages

HTML Direction Attribute

2. Setting the `dir` Attribute on the HTML Tag

The dir attribute must be set on the root HTML element to enable browser-level RTL support. This is the foundation of everything else. When you set dir="rtl" on the tag, the browser automatically:

Changes the default text direction from left-to-right to right-to-left
Flips the document flow (scrollbars appear on the left side)
Enables CSS logical properties to work correctly
Provides the proper context for screen readers and accessibility tools

Without this attribute, your CSS changes alone won't create a proper RTL experience. So, we can add it like this (e.g. in Remix or React Router 7 project):

// app/root.tsx
return (
  <html
    lang={language}
+   dir={getDirection(language)}
    className='h-full overflow-x-hidden'
  >
    <head>...head>
    <body>...body>
  html>
)

3. Dynamic Direction Updates

For single-page applications, the direction needs to update when the user switches languages. We can control that dynamically with direction attribute and typographyClass helper:

Click to see the full implementation code

Add Disqus Comments to Docusaurus Blog Posts in 2025

2025-05-20T00:00:00.000Z

TL;DR In my previous, now archived, article Add Disqus Comments to Docusaurus Blog Posts (archived) in 2021, I have discussed how to add the Disqus blog comments to a Docusaurus blog. At the time, Docusaurus was in the beta of v2.0.0, React was in v17, and I have used the JavaScript version of swizzling. But the trick I used gained some attention and there were several very inspiring comments, which you can see there. Unfortunately, due to my personal situation I have not acted on them. Until now!

UPDATED May 23, 2025

In this article you can read how Disqus comments can be added today, in 2025 using the latest and the greatest Docusaurus 3.8.0, React 18 or 19, and TypeScript instead of JavaScript. Of course, if your project needs JavaScript, you can just omit the types.

Let's Go

Prerequisites

Here's what you'll need to get started:

your project must be running Docusaurus v3 with at least one blog post;
you have installed your project using theme-classic
a terminal session open in the root of your project;
an account with Disqus with your registered Docusaurus web-app.

Install disqus-react and @docusaurus/plugin-content-blog:

pnpm add disqus-react @docusaurus/plugin-content-blog
# or
npm add disqus-react @docusaurus/plugin-content-blog
# or
yarn add disqus-react @docusaurus/plugin-content-blog

If you need some guidance on Disqus weblog registration, see my Register Your Weblog with Disqus section below.

Prepare the Frontmatter

Run your Docusaurus project locally running either yarn start or npm run start in your terminal. Browse to http://localhost:3000/blog and make sure you see at least one blog post. Choose one of them to work with.

Open the chosen blog post file in your editor of choice and add the following lines in the frontmatter:

---
slug: your-blog-post-slug
...
draft: true
comments: true # for Disqus
isBlogPostPage: true
---

The slug should be unique between different blogposts.
Keep draft value as true until you know for sure everything works fine. What it does is that it lets you see your post while running Docusaurus on localhost but not on the published website. When you are ready, set it to false or remove completely from the frontmatter.
The comments property lets you decide for each blog post if you want your visitors to be able to leave comments. In most cases, you can omit it or set it to true--the comments section will be present by default. Set it to false if you don't want any Disqus comments underneath your blog post.
isBlogPostPage is a hack. It is necessary for each blogpost with comments set to true. It seems like a duplication for the comments property but it plays a different role. Without it, the comments are visible and can be placed underneath the short form of the article on the /blog url.

Swizzle the BlogPostItem component

Swizzling a Docusaurus component means either adding a wrapper for or including the source code of a core component into your project. This allows us to customize the component's functionality. The application will then use the swizzled and customized version of the component instead of the standard one. In our case, we will be using swizzling to add the Disqus comments on our blog post pages.

Following the tip about adding comments on the Swizzling page, let us wrap the BlogPostItem component. Run the following command and accept the warning about the risks:

pnpm run swizzle @docusaurus/theme-classic BlogPostItem --danger
# or
npm run swizzle @docusaurus/theme-classic BlogPostItem --danger
# or
yarn swizzle @docusaurus/theme-classic BlogPostItem --danger

Choose TypeScript and then Wrap.

DiscussionEmbed

Open the index.tsx file inside src/theme/BlogPostItem and let us add our custom code. I have followed the instruction from the disqus-react repository. Also, applied the hint of pjnovas (a huge round of applause! 👍), which you can find in the discussion hereunder.

Replace the contents of the swizzled src/theme/BlogPostItem/index.tsx with the following code:

src/theme/BlogPostItem/index.tsx
import { useBlogPost } from '@docusaurus/plugin-content-blog/client'
import useDocusaurusContext from '@docusaurus/useDocusaurusContext'
import BlogPostItem from '@theme-original/BlogPostItem'
import type { Props } from '@theme/BlogPostPage'
import { DiscussionEmbed } from 'disqus-react'
import React from 'react'

export default function BlogPostItemWrapper(props: Props): React.ReactElement {
  const {
    metadata: { frontMatter },
    isBlogPostPage,
  } = useBlogPost()
  const { comments = true, slug, title } = frontMatter
  const identifier = slug.split('-').join('_')
  const { siteConfig } = useDocusaurusContext()
  const baseUrl = siteConfig.url + siteConfig.baseUrl
  const url = `${baseUrl}blog${slug}`

  return (
    <>
      <BlogPostItem {...props} />
      {isBlogPostPage && comments && (
        <DiscussionEmbed
          shortname='your-short-name'
          config={{
            identifier,
            language: 'en_US',
            title,
            url,
          }}
        />
      )}
    >
  )
}

And replace the contents of the index.d.ts file:

src/theme/BlogPostItem/index.d.ts
/// 
/// 
import type { Props } from '@theme/BlogPostPage'

export default function BlogPostItemWrapper(props: Props): React.ReactElement

If your web application has been properly registered with Disqus, you should see the Disqus comments appear under every blog post. Once you got it working locally you may set draft: false in the frontmatter or remove the setting completely and publish your project. The comments block will be there as well.

caution

The comments you add when testing your website locally do not synchronize with the comments of the same deployed page.

DO NOT CHANGE YOUR SLUGS

Be careful with changing slugs. Your existing comments are connected to it. If you change the slug, you will loose them. If that happens, just restore the old slug.

CommentCount and CommentEmbed

Using the disqus-react code snippets for CommentCount and CommentEmbed it is also possible to add those to your Docusaurus project in a similar manner.

Final Observations

While swizzling is handy, it is still some sort of a patch or workaround. So, if Docusaurus in some future release changes the code or signature of the component, you will probably need to swizzle the new version of the component as well as reapply the patch described here. This has already happened to me once with the BlogPostPage component.

Also, the Docusaurus CLI also evolves. In 2.0.0-beta.16, I was ejecting the complete BlogPostPage component and changing the core code inside. Then in January 2022, there came the --wrap option. Today, in 2025 it did not work for me either, so I used the --dangerous one 😄.

Ultimately, adding a comments section via Disqus is more than just a technical implementation; it's about building a vibrant community around your Docusaurus blog. Docusaurus, a robust and well-designed documentation framework, makes this customization possible, providing a clear path to achieve that in 2025 and ensuring your readers have a platform to engage, ask questions, and contribute, even as the framework evolves. Empower your readers to connect with your content today.

Knowledge Sharing, the Missing Part

2022-07-05T00:00:00.000Z

TL;DR Knowledge is the meat of IT companies. Know-how, architecture, software and DevOps technologies, data, etc. When experienced employees leave, they take their knowledge and experience with them. New employees are hard to find and need time before they learn the skills enough to fill that gap. This poses considerable risks for the continuity and efficiency of any high-tech company and its ability to stay relevant and competitive on the modern market of IT-services. So, knowledge sharing should be very important for IT companies, right? Right.

And what about us, developers? Is our primary motivation in life keeping afloat the company that employs us? You bet it's not! For most of us, especially young and ambitious, it is much much more personal. Apart from a good salary, it could be fun at work, exciting and challenging tasks, problem solving, professional growth by learning new technologies, being part of a great team, and of course keeping our families happy. If we fail to satisfy our personal needs as developers with the present company, how long will it take before we start looking for new opportunities? 😉

So, while knowledge sharing has become a crucial survival factor for each IT company, the question is: are we doing it right or is there anything important we are missing? My view is that while the formal knowledge sharing process within a company may be well organized, we often overlook something very important: the personal and social side of it and its impact on the efficiency of the development process.

This article applies to developers of any kind, frontend and backend, as all of them can profit from knowledge sharing. However, the Missing Part is probably more applicable to big enterprise level organizations than to small startup companies, which use those types of knowledge sharing techniques anyway.

IMPORTANT

In this blog post, when I talk about knowledge sharing I am primarily considering ways of doing it face to face. So, it is about meetings, meetups, training sessions, one on one sessions when people have live contact. It is not about individually reading articles and watching training videos to learn about some technical topic.

How do modern devs come about their knowledge? For trainees and junior devs the company can arrange courses related to their job where they can learn some fundamentals like React, TypeScript, C#, .NET framework, Java, and other such big subjects. The experienced senior devs are often able to find solutions even to very tricky issues just by googling. Because they know which search words to choose and they can quickly filter the search results using their vast experience.

The real issue arises in between those two categories, no beginners but also no experts:

the devs have insufficient knowledge of what is necessary or even possible
they lack full understanding of the issue at hand
there is no one to go to for immediate help

The answer to that issue is the knowledge sharing. This blog post is exactly about that.

Before we talk about the Missing Part, let us summarize more conventional ways of knowledge sharing that many companies use. All of them have one thing in common. They share the same mental model: GURU to ANYONE. This model means that one person, a GURU, who "knows it all" shares their knowledge with ANYONE, i.e. normal people who are usually much less experienced and/or lack that knowledge being shared with them.

Course Required by the Company (GURU to ANYONE)

This can be seen as an official technical course that every dev employed by the company should follow who does not have that knowledge yet but it is necessary for their daily work. The trainer is usually an external trainer hired by the company. It can be characterized by:

may be very expensive but the fees are paid by the company as a loan to the employee;
duration is from 1 day to 1 week;
usually instead of normal work, so participation should be confirmed by management;
certificate of participation at the end;
sometimes an exam and a professional certificate.

Internal Meeting (GURU to ANYONE)

This kind of meeting looks more like a normal meeting (on premise or online) of colleagues involved in the same project(s) or doing similar work. It can be characterized by:

regular 1 or 2 hours long team meeting;
meetup type online meeting for everyone interested in the topic(s) shared;
can have a form of a presentation or a workshop;
sessions can be recorded and saved somewhere for later access, also by other team members.

Help request (GURU to ANYONE)

This is usually a one on one session between a senior dev and a less experienced junior dev. It can be characterized by:

occurs strictly upon request of one of the team members;
knowledge sharing is strictly on the "need to know" basis and only for that particular team member who made the request;
the session can be recorded and saved somewhere for later access, also by other team members;
consequently: no request, no knowledge sharing.

Questions We Ask

In this conventional model, the need for knowledge sharing or decision to participate in a knowledge sharing session may arise from one of the following questions we ask ourselves:

Will I learn anything useful I don't know yet? Is it worth my time?
Is it relevant for my work? Will I be able to use it in my project(s)?
If I participate in that session, will I still make the deadline with my current task?
I got stuck in my current task, should I keep trying to find the solution myself or should I make a help request?

All these questions have something in common. They are focussed exclusively on our own gain only: "what's in it for me?" And that is exactly the borderline where the Missing Part comes in.

The Missing Part

Where the conventional model of knowledge sharing falls short is the personal growth of devs and the social implications of knowledge sharing. As we will see, these factors have huge impact on the productivity of devs, the quality of their code, their work satisfaction, creativity, which in fact give a company its competitive edge.

Questions We Ask

The questions we ask in the Missing Part are quite different from those above. They are much less about WHAT I CAN GET and much more about WHAT I CAN SHARE and HOW CAN I CHALLENGE THE STATUS QUO.

I am proud of this piece of my work, can I share it?
this piece of code is fun, can I share it?
this is a very tricky new technique I have used, it is important that my team members know about it. Should I arrange for a 15 minutes knowledge sharing session?
I don't feel comfortable about this piece of code but it is not located in the component I am working on, so formally I should not touch it. Can we at least talk about it?
why is our project structured as it is? I have read about other alternatives. Should I challenge the current solution?

Of course, this list of questions is not complete by far but it gives a good idea of the sort of considerations not touched by the conventional guru driven knowledge sharing model.

What we are missing

Different teams, different organizations, different ways of working. Here are some personal and social aspects of knowledge sharing. See for yourself, which of them are applicable in your specific team or company.

feeling of equality instead of inferiority, especially by junior devs or team members that previously had another specialty;
sense of growth and trust both personally by each team member and the team as a whole;
I have come across something new for myself or something strange, is it safe to ask a question and show my weakness?
what was my/your biggest challenge last week? how have I/you overcome it? if not, can I/you share it with the them/us?
as a (more experienced) dev, I know one of my team members is struggling with a difficult coding task. Should I check on how they are doing?

As you can see, these aspects have a lot to do with the safety feeling, caring about other team members and being taken care of if in trouble.

But wait, what does it have to do with the "continuity and efficiency of any high-tech company and its ability to stay relevant and competitive on the modern market of IT-services" we have mentioned above.

Impact of Missing the Missing Part

SKIP IF YOU LIKE

In this section, I will describe the potential negative impact of missing the Missing Part on the company. It is safe to skip the current section if you are only interested in my advice. Go straight to How the Missing Part Can Help.

Coding Efficiency

Inefficient coding process leads to more man-hours, higher costs and longer TTM (time to market) for the client. Many non-IT people like managers and product owners believe in a myth that practices like pair programming and knowledge sharing sessions are a waste of billable time. The former because the time spent in man-hours counts twice (two devs working 1 hour together means 2 man-hours), and the latter even more times (10 devs having a 1 hour knowledge sharing session means 10 man-hours with nothing tangible produced). Also, there seems to be the impression that pair programming means hours and days spent by two devs sitting together and staring at one screen.

Why does this myth exist? Primarily because dev work is seen as linear. Meaning that the managers' expectation is that spending twice as much time should produce twice the result (lines of code, tickets, etc.). As devs we know that this is not how we work! Software development requires time for thinking, reading, planning, googling, learning, discussing, and refactoring and does not consist only of routine repeatable work. 😃

Another myth is that having devs work each of them 100% on their own is more efficient. Although this can true to some extent for senior devs, it is hardly so for junior devs! The knowledge and experience of senior devs is vast enough to know in advance how to best tackle almost every task at hand. However, when a junior dev picks up a new task, they may face a number of uncertainties:

which technique to use? what are the options?
I have some vague idea how to go about it but is my method the right one?
do I know enough about this technique I must use it or should I spend more time learning it first?
if I fail to get the desired result quickly enough, how much time should I keep trying before I ask for help?
everyone else seems to be doing fine with their tickets, if I let them know I need help I will be the only one!

Let us consider the corresponding potential negative impact of these uncertainties on the Coding Efficiency in terms of time spent or waisted:

time spent on research of the possible options like trying to find similar piece of code in one of the other existing applications;
should the chosen approach finally prove to have been wrong, time has been wasted on the wrong approach;
if I don't know enough, I will first have to spend time to learn the new technique, and even then I still may get stuck when trying to implement it for the first time in my life;
and 5. time spent on trying to solve the task longer than necessary in desperate hope that will save me my face, so I will not have to admit I failed and had to ask for help.

Another negative impact is due to the time lost on fixing merge conflicts. Real massive time consuming issues can arise when large changes are uncontrollably merged into the code base while there are other open pull requests (PRs).

Code quality

Code quality is not only linting and formatting. Every programming language has its own tools to automatically take care of those. We are talking here about such notions as the code style, how clean and modular the code is, whether the S.O.L.I.D. principles are observed, and of course code testing. I strongly believe that it is practically impossible to always produce high quality code working 100% individually. The choices we make as devs while coding have to be reviewed and challenged by our peers. PR reviews are a good way to have some control on this but they may not be enough due to PR fatigue. Other devs don't always have enough time for thorough analysis, so they may unintentionally approve low quality code.

What is the impact of the low quality code for the company? Potentially it is a time bomb. Its negative effect can grow over time and manifest itself in worse performance, readability, maintainability and robustness. All of which leads to higher future maintenance costs as low quality code adds to the technical debt needing rework some time in the future.

Fun and Satisfaction @ Work

When devs are bored, don't get enough opportunities for professional growth, don't feel that their work is valued by the peers and the client, and become SCRUM tickets conveyor belt operators, they are more inclined to leave the company having found a more exciting and stimulating job, which many IT startup companies have to offer. Don't forget that enterprise level companies often have a lot of legacy code requiring the knowledge and the usage of outdated techniques.

Lack of knowledge sharing and positive feedback has considerable negative effect on devs, especially the junior devs. It may lead to stress, the feeling of being overwhelmed and having too much on their plate. This can happen when the task itself is unclear or it is unclear how to solve it from the technical point of view. Even bigger stress can arise when the "wrong path" has been chosen. Imagine being busy for a couple of days only to find out that one did the wrong things and the code must be completely rewritten! Or, even worse, it has now to be rewritten by a senior dev to fit into the current sprint. What a waist of energy and a huge disappointment for the first dev!

How the Missing Part Can Help

Let us now consider the positive impact of adding the Missing Part both on the company and on its employees. The effect is like that of spreading the wings, feeling that anything is possible and knowing for sure that it is.

Quite often, what we think of as knowledge sharing is actually just information sharing. These two notions are not one and the same (see, e.g., Information vs Knowledge: Key Differences). Information has more to do with presentation of facts and data and being informed about certain subject. Knowledge, on the other hand, while certainly is based on information, has more to do with learning and discovering process and being able to practically use it, either to make conclusions or to create, build something. In that respect, information is rather passive and knowledge is rather active.

The funny thing is that for one person, e.g. a senior dev when they tell about some difficult technique they have used, it is certainly their knowledge they are sharing. But if we look at it with the eyes of a less experienced junior dev, this knowledge can become just information. Imagine that this dev's level of prior knowledge, experience and understanding of the matter is insufficient to grasp the whole picture to say nothing of the small details. For this junior dev to use that technique, they would first need to study it or at least sit together with that senior dev and go through the whole process once again step by step.

If we now look again at the conventional ways of knowledge sharing described above as GURU to ANYONE type, we will see something interesting. Although those sessions may indeed be knowledge sharing for those participants who have similar level of prior knowledge, they are but information sharing for all the others. It would be utopia to expect those others to be able to use that information the next day as their knowledge. Maybe even to remember it!

A good example of this is a PR session. The whole team is looking at the code diffs between the old and the new state. For some team members, especially those who were at one time involved in that particular area, these diffs can be quite meaningful. For other team members it can be just loose bits of information giving them some very general idea about the change.

Mental Shift: GURU ⇒ ANYONE

This one is my favorite. 😃 Remember the conventional GURU to ANYONE mental model described above? Not every dev feels themselves as being a guru and thus have the urge to share their knowledge. If one looked through the history of the knowledge sharing sessions and the names of their presenters, one would notice that it is a small number of names that repeat many times each. Same devs make presentations. Other devs don't venture.

Let us make a shift to a different mental model: ANYONE to ANYONE. This shift makes all the difference in the world! Anyone here means any dev, no matter their level of knowledge and experience. So, according to this new model anyone can share their knowledge. What knowledge? A good question. We know that senior devs can share their knowledge. But what about all the others?

This new way of knowledge sharing requires a new way of listening on behalf of the team or colleagues. It requires a more supportive attitude. To illustrate this, I have put the differences in the following table:

Role	GURU to ANYONE	ANYONE to ANYONE
Presenter	- Is this subject interesting enough? - Does the company require it? - Will I score if I make this presentation?	- This new technique I learned is fun! - This difficult issue I solved was so tricky! - I see potential value for the team!
Listeners	- What's in it for me? - Do I need to know this? - The boss requires me to be present 😢	- Let us support our team member! - I know this topic, it's great to talk about it! - Are there any useful tips for the future?

As you can see, the new model is more oriented to support every team member in learning new things, solving difficult issues and telling others about their achievements so that the whole team can celebrate each step in their personal growth as a dev and a professional. And this applies to every team member from a newcomer to a veteran. Knowledge sharing does not have to be related to the application code only. Ik can be anything as long as the Presenter believes that their insights can contribute to the improvement of the team spirit, its efficiency, and professionalism.

Another important feature of it is that these knowledge sharing sessions can be very short and are similar to brainstorming. They can be short because sometimes all it takes to show is just a couple of lines of code or a small tip. Brainstorming follows a very important agreement: nothing is wrong! Meaning that no idea, no matter how crazy or impossible it is, is rejected. Rejection is forbidden! Same here. No matter what kind of idea, technique, tip, or achievement is presented, the team is excited as they witness a step in the professional growth of one of their team members. So, it does not matter if other team members already knew the subject before. These short sessions are always very positive and supportive.

Coding Efficiency

Let us consider several approaches that stimulate coding efficiency. We have already touched the myths around pair programming above (see Coding Efficiency). Let us now go into it in more details.

Pairing or Pair programming

Pairing or pair programming is not new. To remind you what it is all about, let me cite Martin Fowler, a great software guru, from his On Pair Programming article:

Pair programming essentially means that two people write code together on one machine. It is a very collaborative way of working and involves a lot of communication. While a pair of developers work on a task together, they do not only write code, they also plan and discuss their work. They clarify ideas on the way, discuss approaches and come to better solutions.

Opposite of what many people think about it, pairing does not necessarily mean that two developers are working on one machine all day long. Each of them can even work primarily on their own ticket but several times a day as necessary they get together for a short session, just a quarter of an hour in order to unblock, to plan, to discuss, or to challenge each other's progress.

Here is one of the possible scenarios:

Mark picks up a ticket from the SCRUM board and asks Emmy to be his second.
Emmy picks up another ticket from the SCRUM board and asks Steve (or Mark) to be her second (Steve does the same, etc.).
Mark and Emmy get together for 15 minutes to agree on the approach for Mark.
Emmy and Steve get together to agree on the approach for Emmy.
They repeat these sessions from time to time until the ticket is done, making sure
1. none of them is stuck for longer than 30 minutes
  1. if one of them does get stuck, they call their pair for help
  2. if that appears not enough, they both call a more experienced team member for help
2. the implementation matches the chosen approach
3. the code quality matched the requirements
4. the ticket is fully implemented
The ticket is ready for PR only when both devs are happy with it and are both prepared to defend its choices and its code in a PR session.
During the PR session it is the second dev who defends the PR and answers all the questions. Only then everyone can be sure that both devs fully understand the proposed change in the code.

In this way, each of the devs works more or less individually but the pair is ready at hand as a standby. By the time the ticket is done, both know everything about the approach, the choices, the reasons, the changes in plan, the motivations, the difficulties and the final code. None of them has got stuck for longer than 30 minutes at any time. It makes it a no-brainer to call for help, fun to plan and work, and the chance of following the wrong path is very low. In other words, this way of working is very efficient and produces high quality results.

It also does not matter who of the two is a more experienced dev. The less experienced dev gets a chance to learn from their more experienced pair. The more experienced one has to make sure that their pair has grown in their knowledge and is ready for PR questions. In a way, the more experienced dev becomes a short term coach for the less experienced one.

Crowd Programming (Hackathon like)

This is a variation of the pair programming technique, which I have personally experienced a couple of times. In three hours we have developed and deployed a fully functional prototype of a new CRUD API using C#.NET and MSSQL. It is especially great when a team starts on a new project completely from scratch.

Here is how it works. The whole team of 5-8 people goes to a separate location for several hours. That location has a wall TV mirroring the computer screen and a huge whiteboard. The team has two computers: one for the TV and another one for searching the Internet. There are three roles in the team:

The Coder is the dev who is writing code on the computer mirrored on the TV
The Assistant is the dev who is watching everything Coder is doing and is assisting him (typos, missing details, etc.)
The Thinkers are all the other members

The complete team starts by drawing the project diagram on the whiteboard until they have a good idea what they need to create. Then they choose the Coder and the Assistant and start the timer for 15 minutes. The Thinkers tell the Coder what to code watching the progress on the TV screen, the Assistant helps the Coder in minor details. If necessary, someone of the Thinkers searches for more clues on the Internet using the second computer.

When the timer stops, the Coder joins the Thinkers, the Assistant becomes the new Coder, and one of the Thinkers becomes the new Assistant. In this way, every team member takes turns in every role. The team may switch from coding to drawing and back again if and when necessary. Very intensive workflow, huge fun, and it quickly produces results on an MVP level.

What is maybe even more important, is that by the end of the session EACH of the team members knows EVERYTHING about the created product, its concept, design, model, code, database, and deployment, so no extra knowledge sharing is necessary after that. 😃 How exciting!

Merge conflicts

There are a couple of rules in regards to merge conflicts that can really save much time and increase work efficiency. The most important one is:

The devs from both sides of the merge conflict should be involved in the resolution process together to ensure the correct choices.

This saves time because these two devs have full knowledge of their changes. So none of them needs time to investigate the conflicting code from the other side trying to discern the code intent. This also saves a lot of frustration when later it appears that certain lines of code were wrongly removed or left behind. And then it saves the effort to fix those - well hidden - wrong merge choices.

Next rule:

Don't let PR's stay open for several days

When that happens with one PR while other PRs are being merged into the main code base, more and more merge conflicts are accumulating between the open PR and the main code base. So, the consequences described in the previous section become more and more severe. I pity the dev behind the PR staying open for a long time.

Finally:

When doing massive refactoring, make sure that that PR contains only refactoring and very few to no other changes. Let everyone else merge their PRs first, freeze new merges, help the refactoring PR dev solve the merge conflicts, then merge it a.s.a.p. After that everyone starts afresh from the fully refactored code base.

If you don't do it this way, your team may be facing a nightmare of merge conflicts by those devs who had started their feature branch before the refactoring PR has been merged.

Code Quality

A lot of what has been said in relation to the Coding Efficiency applies to the Code Quality as well. The most important factor here is the second opinion. As has already been said above, PR sessions are after the fact and it can be too late. When the ticket is done and there are many tickets and many PRs, the PR fatigue may kick in. Then it can become practically impossible for the other team members to dive deep enough in each of the PRs because of their sheer number and their own tickets. Especially if the project has to meet a very tough deadline. It can happen that a ticket is done and accepted although the code quality leaves something to desire. If that happens, that PR introduces a new piece of technical debt.

Whereas if each dev uses another dev as their pair, poor choices and poor quality code have much less chance to slip into the code base. And by the time the ticket goes to PR, there are two devs able to defend that ticket who know its every detail. At the same time, this serves as a great quality assurance step firmly built into the development process.

Fun and Satisfaction @ Work

When we agree that any dev is welcome to share any insight, whatever concern they might have had whether they are guru enough in a certain area for knowledge sharing, disappears. Every session becomes a celebration of a step in the growth process of some team member no matter junior or senior, By the way, doing a presentation is also a step in personal development. Which is very encouraging for each dev no matter their experience.

Regular short knowledge sharing sessions introduce a lot of excitement, pleasure and satisfaction in daily work. Sharing and learning become a new norm. Every dev learns new small tricks all the time, which makes it possible to immediately reuse some of them in their own work.

Imagine the kind of positive impact it can have on the employee turnover. The happy devs who a feeling that they grow as professionals and that they are part of a great team will stay longer! If the company ignores their need for professional growth and happiness at work, they may leave sooner. Then it may become a constant chore of spending time and resources trying to attract new devs and training them only to see them leave again in disappointment shortly after.

From Theory to Practice

Active Knowledge - Passive Knowledge = Action

The knowledge can be passive or active. When we first learn something, our knowledge becomes passive. It is more like information sharing. We have learned about something but we have not yet mastered it. We have seen things being done but we are not yet able to do it ourselves. Now, in order to make our new knowledge active we need to take action. Meaning to build something new based on it or to use it in some project or application we are currently working on.

If we don't, the risk is to forget what we have just learned. Every college or university student knows how quickly the theory is forgotten after the exam is passed! 😃 In order to make our new knowledge active and persistent, we must use it in our work.

I strongly believe that this gives the senior developers a very important coaching role in relation to other, less experienced, team devs. This coaching process may go through the following three phases:

SHOW - show the dev how something is being done (e.g., during the knowledge sharing session)
WATCH - do it together but let the other dev do it themselves under your supervision
REVIEW - let them do it completely by themselves and review the final result

NB. this technique is known in The Netherlands as doe voor, doe mee, doe zelf

In this way, the senior dev and the team can be 100% sure that the new technique has been really mastered by every team member.

Side Projects

Another exciting way of acquiring and mastering new knowledge is through side projects. These are small projects that are not part of our regular work nor projects. When we create an app after app after app for our clients, we tend to use the same techniques all the time. Copy&Paste from the previous app becomes the modus of operation. The risk is to get in a rut and bored. And then the devs start leaving the company...

Side projects give here a breath of fresh air. New ideas, new techniques, new frameworks, new tricks come out every day. It is impossible to learn all of them. Some of them may be potentially useful for our company but we don't know for sure. It is alto too risky to try them out on client projects. But what is possible, is to try things out on a micro side project using just that technique or trick or framework. The project should be small enough for a dev to finish it within a couple of days working primarily in their private time, e.g., in the evening or over the weekend. The results can be shared with the team in a knowledge sharing session. For the dev it is a new step in becoming a better professional, and the team may even get a new insight that can be used in the real project.

So, the dev is happy because they have learned something new = have grown professionally, and the team is happy at least for the same reason and maybe because of the new insights. Which in the end is also great for the company and its clients.

In Conclusion

In this blog post, I have demonstrated that the conventional formal knowledge sharing techniques are not enough any more if the company wants to stay relevant and competitive in the modern market. Modern developers, especially the good ones, want to have exciting work and stimulating working conditions. They need incentives to feel great about their work and it is up to the company if they get them. A good salary is not the only important incentive, maybe even not the most important. Having room for professional growth and being supported in their drive to grow, is extremely important for modern devs.

Knowledge sharing is capable to give the devs that great feeling if the Missing Part is taken care of and is not missing. They learn new things. they share them freely, other devs share back their discoveries. The new knowledge is being trained and used in side projects. The whole team is supporting and celebrating everyone's growth. If all that is in place who would even think of leaving such a wonderful company!!! 😃

References

For some interesting insights on knowledge sharing inside enterprise organizations, listen to this podcast show: Modern React with Paige Niedringhaus.
The Robert C. Martin's Clean Code Collection
Information vs Knowledge: Key Differences
Martin Fowler's On Pair Programming
Recently, I have come across an article of Carmo Braga da Costa How to Improve Knowledge Sharing In Your Engineering Org. (and beyond). She gives an interesting view on Knowledge Sharing from the organizational point of view. Read her view on Risks and her advice on improving the Knowledge Sharing. This bit is my favorite:

Putting your efforts into improvements takes away time from delivering things. But deprioritizing the dissemination of knowledge across teams can lead to complicated risks, which sooner or later will catch up with you.

Add Disqus Comments to Docusaurus Blog Posts (archived)

2021-01-09T00:00:00.000Z

TL;DR Recently I have switched from Jekyll to Docusaurus for my personal website. And immediately noticed the issue with letting the visitors place comments to blog posts. It seems that the comments work out of the box only for Facebook comments and then only if one has a registered FB business site (according to this PR). Searching on adding e.g. Disqus blog comments in Docusaurus brought back more questions than answers. (see some references at the end of this post)

The closest I could get to the solution was How to add forum to Docusaurus using Utterances comments via GitHub issues. I got the gist but the vendor binding was too big to my taste.

So, I have made my own go on this issue and finally succeeded in adding the Disqus blog comments to my Docusaurus blog. In this blog post you can see them in action and also read how I did it. I hope it might help some of you to do the same on yours.

UPDATED July 12, 2022

The code examples are compatible with Docusaurus 2.0.0-beta.16 and higher

Let's Go

Prerequisites

You will need the following things in place to have ready to get the job done:

your project must be running Docusaurus v2 with at least one blog post;
you have installed your project using theme-classic
a terminal session open in the root of your project;
an account with Disqus with your registered Docusaurus web-app.

Install disqus-react:

pnpm add disqus-react
# or
npm add disqus-react
# or
yarn add disqus-react

If you need some guidance on Disqus weblog registration, see my Register Your Weblog with Disqus section below.

Prepare the Frontmatter

Open the chosen blog post file in your editor of choice and add the following two lines at the end of the frontmatter:

---
slug: your-blog-post-slug
...
draft: true
comments: true # for Disqus
---

It is a good idea to keep draft value as true until you know for sure everything works fine. What it does is that it lets you see your post while running Docusaurus on localhost. But if you publish your branch to the web, this particular blog post won't be published and visible. When you are ready, you can set it to false or remove completely from the frontmatter.

The second comments property lets you decide for each blog post if you want your visitors leave comments. Set it to false and there will be no Disqus comments section underneath your blog post. Without this property or with it explicitly set to true the comments section will be present by default.

Swizzle the BlogPostItem component

Following the tip about adding comments on the Swizzling page, let us wrap the BlogPostItem component. Run the following command and accept the warning about the risks:

pnpm swizzle @docusaurus/theme-classic BlogPostItem -- --wrap
# or
npm run swizzle @docusaurus/theme-classic BlogPostItem -- --wrap
# or
yarn swizzle @docusaurus/theme-classic BlogPostItem -- --wrap

If your project uses TypeScript, add an extra --typescript flag at the end of the command line. This will copy the TypeScript version of the component and its index.d.ts types file.

DiscussionEmbed

Open the index.js file inside and let us add our custom code. I have roughly followed the instruction from the disqus-react repository but changed the code a bit to include the comments property and to add the missing details of integration with Docusaurus.

Replace the contents of the swizzled src/theme/BlogPostItem/index.js with the following code:

/src/theme/BlogPostItem/index.ts
import React from 'react'
import { DiscussionEmbed } from 'disqus-react'
import { useBlogPost } from '@docusaurus/theme-common/internal'
import BlogPostItem from '@theme-original/BlogPostItem'

export default function BlogPostItemWrapper(props) {
  const { metadata } = useBlogPost()
  const { frontMatter, slug, title } = metadata
  const { comments = true } = frontMatter

  return (
    <>
      <BlogPostItem {...props} />
      {comments && (
        <DiscussionEmbed
          shortname='your-disqus-shortname'
          config={{
            url: slug,
            identifier: slug,
            title,
            language: 'en_US',
          }}
        />
      )}
    >
  )
}

caution

The comments you add when testing your website locally do not synchronize with the comments of the same deployed page.

DO NOT CHANGE YOUR SLUGS

Be careful with changing slugs. Your existing comments are connected to it. If you change the slug, you will loose them. If that happens, just restore the old slug.

CommentCount and CommentEmbed

Using the disqus-react code snippets for CommentCount and CommentEmbed it is also possible to add those to your Docusaurus project in a similar manner.

Final Observations

While swizzling is handy, it is still some sort of a patch or workaround. So, if Docusaurus in some future release changes the code or signature of the component, you will probably need to swizzle their new versions. Meaning that you will also need to reapply the patch described here.

This has already happened in Docusaurus 2.0.0-beta.16. In the initial version of this article in January 2021, I was ejecting the BlogPostPage component and changing the core code inside. At that time, there was no wrapping option. Then in January 2022, Sébastien Lorber, one of the maintainers of Docusaurus, posted this comment:

Docusaurus maintainer here, thanks for the blog post. Note that in 2022 and for the v2 release we'll improve and make this easier to add comments.

Basically, instead of copying internal implementation details, you'll just "wrap" an existing component (like BlogContent) to add your comment system just under https://docusaurus.io/docs/...

We are working on a new "docusaurus swizzle --wrap" CLI to encourage this pattern, and thinking about good component granularity so that this pattern can be useful to solve many use-cases

Thanks to Sébastien, I have used this new wrapping option and updated the blog post accordingly.

Register Your Weblog with Disqus

2021-01-09T00:00:00.000Z

TL;DR Many of us have Disqus account to be able to place comments on those blogs which use Disqus comments widget for that. Because placing comments often requires being logged in. Of course, you can also log in with your Twitter or Facebook account. What is nice of Disqus optioin is that it keeps track of all your comments placed anywhere.

Sometimes however we want to add Disqus comments to our own blog and that requires another type of registration: that of our weblog itself. In this article, I share how this can be done. It may be helpful for those of you who got lost on the Disqus website searching for clues. 😃

Disqus Registration

Register and account with Disqus if you don't have one yet.
Log in to your account.
If it is the first time you are logging in, you will immediately get to see the screen as in step no.8. Otherwise, proceed to step no.4.
In the Admin section create your organization (any name you like).
Click on your avatar and choose Settings. You will now see the gear icon next to it.
Click on the gear icon and choose Add Disqus to Site:

Scroll to the bottom of the page till you see the GET STARTED button. Click on it.
Now choose the I want to install Disqus on my site option.
Fill in the form:

You may click the Customize Your URL link for more information on how to choose the Website Name.

When you fill in all the fields, click the the Create Site button.
On the next page your will be presented with the Disqus paid plans. Just scroll down to the free Basic plan and click on the Subscribe Now button:

Now you will be presented with a big choice of platforms to install Disqus on. Docusaurus is not one of them, so choose

Ignore the next page.

Click on the Configure Disqus menu option in the side menu on the left. This one is important. Here you have to specify your real Website URL to make sure that Disqus will collect the comments coming from that domain. Click the Next button.
Now, in Setup Moderation choose the default settings profile to moderate the comments of your visitors. Click the Complete Setup button.

You are done! Now, you will see the Disqus comments section under your blog posts. However...

Extra Moderation Settings

Make sure you configure the special Comment & Moderation Settings section for your website!

Disqus Moderation Policies

In the Admin portal of your newly registered website, go to Moderation Settings:

Now, go through the Moderation Settings and make sure you checkmark the options you believe are important to have:

For me personally, the most difficult choice is that of Pre-moderation. Without it you may get spam comments published under your blog post. With it you may frighten away visitors who don't want to be censored. I would rather prefer a rule which requires any new visitor to have only his very first comment moderated and, if accepted, no more moderation for all their comments afterwards.

How GraphQL Query Passes its Response Back to Gatsby React Components

2019-12-01T00:00:00.000Z

TL;DR When I started learning Gatsby, I wanted to understand the magic of GraphQL queries passing their results back to the React component. My secondary focus was to use React functional components instead of React class components as much as possible. In this blogpost, I have summarized my findings.

Most of the information comes from Gatsby Documentation and from my personal test projects.

Page Query

Suppose we have our site metadata defined in gatsby-config.js:

module.exports = {
  siteMetadata: {
    title: "My Personal website",
    description: "The most wonderful description of my website goes here.",
  },
}

Then in the src/pages/HomePage.js (or index.js) we can write the following code, which will show the description The most wonderful description of my website goes here. on the page:

import React from 'react'
import { graphql } from 'gatsby'

const HomePage = ({data}) => {
  return (
    <div>
     {data.site.siteMetadata.description}
    </div>
  )
}

export const query = graphql`
  query HomePageQuery {
    site {
      siteMetadata {
        description
      }
    }
  }
`

export default HomePage

So, where does the HomePage function get its data from? Here we have the famous "Convention over Configuration" principle at work:

the site field in the GraphQL query refers to the gatsby-config.js file above; the siteMetadata object with the description field gets exported there;
the GraphQL query itself is (and should be!) also exported: export const query = graphql;
as a result, the query response is passed as the data prop to the HomePage function and can be destructured as { data } from its props.

Page Query with Query Variables

With page queries we can go a step further and add query variables to the GraphQL query. The following example shows how it can be done. It is extra interesting because it is also an example of how to query the .mdx pages in our project.

Let us look at this query in the src/templates/blog-post.js file:

export const query = graphql`
  query MdxBlogPost($title: String) {
    mdx(title: {eq: $title}) {
      id
      title
    }
  }
`

It uses $title as a variable and searches the MDX-nodes in the project site with the title that equals the $title string value.

For this to work,

the MdxBlogPost query should have gatsby-plugin-mdx plugin installed, and

serving of the .mdx files should be configured via gatsby-source-filesystem plugin in the gatsby-config.js file.

When a page is created dynamically from the blog post template in gatsby-node.js, you can provide an object as part of the page’s context. Keys in the context object that match up with arguments in the page query (in this case: "title"), will be used as variables. Variables are prefaced with $, so passing a title property will become$title in the query.

posts.forEach(({ node }, index) => {
  createPage({
    path: node.fields.slug,
    component: path.resolve(`./src/templates/blog-post.js`),
    // values in the context object are passed in as variables to page queries
    context: {
      title: node.title, // "The most wonderful description ..."
    },
  })
})

StaticQuery

Gatsby v2 introduced StaticQuery, a new API that allowed not only pages but any component to retrieve data via a GraphQL query.

The table below shows the differences between page queries and the StaticQuery element.

Page Query	StaticQuery
works only in Pages	works in any React component including Pages
accepts variables via `pageContext`	accepts no variables
works with `React.createElement`	does not work with `React.createElement`, instead it is itself a JSX element
default export: the page `query` itself	default export: an anonymous function, which returns the `StaticQuery` element

Simply said the StaticQuery is a JSX-element with 2 parameters:

query that holds a query definition, and
render that holds a function returning a JSX-element

<StaticQuery query={graphql`...`} render={...} />

It handles the query result in a different way than a page query. Let us consider the following code snippet:

import React from "react"
import { StaticQuery, graphql } from "gatsby"

export default () => (
  <StaticQuery
    query={graphql`
      query HeadingQuery {
        site {
          siteMetadata {
            title
          }
        }
      }
    `}
    render={data => (
      <header>
        <h1>{data.site.siteMetadata.title}h1>
      header>
    )}
  />
)

How it works is that the result of the query in the query parameter automagically becomes the value of the render function data argument.

Notice the export default () => (...) signature similar to that of the page query except that here we have an anonymous default export.

From StaticQuery to useStaticQuery hook

React hooks are becoming more and more popular, and Gatsby has created its own: useStaticQuery hook. It is based on the StaticQuery element and requires at least version 16.8.0 of React and ReactDOMpackages. Let us rewrite the previous example using this hook:

import React from "react"
import { useStaticQuery, graphql } from "gatsby"

export default () => {
  const data = useStaticQuery(graphql`
    query HeaderQuery {
      site {
        siteMetadata {
          title
        }
      }
    }
  `)

  return (
    <header>
      <h1>{data.site.siteMetadata.title}h1>
    header>
  )
}

Here, we extract data object from the useStaticQuery hook and then use it in the JSX-element we return from the default anonymous export.

Known Limitations of useStatic Query

As Gatsby documentation states, useStaticQuery

does not accept variables (hence the name “static”), but can be used in any component, including pages;
because of how queries currently work in Gatsby, only a single instance of useStaticQuery per file is supported.

Closing Words

We have considered three options how to use GraphQL in Gatsby:

Page Queries to use only on pages
StaticQuery to use in any JSX-component
useStaticQuery hook to use in any JSX-component

For every option we have shown how the query result is passed to the corresponding presentational component.

Storybook React - DocsPage+MDX and Notes+MD with Typescript

2019-11-23T00:00:00.000Z

TL;DR When I came across the Storybook project as a way to create a standard design system, I have very quickly realized that many of the code snippets in the official documentation don't work out of the box if using Typescript. My focus however was on setting up the Storybook DocsPage + MDX and Storybook Notes + Markdown with Typescript. In this blog post you can read how I got everything working. First, Notes with Markdown. Then DocsPage with MDX.

Keep in mind

In the beginning, when I added Typescript many things broke and stopped working, so I have had to search on Google and have tried a whole bunch of different tips and tricks. Of course, most of them come from the Storybook documentation, Storybook blog posts, and StackOverflow. By the time I got stuff working, I did not know any more, which tip I found where. Even if everything I added was really necessary. So feel free to remove some additions if you think they don't make sense.

We are using YARN all over the project, so you will see a lot of yarn commands. If you prefer NPM, just replace yarn add with npm i to install stuff, and yarn with npm run and you are good to go. :-)

Typescript stuff

Here is the tsconfig.json in the root of the project:

{
  "compilerOptions": {
    "allowJs": false,
    "allowSyntheticDefaultImports": true,
    "downlevelIteration": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "jsx": "react",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "module": "esnext",
    "moduleResolution": "node",
    "noEmit": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noImplicitReturns": true,
    "noImplicitThis": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "removeComments": false,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "sourceMap": true,
    "strict": true,
    "target": "esnext",
    "typeRoots": [
      "./node_modules/@types",
      "./src/**/*.d.ts"
    ]
  },
  "exclude": [
    "build",
    "node_modules",
    "**/*.spec.ts",
    "**/*.spec.tsx"
  ],
  "include": [
    "src/**/*"
  ]
}

This is the tsconfig.json in the .storybook folder:

{
  "extends": "../tsconfig.json",
  "include": [
    "../src/**/*",
    "./storybookTheme.ts"
  ]
}

Add react.d.ts typings file in src/types/@storybook folder:

export const addDecorator: any
export const addParameters: any
export const configure: any
export const forceReRender: any
export const getStorybook: any
export const raw: any
export const setAddon: any
export const storiesOf: any

Notes with Markdown

For the Storybook Notes we will need raw-loader and @storybook/addon-notes NPM packages:

yarn add -D raw-loader @storybook/addon-notes

import '@storybook/addon-notes/register'

Next, suppose you have a Button.stories.tsx file. Place a notes.md file next to it:

DocsPage is a new Storybook way of generating documentation (see the Docs tab). However, we can also add extra Notes here in plain Markdown.

Lo and behold!

console.log('Hello world!')

const bs = ({ arg }) => {
  if (arg === 0) {
    return false
  }
}

Add raw-loader to the .storybook/webpack.config.js configuration:

module: {
  rules: [
    ...
    {
      test: /\.md$/,
      use: 'raw-loader',
    },
  ],
},

Now, in Button.stories.tsx add this code:

... // add here your imports, etc.

const notes = require('!!raw-loader!./notes.md').default

... // add more const if necessary

storiesOf('Button', module)
  ... // add here your decorators
  .add(
    'default',
    () => {
      return (
        ... // add here component details
      )
      ...
    },
    {
      notes: {
        Information: 'This page can be used for the general audience',
        'Design Notes': notes,
      },
    }
  )

Now, if your start your storybook with yarn start, you will see by the Button component the Notes panel with two tabs:

Information

and

Design Notes

The words Information and Design Notes here are arbitrary. You can use any other words instead. The only exception a.f.a.i.k. is the word markdown, which has a special meaning as a keyword in Storybook. I must say, however, that I have had issues trying to implement Notes with this markdown option. E.g., single quotes would be replaced with ' on the screen.

DocsPage with MDX

Pre-requisites

For the Storybook DocsPage + MDX we will need @mdx-js/loader, babel-loader and @storybook/addon-docs NPM packages:

yarn add -D @mdx-js/loader babel-loader @storybook/addon-docs

import '@storybook/addon-docs/register'

Add the following configurations to the .storybook/config.js file:

import { DocsContainer, DocsPage } from '@storybook/addon-docs/blocks'
import { addDecorator, addParameters, configure } from '@storybook/react'
... // add here other imports

... // add here your decorators
addParameters({
  options: {
    sortStoriesByKind: true,
    ... // add here other options
  },
  docs: {
    container: DocsContainer,
    page: DocsPage,
  },
})

configure(
  [
    require.context('../stories', true, /\.stories\.tsx?$/),
    require.context('../stories', true, /\.stories\.js$/),
    require.context('../stories', true, /\.stories\.mdx$/),
  ],
  module
)

Add the following to the .storybook/presets.js file:

module.exports = ['@storybook/addon-docs/react/preset']

And this goes into .storybook/webpack.config.js:

const createCompiler = require('@storybook/addon-docs/mdx-compiler-plugin')
... // add here your other const


module.exports = async ({ config, mode }) => ({
  ...config,

  resolve: {
    ...config.resolve,
    extensions: ['.js', '.jsx', '.ts', '.tsx', 'md', 'mdx'],
  },

  ... // add here your other settings

  module: {
    rules: [
      ... // add here other extensions
      {
        test: /\.(stories)\.mdx$/,
        use: [
          {
            loader: 'babel-loader',
          },
          {
            loader: '@mdx-js/loader',
            options: {
              compilers: [createCompiler({})],
            },
          },
        ],
      },
    ]
  }
})

Now, let us start experimenting with MDX.

One important observation though. The names of the MDX files we wish to see in our Storybook should end with .stories.mdx, not just .mdx.

Where the different names go

Let us create our first file:

    import { Meta } from '@storybook/addon-docs/blocks'

    

    # INTRO3

    Most of the documentation can be done via the __Docs__ option.
    Yet, in some cases we can add side notes in __Markdown__.

    ```js
    console.log('this is an Intro page!')

    const test = ({ arg }) => {
      if (true) {
        return false
      }
    }

Here, I have used `intro1` in the name of the file, `intro2` in the `meta` tag, and `intro3` in the text. When we now run `yarn start`, we will notice the following:

1. we don't see the name `intro1` anywhere, and a.f.a.i.k. this is as expected behavior
1. we get to see the new `MAIN` section in the menu tree on the left and `Intro2` as a new menu option

   ![main menu with intro2 option](images/main_intro2.png)

1. finally, `intro3` will be in the text as expected:

   ![docs panel with intro3 in the text](images/docs_intro3.png)

> Using more pipes (`|`) in the `title` property `` tag can be used as a means to create the complete documentation hierarchy next to the UI-components themselves.

### MDX file using a React component

In the previous section the `.mdx` file was in fact a pure `.md` file. Now, let us add a second file but this time let us add a React component inside. For this example, we will need to install `moment.js` package to format dates:

``` bash
yarn add moment

and create a simple CommitDate React component in src/components folder:

import moment from 'moment'
import * as React from 'react'

interface IDate {
  date: string
}

export const CommitDate = ({ date }: IDate): React.ReactNode => {
  console.log(date)
  const formattedDate = moment(date).format('LL')
  console.log(formattedDate)

  return (
    <>
      <em>{formattedDate}em>
    >
  )
}

Now, we create the changelog page: changelog.stories.mdx.

import moment from 'moment'
import { Meta } from '@storybook/addon-docs/blocks'
import { CommitDate } from '../src/Components'

<Meta title='Main|Changelog' />

# Changelog

| Version    | Date                               | Description       |
| ---------- | ---------------------------------- | ----------------- |
| __1.2.18__ |  | ✨ Initial release |

Let us run the Storybook UI with yarn start. First of all, we will get the second menu option under the MAIN menu section:

And this will be our Docs part:

As you can see, the Date column gets the formatted commit date:

September 5, 2019.

QED

Concluding notes

In my personal experience, adding Typescript - even to a working - project can lead to quite a lot of extra wiring and testing. Storybook projects are not an exception. Most of the code snippets in the documentation are written in ES6 en use not types. Just installing the Typescript related NPM packages and changing the file extensions from .js/.jsx to .ts/.tsx is not the end but only the beginning of the refactoring road.

In this blog post, I have shown the steps that were necessary to get the Storybook DocsPage working with MDX stories and Notes with Markdown files. I would be happy if this information helps you to fix your Storybook project.

By the way, it looks that Storybook is going to replace Notes with DocsPage. E.g., Notes is not mentioned any more in the list of add-ons on the Storybook Add-ons page. Well the Docs!

References

Articles about the DocsPage and the Storybook Design System

Sources

Storybook Design System and its Github repo
Storybook Roadmap

Webdings... Web What?

2016-01-02T00:00:00.000Z

TL;DR In this blog post, I share my personal story of how I discovered web development and came to passionately love it. Also about my mistakes and misconceptions along the way. It is not about the "ultimate truth" but rather about my personal observations and conclusions.

So, it will probably be more interesting to you if you are now in a similar situation to the one I was in at the beginning of the way. It was a long way and it took me at least a year to come to realize what web development was all about. I will be very happy if my story helps you to shorten yours. 😃

And, of course, your comments are more than welcome.

Hello, Reader. My name is André Roussakoff. At the moment of writing this post, I am 57 and I have never in my life had a blog of my own. I have never realized that it would be so hard to begin. There is so much to say and I have yet no clear understanding of what my blog will finally look like. Only that I have to start.

Oh yeah, about webdings. Check my About page.

I have been a backend application developer for many years developing backend applications with SQL databases. Working mostly with .NET and C#. I had no clear notion of the existence of web development as profession. Websites fascinated me by their beauty and style. Creating websites I called web design and I thought that it had everything to do with creative art and Photoshop skills. Being an application developer, I had a feeling that it lay outside of my profession.

Until several years ago. Then one day I was confronted with the necessity to create a website for a good acquaintance of mine. Somebody mentioned CMS as a tool to create websites and I started my research about CMS. Of course, the most popular were WordPress and Joomla. Unfortunately, both packages were written in PHP and I was in no hurry to learn another programming language even before I have created my first website. I must admit that I failed at the latter anyway because just using the standard menu options, I was never quite satisfied with the results.

Separation of Concerns

However, that CMS research on the positive side gave me the notion of separation of concerns. That when thinking about a website, one has to consider these four notions:

Form (structure and presentation)
Style (CSS)
Content (information)
Behavior (UX)

and that these can be treated rather independently of each other. That was a breakthrough because I suddenly saw a bridge to the world of OOP (Object Oriented Programming), which was very familiar to me and that one does not have to do all at once. With it also came the realization that my understanding of the notion of web design covered but a small piece of the whole story. That in terms of activities related to the website creation, we can distinguish (at least) the following three:

web design
web development
content management

Web design has indeed a lot to do with artistic creativity. Web development has to do with tons and tons of programming. And content management is the main responsibility of the actual website owner.

At this point, I decided to look deeper into web development. To my utter amazement the deeper I looked, the more there was to learn and the more confusing it all seemed. In Holland, we have a saying: "Because of all the trees, one does not see the forest". 😃 That was definitely true to say about me at that moment. Even now to some extent, I must admit, although I begin to have my preferences.

Web Development

Zooming further in on web development, I discovered there were two major areas of it:

front-end or client side development
back-end or server side development

and those developers who are doing both often talk about their work as

full stack website development

Front-end development has more to do with the visible to visitors part of the website, like menus, animations, complex UX tricks, DOM manipulations, etc.

Back-end development has more to do with the "invisible" activities, like user authentication and authorization, HTTP requests handling, data and database manipulation.

Websites vs XXX Apps

The next "tree" was the realization that mobile devices like smartphones and tablets often require a special approach and that apps we download for an app store are not the websites we browse on our PC or notebook screen. One can distinguish roughly four types of apps:

web apps
native apps
mobile apps
hybrid apps

A web app is, in fact, nothing more than a classic website, which we view on a mobile device using any installed browser.

A native app needs first to be registered within an app store like Windows Store, Apple Store or Google Play. Only after that we can download it and install on our mobile device. Thus, a native app is not a website but an application.

A mobile app is a web app that has such look and feel that, when started, it is practically undistinguishable from a native app.

Finally, a hybrid app combines the features of both worlds, web and native, and can access the mobile device's hardware. E.g. imagine an app in an app store, which is a wrapper around a classic website. Or a cross-browser app, which is customized to work on mobile devices independent of its platform.

One special sort of apps is a SPA (Single Page Application). A SPA has look and feel of a website or a native app with many pages and menu et al. Whereas technically it is all the time one and the same page object, only its elements are in-place replaced by new elements depending on the user action. E.g. the next image replaces the previous image or the content of another page replaces the content of the current page. And due to caching this can happen even without communication between the client and the server.

Different Platforms

The next "tree" came as a shock. Being a .NET developer I was supposed to "hate" all things Java because all Java developers "hate" all things .NET. 😃 Also, being a Windows developer I was supposed to "hate" all things Android or macOS. Same reason. All this was quite difficult to digest. Yet, maybe 90% of all mobile devices in the world are not on Windows platform. Have I landed in the wrong camp without even noticing it? The obvious answer seems to be "yes", isn't it?

On the other hand, one can ask another question: should I switch camps at the age of 57? Would it be reasonable and feasible? Fortunately for me, Microsoft seems to also have realized this gap and the hard choice that many a Windows developer was facing because of its previous policy.

As of last year, Microsoft came up with a number of new tools. It went open source with ASP.NET 5 (a.k.a. ASP.NET Core), MVC 6 and Entity Framework 7. It became partners with Cordova for the possibility of cross-platform development under Windows. And it brought out a wonderful light-weight code editor, Visual Studio Code (VSCode), which is absolutely NOT a clone of Visual Studio but rather a brother of such editors as Atom, Brackets or Sublime Text and even works on Linux and macOS.

At the same time, I have found out that I can run some traditional Linux/macOS tools under Windows like Nodejs.

As a developer, having all these tools at my disposal, I don't feel in any way limited by Windows platform as to the kind of web development I can do, now or in future.

Yippee! I don't have to switch the platform! 😃

JavaScript, the Language of the Web

Turning around, the next "tree" was JavaScript. JavaScript for me started at the very early stage of CMS research when my web world consisted of WordPress and Joomla. As soon as I saw some basic jQuery scripting, I almost immediately came across this advice (in my free interpretation):

Avoid using jQuery or JavaScript as much as possible, because inadequate code can completely ruin the website performance.

At first, it sounded reasonable and for some time I did indeed avoid anything to do with it. Probably for a non-developer, it is a reasonable thing to do. But for me, the more I saw of JavaScript here and there, the more I came to love it and the more wonderful things I saw it can make rather than break. So, I learned myself some JavaScript.

And with that, I perceived a whole new world previously completely unknown to me. I am talking about myriad of different JavaScript frameworks and libraries, like Nodejs, Angular, Aurelia, React, Backbone, Underscore and Lodash, Express and Hapi, Gulp, Grunt, Ionic, Signalr, Karma, Jasmine, Mocha, Selenium - you name it. Even the names themselves are beautiful to say nothing of what these tools are capable of!

The most important discovery was that it is practically unthinkable to do web development without HEAVY use of JavaScript. Talking about that advice to avoid it as much as possible! 😃

MVC and REST API

In this final part of the article, I want to talk about the concept of separation of concerns that I have mentioned earlier and in a very different context. When talking about CMS, this separation was related to Form, Style, Content and Behavior. Now, I realize that on a lower, more technical level this "external" separation of concerns can be hard coupled with the beautiful MVC (Model-View-Controller) paradigm. MVC relates to the way we structure our code in terms of responsibilities and it determines the division between:

Model (representation of the data structure)
View (the way to present the information to the user)
Controller (application logic behind the scenes which binds Views and Models together)

On the client side, everything can be written in plain JavaScript but it is probably much easier to use some specialized JavaScript framework of library. My impression is that at the moment, the most popular framework for client side development seems to be Angular with React only a half step behind, although my personal beauty prize goes to Aurelia.

Angular has also such advantage that, in combination with Ionic framework, it makes it easier to create cross-platform apps. And as to React, it is the Facebook's main development tool.

In the earlier versions of ASP.NET MVC, Microsoft used out-of-the-box no JavaScript for client side development. The clients had to send AJAX requests to the server. The response was composed on the server and after that sent to the client. With the corresponding performance penalty. On the other hand, the standard tool for the development of views is Razor. This fantastic tool makes it possible to combine HTML code with C# snippets, so that we can manipulate HTML tags based on C# variables and use conditional logic and loops. Recently, I came across a wonderful Umbraco CMS, which became my second love in the world of web development, the first being Aurelia. Umbraco CMS is free, is based on ASP.NET MVC 4, and it uses Angular on the client side.

On the server side, I have discovered the wonderful world of RESTful API. Simply explained, it is a two-way translation between the URL string composition and the corresponding action that has to be executed. Here is a couple of trivial examples how a REST API could look like:

http://website.com - show home page
http://website.com/articles - show list of articles
http://website.com/articles/1 - show or update article with id = 1

REST API can be implemented in a lot of different ways: with JavaScript (e.g. Nodejs + Express) or with C#/ASP.NET.

Also, it is now possible to develop with JavaScript inside the Visual Studio 2015, or alternatively develop completely outside of Visual Studio using VSCode on any platform, Windows, Linux or macOS, and even run natively C# code on all of them using OmniSharp!

Round up

Surprisingly, it has become quite a big article, over 2000 words. I have told you about the different steps I had gone through before I had discovered the "forest" of web development as my new love. Although there are so many different puzzle pieces in the web development picture, there some important binding concepts that keep it all together and give me the feeling of beauty.

the most important central notion of separation of concerns (both in CMS and MVC)
the possibility to use same toolset for different aims (different apps and SPAs), so everything become more accessible and understandable
Microsoft going open source with the latest release of ASP.NET, MVC and Entity Framework and its support for traditional Linux/macOS tooling as well, so no necessity to switch to Java camp
huge open source community behind all of this, which made it possible for me to come this far and maybe even inspired me to write this article

This is by far not the end of the way! It is only the first step. From complete illiteracy to learning to read and understand something of what I have read. A much more difficult step is the next one: learning to write. Meaning developing complete projects from A to Z and thus using the tools I have learned.

I believe I have yet to add a link here and there in case somebody becomes interested to go into more details on some tool or framework, although Google search also can help.

Thank you, the Reader, for coming this far. If there is anything at all that you could add as feedback on this article, please do. Be it positive or negative. I will accept it thankfully.

Madrus's Webdings Blog

Implementing Right-to-Left (RTL) Support in a Tailwind CSS React Application

Understanding the Challenge​

Setting Up the Foundation​

1. RTL Utility Functions​

HTML Direction Attribute​

2. Setting the dir Attribute on the HTML Tag​

3. Dynamic Direction Updates​

Add Disqus Comments to Docusaurus Blog Posts in 2025

Let's Go​

Prerequisites​

Prepare the Frontmatter​

Swizzle the BlogPostItem component​

DiscussionEmbed​

CommentCount and CommentEmbed​

Final Observations​

Knowledge Sharing, the Missing Part

Why Knowledge Sharing is Important​

Conventional Ways of Knowledge Sharing​

Course Required by the Company (GURU to ANYONE)​

Internal Meeting (GURU to ANYONE)​

Help request (GURU to ANYONE)​

Questions We Ask​

The Missing Part​

Questions We Ask​

What we are missing​

Impact of Missing the Missing Part​

Coding Efficiency​

Code quality​

Fun and Satisfaction @ Work​

How the Missing Part Can Help​

Knowledge Sharing vs Information sharing​

Mental Shift: GURU ⇒ ANYONE​

Coding Efficiency​

Pairing or Pair programming​

Crowd Programming (Hackathon like)​

Merge conflicts​

Code Quality​

Fun and Satisfaction @ Work​

From Theory to Practice​

Active Knowledge - Passive Knowledge = Action​

Side Projects​

In Conclusion​

References​

Add Disqus Comments to Docusaurus Blog Posts (archived)

Let's Go​

Prerequisites​

Prepare the Frontmatter​

Swizzle the BlogPostItem component​

DiscussionEmbed​

CommentCount and CommentEmbed​

Final Observations​

Register Your Weblog with Disqus

Disqus Registration​

Disqus Moderation Policies​

How GraphQL Query Passes its Response Back to Gatsby React Components

Page Query​

Page Query with Query Variables​

StaticQuery​

From StaticQuery to useStaticQuery hook​

Known Limitations of useStatic Query​

Closing Words​

Storybook React - DocsPage+MDX and Notes+MD with Typescript

Keep in mind​

Typescript stuff​

Notes with Markdown​

Lo and behold!​

Information​

Design Notes​

DocsPage with MDX​

Pre-requisites​

Where the different names go​

Concluding notes​

References​

Articles about the DocsPage and the Storybook Design System​

Sources​

Webdings... Web What?

Separation of Concerns​

Web Development​

Websites vs XXX Apps​

Understanding the Challenge

Setting Up the Foundation

1. RTL Utility Functions

HTML Direction Attribute

2. Setting the `dir` Attribute on the HTML Tag

3. Dynamic Direction Updates

Let's Go

Prerequisites

Prepare the Frontmatter

Swizzle the BlogPostItem component

DiscussionEmbed

CommentCount and CommentEmbed

Final Observations

Why Knowledge Sharing is Important

Conventional Ways of Knowledge Sharing

Course Required by the Company (GURU to ANYONE)

Internal Meeting (GURU to ANYONE)

Help request (GURU to ANYONE)

Questions We Ask

The Missing Part

Questions We Ask

What we are missing

Impact of Missing the Missing Part

Coding Efficiency

Code quality

Fun and Satisfaction @ Work

How the Missing Part Can Help

Knowledge Sharing vs Information sharing

Mental Shift: GURU ⇒ ANYONE

Coding Efficiency

Pairing or Pair programming

Crowd Programming (Hackathon like)

Merge conflicts

Code Quality

Fun and Satisfaction @ Work

From Theory to Practice

Active Knowledge - Passive Knowledge = Action

Side Projects

In Conclusion

References

Let's Go

Prerequisites

Prepare the Frontmatter

Swizzle the BlogPostItem component

DiscussionEmbed

CommentCount and CommentEmbed

Final Observations

Disqus Registration

Disqus Moderation Policies

Page Query

Page Query with Query Variables

StaticQuery

From StaticQuery to useStaticQuery hook

Known Limitations of useStatic Query

Closing Words

Keep in mind

Typescript stuff

Notes with Markdown

Lo and behold!

Information

Design Notes

DocsPage with MDX

Pre-requisites

Where the different names go

Concluding notes

References

Articles about the DocsPage and the Storybook Design System

Sources

Separation of Concerns

Web Development

Websites vs XXX Apps

Different Platforms

JavaScript, the Language of the Web

MVC and REST API

Round up