Getting Started

A remark plugin providing an alternative syntax to author diff code blocks in Markdown.

To learn more about some of the drawbacks of classic diff code blocks and how remark-auto-diff tries to solve them, check out the “Why a new syntax?” page.

Installation

1. Install remark-auto-diff using your favorite package manager:

   npm

   npm i remark-auto-diff

   pnpm

   pnpm add remark-auto-diff

   yarn

   yarn add remark-auto-diff

   ni

   ni remark-auto-diff

2. The plugin can be used in any project using remark including Astro and Starlight.

   Starlight

   Add the plugin in your Astro configuration in the astro.config.mjs file.

   astro.config.mjs

   // @ts-check
   import starlight from '@astrojs/starlight'
   import { defineConfig } from 'astro/config'
   import { remarkAutoDiff } from 'remark-auto-diff'
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'My Docs',
       }),
     ],
     markdown: {
       remarkPlugins: [remarkAutoDiff],
     },
   })

   Astro

   Add the plugin in your Astro configuration in the astro.config.mjs file.

   astro.config.mjs

   // @ts-check
   import { defineConfig } from 'astro/config'
   import { remarkAutoDiff } from 'remark-auto-diff'
   
   export default defineConfig({
     markdown: {
       remarkPlugins: [remarkAutoDiff],
     },
   })

   remark

   You can use the remark-auto-diff plugin by adding it to your remark pipeline.

   markdown.js

   import { remark } from 'remark'
   import { remarkAutoDiff } from 'remark-auto-diff'
   
   const file = await remark().use(remarkAutoDiff).process('Your markdown here')
   
   console.log(String(file))

Usage

When using the remark-auto-diff plugin, a first code block is used to specify the “before” version of the code immediately followed by a second code block to specify the “after” version of the code. The auto-diff attribute is added to the opening code fence of both code blocks to specify that the plugin should compute the diff automatically.

Markdown Code Editor

My Markdown content.


```js auto-diff
console.log('removed line')
```


```js auto-diff
console.log('added line')
```

The above example will automatically be transformed by the plugin to:

My Markdown content.

```diff lang=js
- console.log('removed line')
+ console.log('added line')
```

When rendered by Expressive Code, the above example would be rendered as:

console.log('removed line')
console.log('added line')