Merge pull request #96 from timlrx/mdx-bundler

feat: mdx-bundler and xdm
2021-07-04 15:23:40 +08:00
parent 58ec53d19d ec450d9997
commit 0fcb9fc90c
16 changed files with 1536 additions and 971 deletions
--- a/data/authors/sparrowhawk.md
+++ b/data/authors/sparrowhawk.md
@ -1,6 +1,6 @@
 ---
 name: Sparrow Hawk
-avatar: https://upload.wikimedia.org/wikipedia/commons/thumb/e/e8/Accnis_edit.jpg/220px-Accnis_edit.jpg
+avatar: /static/images/sparrowhawk-avatar.jpg
 occupation: Wizard of Earthsea
 company: Earthsea
 twitter: https://twitter.com/sparrowhawk
--- a/data/blog/github-markdown-guide.mdx
+++ b/data/blog/github-markdown-guide.mdx
@ -140,6 +140,7 @@ function fancyAlert(arg) {
    $.facebox({ div: '#foo' })
  }
 }
+```
 ````

 And here's how it looks - nicely colored with styled code titles!
--- a/data/blog/guide-to-using-images-in-nextjs.mdx
+++ b/data/blog/guide-to-using-images-in-nextjs.mdx
@ -50,14 +50,10 @@ _Note_: If you try to save the image, it is in webp format, if your browser supp
 ![ocean](/static/images/ocean.jpeg)

 <p>
-  Photo by{' '}
-  <a href="https://unsplash.com/@yucar?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">
-    YUCAR FotoGrafik
-  </a>{' '}
-  on{' '}
-  <a href="https://unsplash.com/s/photos/sea?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">
-    Unsplash
-  </a>
+  Photo by [YUCAR
+  FotoGrafik](https://unsplash.com/@yucar?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText)
+  on
+  [Unsplash](https://unsplash.com/s/photos/sea?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText)
 </p>

 # Benefits
--- a/data/blog/new-features-in-v1.mdx
+++ b/data/blog/new-features-in-v1.mdx
@ -1,6 +1,6 @@
 ---
 title: 'New features in v1'
-date: '2021-06-02'
+date: '2021-06-29'
 tags: ['next-js', 'tailwind', 'guide']
 draft: false
 summary: 'An overview of the new features released in v1 - code block copy, multiple authors, frontmatter layout and more'
@ -12,15 +12,17 @@ layout: PostSimple
 A post on the new features introduced in v1.0. New features:

 - [Theme colors](#theme-colors)
+- [Xdm MDX compiler](#xdm-mdx-compiler)
 - [Layouts](#layouts)
 - [Multiple authors](#multiple-authors)
 - [Copy button for code blocks](#copy-button-for-code-blocks)
+- [Line highlighting and line numbers](#line-highlighting-and-line-numbers)

 ## Theme colors

 You can easily modify the theme color by changing the primary attribute in the tailwind config file:

-```:tailwind.config.js
+```js:tailwind.config.js
 theme: {
    colors: {
      primary: colors.teal,
@ -37,6 +39,37 @@ Tailwind includes great default color palettes that can be used for theming your

 Migrating from v1? You can revert to the previous theme by setting `primary` to `colors.sky` (Tailwind 2.2.2 and above, otherwise `colors.lightBlue`) and changing gray to `colors.coolGray`.

+## Xdm MDX compiler
+
+We switch the MDX bundler from [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote) to [mdx-bundler](https://github.com/kentcdodds/mdx-bundler).
+This uses [xdm](https://github.com/wooorm/xdm) under the hood uses the latest micromark 3 and remark, rehype libraries.
+
+**Warning:** If you were using custom remark or rehype libraries, please upgrade to micromark 3 compatible ones. If you are upgrading, please delete `node_modules` and `package-lock.json` to avoid having past dependencies related issues.
+
+[xdm](https://github.com/wooorm/xdm) contains multiple improvements over [@mdx-js/mdx](https://github.com/mdx-js/mdx), the compiler used internally by next-mdx-remote, but there might be some breaking behaviour changes.
+Please check your markdown output to verify.
+
+Some new possibilities include loading components directly in the mdx file using the import syntax and including js code which could be compiled at the build step.
+
+For example, the following jsx snippet can be used directly in an MDX file to render the page title component:
+
+```js
+import PageTitle from './PageTitle.js'
+
+;<PageTitle> Using JSX components in MDX </PageTitle>
+```
+
+import PageTitle from './PageTitle.js'
+
+<PageTitle> Using JSX components in MDX </PageTitle>
+
+The default configuration resolves all components relative to the `components` directory.
+
+**Note**:
+Components which require external image loaders would require additional esbuild configuration.
+Components which are dependent on global application state on lifecycle like the Nextjs `Link` component would also not work with this setup as each mdx file is built indepedently.
+For such cases, it is better to use component substitution.
+
 ## Layouts

 You can map mdx blog content to layout components by configuring the frontmatter field. For example, this post is written with the new `PostSimple` layout!
@ -110,7 +143,7 @@ Information on authors is now split from `siteMetadata.json` and stored in its o

 Here's how an author markdown file might looks like:

-```:default.md
+```md:default.md
 ---
 name: Tails Azimuth
 avatar: /static/images/avatar.png
@ -153,3 +186,46 @@ A demo of a multiple author post is shown in the [Introducing Tailwind Nextjs St

 Hover over a code block and you will notice a Github inspired copy button! You can modify `./components/Pre.js` to further customise it.
 The component is passed to `MDXComponents` and modifies all `<pre>` blocks.
+
+## Line highlighting and line numbers
+
+Line highlighting and line numbers is now supported out of the box thanks to the new [rehype-prism-plus plugin](https://github.com/timlrx/rehype-prism-plus)
+
+The following javascript code block:
+
+````
+```js {1, 3-4} showLineNumbers
+var num1, num2, sum
+num1 = prompt('Enter first number')
+num2 = prompt('Enter second number')
+sum = parseInt(num1) + parseInt(num2) // "+" means "add"
+alert('Sum = ' + sum) // "+" means combine into a string
+```
+````
+
+will appear as:
+
+```js {1,3-4} showLineNumbers
+var num1, num2, sum
+num1 = prompt('Enter first number')
+num2 = prompt('Enter second number')
+sum = parseInt(num1) + parseInt(num2) // "+" means "add"
+alert('Sum = ' + sum) // "+" means combine into a string
+```
+
+To modify the styles, change the following class selectors in the `tailwind.css` file:
+
+```css
+.code-line {
+  @apply pl-4 -mx-4 border-l-4 border-gray-800;
+}
+
+.highlight-line {
+  @apply -mx-4 bg-gray-700 bg-opacity-50 border-l-4 border-primary-500;
+}
+
+.line-number::before {
+  @apply pr-4 -ml-2 text-gray-400;
+  content: attr(line);
+}
+```
--- a/data/blog/pictures-of-canada.mdx
+++ b/data/blog/pictures-of-canada.mdx
@ -59,42 +59,26 @@ When MDX v2 is ready, one could potentially interleave markdown in jsx directly!
 ### Photo Credits

 <div>
-  Maple photo by{' '}
-  <a href="https://unsplash.com/@i_am_g?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">
-    Guillaume Jaillet
-  </a>{' '}
-  on{' '}
-  <a href="https://unsplash.com/s/photos/canada?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">
-    Unsplash
-  </a>
+  Maple photo by [Guillaume
+  Jaillet](https://unsplash.com/@i_am_g?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText)
+  on
+  [Unsplash](https://unsplash.com/s/photos/canada?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText)
 </div>
 <div>
-  Mountains photo by{' '}
-  <a href="https://unsplash.com/@john_artifexfilms?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">
-    John Lee
-  </a>{' '}
-  on{' '}
-  <a href="https://unsplash.com/s/photos/canada?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">
-    Unsplash
-  </a>
+  Mountains photo by [John
+  Lee](https://unsplash.com/@john_artifexfilms?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText)
+  on
+  [Unsplash](https://unsplash.com/s/photos/canada?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText)
 </div>
 <div>
-  Lake photo by{' '}
-  <a href="https://unsplash.com/@tjholowaychuk?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">
-    Tj Holowaychuk
-  </a>{' '}
-  on{' '}
-  <a href="https://unsplash.com/s/photos/canada?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">
-    Unsplash
-  </a>
+  Lake photo by [Tj
+  Holowaychuk](https://unsplash.com/@tjholowaychuk?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText)
+  on
+  [Unsplash](https://unsplash.com/s/photos/canada?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText)
 </div>
 <div>
-  Toronto photo by{' '}
-  <a href="https://unsplash.com/@matthewhenry?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">
-    Matthew Henry
-  </a>{' '}
-  on{' '}
-  <a href="https://unsplash.com/s/photos/canada?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">
-    Unsplash
-  </a>
+  Toronto photo by [Matthew
+  Henry](https://unsplash.com/@matthewhenry?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText)
+  on
+  [Unsplash](https://unsplash.com/s/photos/canada?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText)
 </div>