Forem: Hállex da Silva Costa

How MDX can accelerates document creation in websites

Hállex da Silva Costa — Mon, 05 May 2025 14:39:54 +0000

Overview

See how MDX solves the problem of writing extremely long pages or articles.

In this article, we will show you how MDX can be a powerful solution to speed up the documentation creation process.

Introduction

Have you ever seen a very common problem in many companies, such as outdated documents? Well, in a world where maintaining documents such as policies and privacy, terms and security is crucial.

At the same time, having to deal with the fact that you will have to spend precious time writing N pages that have already been written in a document like Word or PDF to an HTML, JSX or TSX page does not seem very pleasant or very smart.

Finding efficient ways to create and maintain documents becomes essential.

The Problem with Articles/Documentation

One of the biggest challenges in creating documentation is the time spent retyping content. Often, we need to:

Rewrite texts that already exist in other formats
Maintain consistency between different versions of the same document
Update multiple formats when changes occur

This process not only consumes time but also increases the chance of errors and inconsistencies.

The Solution: MDX

MDX (Markdown + JSX) emerges as an elegant solution to these problems. It combines the simplicity of Markdown with the power of JSX, allowing the creation of interactive and dynamic documents.

Easy Conversion from DOCX to MD/MDX

One of the biggest advantages of using MDX is the ease with which you can convert an existing document from docx to markdown and from markdown to MDX

Why Follow This Approach?

1. Productivity

Less time spent on formatting
Component reuse
Faster updates

2. Maintenance

Code and documentation together
Simpler versioning
Less content duplication

3. Interactivity

Interactive components
Executable code examples
Better reader experience

4. Flexibility

Easy integration with modern tools
Support for different output formats
Compatibility with popular documentation systems

Examples

Here's an example of a DocumentPage.tsx created using the tsx syntax for another page using the DocumentPage.mdx syntax

DocumentPage.tsx

import React from 'react';

const DocumentPage: React.FC = () => {
  return (
    <div className="document-page max-w-4xl mx-auto py-8 px-4">
      <h1 className="text-3xl font-bold mb-8 text-center">Terms of Service and Privacy Policy</h1>

      <section className="mb-8">
        <h2 className="text-2xl font-semibold mb-4">1. Introduction</h2>
        <p className="mb-4">
          Welcome to our Terms of Service and Privacy Policy. 
          This document establishes the rules and guidelines for using our services.
        </p>
        <p className="mb-4">
          By accessing and using our platform, you agree to the terms set forth herein.
          We recommend reading this document carefully before proceeding.
        </p>
      </section>

      <section className="mb-8">
        <h2 className="text-2xl font-semibold mb-4">2. Definitions</h2>
        <p className="mb-4">For the purposes of this document, the following terms shall have the meanings below:</p>
        <ol className="list-decimal pl-6 space-y-2">
          <li>
            <strong>Platform:</strong> Refers to the set of services and features provided
            through our website and applications.
          </li>
          <li>
            <strong>User:</strong> Any person who accesses or uses the Platform.
          </li>
          <li>
            <strong>Content:</strong> Information, data, text, images, and other materials provided
            through the Platform.
          </li>
        </ol>
      </section>

      <section className="mb-8">
        <h2 className="text-2xl font-semibold mb-4">3. Platform Usage</h2>
        <p className="mb-4">By using our Platform, you agree to:</p>
        <ul className="list-disc pl-6 space-y-2">
          <li>Provide accurate and up-to-date information</li>
          <li>Maintain the confidentiality of your account</li>
          <li>Not use the Platform for illegal purposes</li>
          <li>Respect intellectual property rights</li>
        </ul>
      </section>

      <section className="mb-8">
        <h2 className="text-2xl font-semibold mb-4">4. Privacy and Data Protection</h2>
        <p className="mb-4">
          Our privacy policy describes how we collect, use, and protect your personal information.
          For more details, please refer to our{' '}
          <a href="/privacy" className="text-blue-600 hover:underline">
            complete Privacy Policy
          </a>.
        </p>
        <div className="bg-gray-50 p-4 rounded-lg">
          <h3 className="text-lg font-semibold mb-2">Collected Data</h3>
          <ul className="list-disc pl-6 space-y-1">
            <li>Registration information</li>
            <li>Platform usage data</li>
            <li>Device information</li>
            <li>Cookies and similar technologies</li>
          </ul>
        </div>
      </section>

      <section className="mb-8">
        <h2 className="text-2xl font-semibold mb-4">5. Responsibilities</h2>
        <p className="mb-4">Our responsibilities include:</p>
        <ol className="list-decimal pl-6 space-y-2">
          <li>
            Maintaining the Platform available and functioning properly
          </li>
          <li>
            Protecting user data in accordance with data protection laws
          </li>
          <li>
            Providing technical support when needed
          </li>
        </ol>
      </section>

      <section className="mb-8">
        <h2 className="text-2xl font-semibold mb-4">6. Contact</h2>
        <p className="mb-4">
          For questions regarding these terms, please contact us via email at{' '}
          <a href="mailto:legal@company.com" className="text-blue-600 hover:underline">
            legal@company.com
          </a>
          {' '}or by phone at (555) 123-4567.
        </p>
      </section>

      <footer className="text-sm text-gray-600 mt-8 pt-4 border-t">
        <p>Last updated: {new Date().toLocaleDateString('en-US')}</p>
      </footer>
    </div>
  );
};

export default DocumentPage;

DocumentPage.mdx

---
title: "Terms of Service and Privacy Policy"
description: "Terms and conditions for using the platform and privacy policy"
creationAt: "2025-05-04"
lastUpdated: "2025-05-04"
---

export const meta = {
  title: "Terms of Service and Privacy Policy",
  creationAt: "2025-05-04",
  lastUpdated: "2025-05-04"
};

# {meta.title}

{frontmatter.description}

## 1. Introduction

Welcome to our Terms of Service and Privacy Policy. 
This document establishes the rules and guidelines for using our services.

By accessing and using our platform, you agree to the terms set forth herein.
We recommend reading this document carefully before proceeding.

## 2. Definitions

For the purposes of this document, the following terms shall have the meanings below:

1. **Platform:** Refers to the set of services and features provided
   through our website and applications.

2. **User:** Any person who accesses or uses the Platform.

3. **Content:** Information, data, text, images, and other materials provided
   through the Platform.

## 3. Platform Usage

By using our Platform, you agree to:

* Provide accurate and up-to-date information
* Maintain the confidentiality of your account
* Not use the Platform for illegal purposes
* Respect intellectual property rights

## 4. Privacy and Data Protection

Our privacy policy describes how we collect, use, and protect your personal information.
For more details, please refer to our [complete Privacy Policy](/privacy).

<InfoBox type="info">
  ### Collected Data

  * Registration information
  * Platform usage data
  * Device information
  * Cookies and similar technologies
</InfoBox>

## 5. Responsibilities

Our responsibilities include:

1. Maintaining the Platform available and functioning properly
2. Protecting user data in accordance with data protection laws
3. Providing technical support when needed

## 6. Contact

For questions regarding these terms, please contact us via email at [legal@company.com](mailto:legal@company.com)
or by phone at (555) 123-4567.

<LegalNotice>
  This document was last updated on {meta.lastUpdated}.
  We recommend checking periodically for updates.
</LegalNotice>

{/* Custom components for legal elements */}
<LegalSection>
  <h2>Final Provisions</h2>
  <p>
    These terms are governed by the laws of the United States and any dispute shall be
    submitted to the jurisdiction of the courts of New York, NY.
  </p>
</LegalSection>

<TableOfContents>
  <h2>Table of Contents</h2>
  <ol>
    <li><a href="#introduction">Introduction</a></li>
    <li><a href="#definitions">Definitions</a></li>
    <li><a href="#usage">Platform Usage</a></li>
    <li><a href="#privacy">Privacy and Data Protection</a></li>
    <li><a href="#responsibilities">Responsibilities</a></li>
    <li><a href="#contact">Contact</a></li>
  </ol>
</TableOfContents>

> Documente created at {meta.creationAt}

This MDX example demonstrates how we can create complex legal documents in a more structured and interactive way. Notice how:

The frontmatter organizes the document metadata. Use it or export a new meta variable to use in your markdown and communicate with external layer like the MDXProvider
Markdown syntax keeps the content readable and well-formatted
Custom components (<InfoBox>, <LegalNotice>, <LegalSection>, <TableOfContents>) add specific functionality
Custom styles for common elements as h1, h2, h3, h4, h5, p, a, li, ol, etc... Allows you to dynamically style markdown syntax elements such as #, ##, ###, -
JavaScript code can be embedded for dynamic features (like the update date)
The document structure is clear and well-organized

This approach makes it much easier to maintain and update extensive legal documents, while also significantly improving the end-user experience.

You can visit a repository with a simple example comparing TSX and MDX here and visit here to play a little with mdx playground

Conclusion

MDX is an excellent tool for saving time, maintaining code consistency, and improving efficiency. By combining the simplicity of Markdown with the power of JSX, it offers a robust solution to modern documentation challenges.

The approach of converting existing documents to MDX not only speeds up the creation process but also improves the quality and maintainability of documentation. In a world where documentation is crucial, MDX presents itself as an essential tool for teams seeking efficiency, quality and save time.

Resilient Node.js servers without using docker

Hállex da Silva Costa — Tue, 04 Mar 2025 01:55:09 +0000

Overview

Now you will learn how we create resilient services without interrupting the main SSH connection or without the need to create N SSH connections with N open terminals while developing our services in our remote development environment.

Summary

Requirements
What is PM2?
Installing PM2
Persisting Processes
Check Processes
In Conclusion

Requirements

Node.js
NPM

What is PM2?

PM2 is a daemon process manager that will help you manage and keep your application online 24/7

The services running through it become resilient. A similar analogy is comparing PM2 with NGINX

Installing PM2

npm i -g pm2

Persisting Processes

# Explanation: pm2 start <package-manager> --name <app-name> -- <script-name>
pm2 start pnpm --name woovi-front -- woovi

Your server is launched in daemon mode, meaning it runs as a detached background process.

Under the hood, PM2 spawns a new process for your service that is independent of the initial terminal session.

This decoupling ensures that the server continues to run even if you close the terminal, while PM2 monitors, logs, and automatically restarts the process if it encounters any issues.

Check Processes

pm2 ls

You can view the daemon processes that PM2 spawns for your services, and check the following information

If the status is "online", your service already be up, then you can test using the command curl

I already know that my service may be running on port 3000, you must change the port to your application's port

# use this for test in your VPS
curl http://localhost:3000

# or this, if want to test in the machine host
curl http://yourmachineip:3000

PM2 is powerful when it comes to process management it has many other commands like pm2 delete to delete an unused daemon process, pm2 restart to restart a process, and pm2 stop to end a process execution

In Conclusion

Integrating PM2 into remote development environments is an effective strategy to ensure that your services or applications remain running continuously and stably so that you can move freely without worrying about tying up the main process of your SSH connection and ending up interrupting the service at some point.

Woovi monorepos best practices

Hállex da Silva Costa — Mon, 24 Feb 2025 15:04:11 +0000

Summary

Look the conflict between dependencies version
Always update the packages remember of updates your codependencies
Clear the cache
Change error also is progress

Look at the conflict between the dependencies version

This detail implies if any dependencies can be resolved correctly and if not have a version conflict.
As the example we have the styled-components lib, it can have a problem with type Symbol reference where the library doesn´t find your properties of themes because, in your internal code, it uses the symbolObject which is a unique object that refers your set configs.

This rule is valid for any type of dependency like react-relay, relay-compiler, style-components, react and so on.
If you use pnpm you can run the command pnpm list <package-name> --recursive to help you find duplicate packages with different versions.

Always update a package remember to update your codependencies

Here I will use relay-compiler as an example, if you update the project's relay version, ensure that the react-relay, babel, swc, or in the general context, all relay plugins and your codependency this updates can prevent conflict of compatibility and unexpected bugs.
Also remember to delete any artifact that may have been generated by an old version of some library you are using, such as the __generated__ folder of relay-compiler.

Clear the cache

If some error is thrown on the screens and the value is undefined it should have some value and probably have a persistence of cache from older executions.

Change the error also is a progress

Sometimes you may get stuck on an error or bug, just following these other steps above may not solve the problem 100%, but it will probably change the error and this can be considered progress.

In Conclusion

Synchronizing codependencies and using tools like pnpm list <package-name> --recursive helps identify incompatible versions while updating related packages ensures compatibility. Clearing caches, and removing old artifacts of relay-compiler can help get closer to the goal, and errors should be treated as progress steps toward resolution.