|
| 1 | +# @studiocms/markdown-remark |
| 2 | + |
| 3 | +[](https://npm.im/@studiocms/markdown-remark) |
| 4 | +[](https://biomejs.dev/) |
| 5 | +[](https://astro.build) |
| 6 | + |
| 7 | +## Overview |
| 8 | + |
| 9 | +`@studiocms/markdown-remark` is a powerful Markdown parser and transformer built on top of [remark](https://github.com/remarkjs/remark). It provides seamless integration with [Astro](https://astro.build/), allowing you to easily parse and transform Markdown content within your Astro projects. |
| 10 | + |
| 11 | +This project is heavily based on and compatible with Astro's built-in `@astrojs/markdown-remark` |
| 12 | + |
| 13 | +## Features |
| 14 | + |
| 15 | +- **Markdown Parsing**: Parse Markdown content into an abstract syntax tree (AST) using remark. |
| 16 | +- **Astro Integration**: Easily integrate with Astro to transform Markdown content into HTML. |
| 17 | +- **Custom Plugins**: Extend the functionality with custom remark plugins. |
| 18 | +- **Configurable**: Highly configurable to suit your specific needs. |
| 19 | + |
| 20 | +## Installation |
| 21 | + |
| 22 | +To install `@studiocms/markdown-remark`, use your preferred package manager: |
| 23 | + |
| 24 | +```bash |
| 25 | +npm install @studiocms/markdown-remark |
| 26 | +# or |
| 27 | +yarn add @studiocms/markdown-remark |
| 28 | +# or |
| 29 | +pnpm add @studiocms/markdown-remark |
| 30 | +``` |
| 31 | + |
| 32 | +## Usage |
| 33 | + |
| 34 | +### As an Astro Integration |
| 35 | + |
| 36 | +With the Astro integration enabled, you can either pass in custom components into your astro config, or manually for the specific render your trying to do shown in the following methods. |
| 37 | + |
| 38 | +#### Setup the integration |
| 39 | + |
| 40 | +**`astro.config.mjs`** |
| 41 | + |
| 42 | +```ts |
| 43 | +import markdownRemark from '@studiocms/markdown-remark'; |
| 44 | +import { defineConfig } from 'astro/config'; |
| 45 | + |
| 46 | +export default defineConfig({ |
| 47 | + markdown: { |
| 48 | + /* |
| 49 | + * Your Customizations here based on: |
| 50 | + * https://docs.astro.build/en/reference/configuration-reference/#markdown-options |
| 51 | + */ |
| 52 | + }, |
| 53 | + integrations: [markdownRemark({ |
| 54 | + // Used for injecting CSS for Headings and Callouts |
| 55 | + injectCSS: true, |
| 56 | + // User defined components that will be used when processing markdown |
| 57 | + components: { |
| 58 | + // Example of a custom defined component |
| 59 | + custom: "./src/components/Custom.astro", |
| 60 | + }, |
| 61 | + // Custom Markdown config |
| 62 | + markdown: { |
| 63 | + // Configure the available callout themes |
| 64 | + callouts: { |
| 65 | + theme: 'obsidian' // Can also be 'github' or 'vitepress' |
| 66 | + }, |
| 67 | + autoLinkHeadings: true, |
| 68 | + sanitize: {} // see https://github.com/natemoo-re/ultrahtml?tab=readme-ov-file#sanitization for full options |
| 69 | + } |
| 70 | + })], |
| 71 | +}); |
| 72 | +``` |
| 73 | + |
| 74 | +#### Use the integration |
| 75 | + |
| 76 | +**`src/pages/index.astro`** |
| 77 | + |
| 78 | +```astro |
| 79 | +--- |
| 80 | +import { Markdown } from 'studiocms:markdown-remark'; |
| 81 | +import Custom from '../components/Custom.astro'; |
| 82 | +--- |
| 83 | +<html> |
| 84 | + <head> |
| 85 | + <meta charset="utf-8" /> |
| 86 | + <meta name="viewport" content="width=device-width" /> |
| 87 | + <title>Example</title> |
| 88 | + </head> |
| 89 | + <body> |
| 90 | + <Markdown content={`# Hello World! <custom></custom>`} components={{ custom: Custom }} /> |
| 91 | + </body> |
| 92 | +</html> |
| 93 | +``` |
| 94 | + |
| 95 | +OR |
| 96 | + |
| 97 | +```astro |
| 98 | +--- |
| 99 | +import { render } from 'studiocms:markdown-remark'; |
| 100 | +import Custom from '../components/Custom.astro'; |
| 101 | +
|
| 102 | +// @ts-ignore |
| 103 | +const { html } = await render('# Hello World! <custom></custom>', {}, { $$result, {custom: Custom} }) |
| 104 | +--- |
| 105 | +<html> |
| 106 | + <head> |
| 107 | + <meta charset="utf-8" /> |
| 108 | + <meta name="viewport" content="width=device-width" /> |
| 109 | + <title>Example</title> |
| 110 | + </head> |
| 111 | + <body> |
| 112 | + {html} |
| 113 | + </body> |
| 114 | +</html> |
| 115 | +``` |
| 116 | + |
| 117 | +### Using the Markdown component directly without the integration |
| 118 | + |
| 119 | +**`src/pages/index.astro`** |
| 120 | + |
| 121 | +```astro |
| 122 | +--- |
| 123 | +import { Markdown } from '@studiocms/markdown-remark/components'; |
| 124 | +import H1 from '../components/H1.astro'; |
| 125 | +--- |
| 126 | +<html> |
| 127 | + <head> |
| 128 | + <meta charset="utf-8" /> |
| 129 | + <meta name="viewport" content="width=device-width" /> |
| 130 | + <title>Example</title> |
| 131 | + </head> |
| 132 | + <body> |
| 133 | + <Markdown content={`# Hello world!`} components={{ h1: H1 }} /> |
| 134 | + </body> |
| 135 | +</html> |
| 136 | +``` |
| 137 | + |
| 138 | +## Changelog |
| 139 | + |
| 140 | +See the [Changelog](https://github.com/withstudiocms/studiocms/blob/main/packages/@studiocms/markdown-remark/CHANGELOG.md) for the change history of this package. |
| 141 | + |
| 142 | +## Contribution |
| 143 | + |
| 144 | +If you see any errors or room for improvement, feel free to open an [issue or pull request](https://github.com/withstudiocms/studiocms/) . Thank you in advance for contributing! ❤️ |
| 145 | + |
| 146 | +## Licensing |
| 147 | + |
| 148 | +[MIT Licensed](./LICENSE). |
0 commit comments