https://github.com/johnzanussi/astro-mdx-code-blocks

An easy way to customize the syntax highlighting of MDX fenced code blocks by providing your own Astro component.
https://github.com/johnzanussi/astro-mdx-code-blocks

astro integration mdx syntax-highlighting

Last synced: 3 months ago
JSON representation

An easy way to customize the syntax highlighting of MDX fenced code blocks by providing your own Astro component.

• Host: GitHub
• URL: https://github.com/johnzanussi/astro-mdx-code-blocks
• Owner: johnzanussi
• License: mit
• Created: 2023-03-14T21:42:00.000Z (almost 2 years ago)
• Default Branch: main
• Last Pushed: 2024-04-26T18:12:29.000Z (8 months ago)
• Last Synced: 2024-09-27T21:41:01.272Z (3 months ago)
• Topics: astro, integration, mdx, syntax-highlighting
• Language: TypeScript
• Homepage:
• Size: 15.6 KB
• Stars: 13
• Watchers: 1
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# 🚀 Astro MDX Code Blocks

Use a custom Astro component to render and syntax highlight code snippets in your MDX files.

## Demo

View a demo of the integration in action on [StackBlitz](https://stackblitz.com/edit/astro-mdx-code-blocks-example?file=src%2Fpages%2Findex.mdx,astro.config.mjs,src%2Fcomponents%2FCodeBlock.astro).

## Installation

Due to the extra configuration needed, you must manually install this integration.

> This integration depends on the [`AutoImport`](https://github.com/delucis/astro-auto-import) and [`@astrojs/mdx`](https://docs.astro.build/en/guides/integrations-guide/mdx/) integrations.

```bash

npm install -D astro-mdx-code-blocks astro-auto-import @astrojs/mdx

```

## Code Block Component

Create a component in your project that will be used to render fenced code blocks.

### Props

The code block component provided to the integration receives the following props.

| Prop | Type | Optional | Description |

| ---- | ---- | -------- | ------------|

| code | `String` | No | The raw contents of the fenced code block from the `.mdx` file.

| lang | `String` | Yes | The language detected from the fenced code block. |

| filename | `String` | Optional | If a `// filename.ts` is provided at the top of the code block it will be removed and sent in in the `filename` prop. |

In addition, you can export the following type definition from the integration.

```ts

type CodeBlockProps = {

    code: string;

    lang?: string;

    filename?: string;

};

```

```ts

import type { CodeBlockProps } from 'astro-mdx-code-blocks';

```

### Example Component

> This example uses Astro's [Prism component](https://docs.astro.build/en/reference/api-reference/#prism-) for syntax highlighting. However, you can use any library you'd like as the component has access to the raw `code` string.

`src/components/CodeBlock.astro`

```astro

---

import { Prism } from '@astrojs/prism';

const {

    code,

    lang,

    filename,

} = Astro.props;

const hasLang = !!lang;

const hasFileName = !!filename;

const showHeader = hasLang || hasFileName;

---

    {showHeader && (

        

            {hasFileName && (

                

                    {filename}

                

            )}

            {hasLang && (

                

                    {lang}

                

            )}

        

    )}

    

```

## Configuration

* Import the `AutoImport` and `mdx` integrations.

* Import `MDXCodeBlocks` and `mdxCodeBlockAutoImport` from `astro-mdx-code-blocks`.

* Add `AutoImport`, `MDXCodeBlocks`, and `mdx` to the `integrations` config option.

* Use the `mdxCodeBlockAutoImport` function to provide the `AutoImport` integration the path to your custom Astro component.

```js

import { defineConfig } from 'astro/config';

import AutoImport from 'astro-auto-import';

import mdx from '@astrojs/mdx';

import MDXCodeBlocks, { mdxCodeBlockAutoImport } from 'astro-mdx-code-blocks';

export default defineConfig({

    // ...

    integrations: [

         AutoImport({

            imports: [

                mdxCodeBlockAutoImport('src/components/CodeBlock.astro')

            ],

        }),

        MDXCodeBlocks(),

        mdx(),

    ],

});

```

> AutoImport must come before `MDXCodeBlocks` and `MDXCodeBlocks` must come before `mdx`.

## Usage

Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) in your MDX files as you normally would. As noted above, the integration will pull out certain metadata from the block and provide it to your custom Astro component.

## Contributing

Issues and pull requests are welcome.

## License

[MIT](LICENSE)