Что такое MDX и как вы можете использовать его в своем блоге Gatsby

Первоначально опубликовано на https://inspiredwebdev.com.

Почему я люблю писать, используя Markdown

Если вы никогда не использовали Markdown, позвольте мне рассказать вам об этом в нескольких словах. Это простой инструмент преобразования, который позволяет вам писать простой текстовый формат, который преобразуется в действительный HTML.

Например, для создания заголовков ( h1) вы должны использовать #, для создания полужирных тегов вы должны использовать **text** и так далее, вы можете прочитать больше о Markdown в этом руководстве.

С того момента, как я начал использовать Markdown, я влюбился в него. Он такой простой, но такой мощный, что я даже дошел до того, что использовал его, чтобы написать книгу на 300 страниц (здесь, если вам интересно).

Это позволяет мне использовать один и тот же формат для написания статей в моем блоге и Dev.To, и, если мне нужно, я могу использовать такие инструменты, как Pandoc, чтобы легко преобразовать его в PDF или DOC.

Есть много приложений, которые вы можете использовать для написания Markdown, я говорю о моем любимом здесь.

После его интенсивного использования в моем блоге (inspiredwebdev.com) я почувствовал, что хочу, чтобы он делал больше, чтобы было проще реализовать внутри него пользовательский HTML и JS.

Markdown поддерживает HTML, поэтому, например, если вы хотите, чтобы в вашей статье был определенный заголовок, вы все равно можете написать:

вместо того, чтобы писать следующее, что сделало бы невозможным добавление пользовательского id в тег HTML.

Мне нравится, чтобы мой Markdown был как можно более чистым, поэтому я стараюсь не помещать в него слишком много HTML, но бывают случаи, когда это может быть полезно.

Иногда мне казалось, что было бы неплохо реализовать этот классный компонент карусели в середине моей статьи, вместо того, чтобы размещать его в конце, за пределами файла Markdown и в шаблоне страницы JSX (в случае Gatsby блог).

К сожалению, в Markdown я бы не смог этого сделать, и именно здесь я обнаружил MDX.

Что такое MDX и почему это круто

MDX для JSX — это то же самое, что MD для JS. Благодаря этому теперь вы можете легко импортировать свои компоненты в файл MDX и легко интегрировать их в свой Markdown.

Если сейчас я хочу добавить этот красивый компонент карусели в середину моей статьи, я могу сделать это всего двумя строками:

Сначала мне нужно импортировать компонент следующим образом:

а затем я использую его так же, как в файле JSX:

Остальную часть моей статьи вообще не нужно менять, я могу продолжать писать ## для своего h2 и т. д.

Помните, что если вы ссылаетесь на свои компоненты, путь должен указываться относительно папки, в которой находится файл MDX.

Как установить его на мой блог Гэтсби

У меня было два ранее существовавших блога Gatsby, которые я хотел перевести на использование MDX, и на это у меня ушло примерно 10 минут.

Подводя итог шагам, которые необходимо предпринять для обновления существующего блога:

1) Установите необходимые пакеты следующим образом: npm install --save gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react и не забудьте удалить старый плагин gatsby-transformer-remark.

2) Зайдите в свой файл gatsby-config и замените старый gatsby-transformer-remark новым gatsby-plugin-mdx и обязательно добавьте extensions: [.mdx, .md], в массив опций плагина.

3) Внутри gatsby-node.js нужно заменить упоминания allMarkdownRemark на allMdx

4) Найдите свою страницу index.js или там, где отображается список сообщений, и замените все упоминания allMarkdownRemark.edges на allMdx.edges. Не забудьте заменить его в запросе GraphQL.

5) Внутри шаблона отдельного поста вам нужно заменить data.markdownRemark на data.mdx. Опять же, не забудьте заменить его и в запросе GraphQL.

6) Внутри шаблона отдельного поста добавьте import { MDXRenderer } from "gatsby-plugin-mdx" и замените упоминания html на body как в коде, так и в запросе.

7) На последнем шаге нам нужно заменить раздел, где мы используем dangerouslySetInnerHTML, на новый <MDXRenderer>{post.body}</MDXRenderer> и не забудьте заменить post.body соответствующим именем переменной, которое вы используете в своем шаблоне.

Это должно сработать. В процессе обновления я столкнулся с несколькими ошибками, но все они были связаны с некоторыми незакрытыми HTML-тегами в моих файлах Markdown. Как только я исправил эти мелкие проблемы, все стало гладко.

Бьюсь об заклад, ваша миграция также пройдет гладко.

Если вам нужно более подробное руководство по обновлению, вы должны проверить официальный блог Гэтсби, там также есть статьи по реализации MDX в новом блоге, если вы не пришли из уже существующего, как я.

Работа с многомерными выражениями

До сих пор работа с MDX была отличной, я не сталкивался с какими-либо проблемами, и возможность добавлять компоненты в мои файлы Markdown, не отказываясь от простоты синтаксиса Markdown, была потрясающей.

Если вы работаете над VSCode, вам придется установить новое расширение, чтобы включить подсветку синтаксиса. Вы можете просто выполнить поиск MDX в магазине расширений, и первый найденный будет вам полезен.

Если вы столкнулись с какой-либо ошибкой при использовании MDX, сообщите о ней в Github по этой ссылке.

Предостережения по работе с MDX

Если вы знаете, как работает GatsbyJS, вы знаете, что каждый файл JS в папке pages станет страницей. Если вы работаете с файлами Markdown, это не имеет значения, но если вы используете MDX, вам нужно знать, что каждый файл MDX внутри этой папки также станет страницей.

Так, например, если у вас есть папка с названием blog в папке pages, каждый файл .mdx станет страницей с URL-адресом Sitename/blog/fileName. Если вы не хотите автоматически генерировать страницы, а вместо этого хотите создавать свои собственные внутри gatsby-node, тогда решение простое: переместите папку blog за пределы страницы.

Сделав это, вы пропустите автоматическое создание и вместо этого сможете вручную определить способ создания этих страниц в файле gatsby-node. Не забудьте обновить пути импорта ваших компонентов в файлах MDX при перемещении папки!

Заключительные соображения

Что вы думаете о MDX? Вы впервые об этом услышали? Это привлекло ваше внимание? Или вы им давно пользуетесь?

В таком случае, каков ваш опыт? Оставить комментарий.

Первоначально опубликовано на https://inspiredwebdev.com.