_kud's tech blog

How to edit a markdown in 2020, part 1: zmv

Sorry .mdx but I renamed you.

As you may know, I now use Next.js to compile my website. It allows me to write my layout and pages in React and still have the benefit to use static files in the end.

For my posts, MDX was my choice: it is Markdown but with JSX capacity, perfect when you want to display a live version of your code, or to use custom components to inject into your Markdown documents.

Okay, now that you know more about my stack, let's talk about MDX. If you read the documentation of MDX, the extension of the files used is .mdx by default. It is a good idea to make the difference between markdown documents and mdx documents.

However, it provokes some issues on different topics.

Already existing format

First of all, as you can read on Wikipedia, .mdx already exists as format, and what is it?

Media Data Extended files are a binary file format for storing 3D models, engineered and used by Blizzard Entertainment in its games.

Okay fine, but what's the problem? The problem is some editors like Sublime Text (and plugins) could ignore them by default as they think it is a binary so you won't be able to see them in the sidebar or whatever.

Impossible to open on Markdown Editors

Second issue, it is not recognised yet by different Markdown editors. Indeed, they only display .md files.

So what's the solution?

The solution is simply to change all the .mdx into .md.

(And to be honest, I don't mind because I also do the same for JSX where my files are in .js and not .jsx.)

This is the part where zmv comes.

What do we want to do? Change all the MDX documents into .md. So what could we use for that? rename? meh, it needs find for that. The excellent rnm? Yeah we could but I often need to read the documentation to understand how it works. So, what could we use? ZMV 💪🏻

zmv is a zsh command to rename easily your folders or/and files.

How could we use it for our goal? Like that:

1$ zmv -W "**/index.mdx" "**/index.md"

💥, the trick is done. Any index.mdx of any folders are now named index.md. The API is quite obvious to me, I love it.

Different ways to use it:

  • Using capture

    1$ zmv '(**/)foo.txt' '${1}bar.txt'
  • Using the w flag to have each wildcard automatically made into a parenthetical group

    1zmv -w '**/foo.txt' '${1}bar.txt'
  • Using the W flag and use wildcards in the replacement text — with this flag, the wildcards in the replacement text are turned into $1, $2, etc.

    1$ zmv -W '**/foo.txt' '**/bar.txt'

To use zmv , you first need to load it via autoload zmv. I suggest you to load it into your .zshrc like:

1# ~/.zshrc
2autoload zmv

Next.js part

Okay we're good, our files are now with the good extension and can be easily opened via different editors. However, we still need to change the way Next.js compile our files.

It is quite easy, no worries, you simply need to go to next.config.js and specify the string of the extension like this:

1// next.config.js
2const withPlugins = require("next-compose-plugins")
3const withMDX = require("@next/mdx")({
4+ extension: /\\.md$/,
5})
6
7module.exports = withPlugins([withMDX], {
8- pageExtensions: ["mdx", "js"],
9+ pageExtensions: ["md", "js"],
10})

If you still want to keep .md and .mdx, no issues, you can write it like this:

1// next.config.js
2const withPlugins = require("next-compose-plugins")
3const withMDX = require("@next/mdx")({
4 extension: /\\.md?$/,
5})
6
7module.exports = withPlugins([withMDX], {
8 pageExtensions: ["md", "mdx", "js"],
9})

(As you can see in this code, I use the excellent pluging next-compose-plugins which allows you to have a better readability of your list of plugins.)


Greaaaaaaaat! Now that we've renamed all our MDX files, we now can open them in any markdown editors! In another post, I'll talk to you about different Markdown Editors I tried or use.

And if you want some resources about zvm:

Bye bye 👋🏻