Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/r4ai/remark-callout
A remark plugin to add obsidian style callouts to markdown
https://github.com/r4ai/remark-callout
callout caution markdown remark remark-plugin
Last synced: 18 days ago
JSON representation
A remark plugin to add obsidian style callouts to markdown
- Host: GitHub
- URL: https://github.com/r4ai/remark-callout
- Owner: r4ai
- License: mit
- Created: 2024-03-06T11:44:11.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-12-11T05:14:50.000Z (23 days ago)
- Last Synced: 2024-12-11T09:10:20.134Z (23 days ago)
- Topics: callout, caution, markdown, remark, remark-plugin
- Language: TypeScript
- Homepage: https://r4ai.github.io/remark-callout/
- Size: 3.6 MB
- Stars: 9
- Watchers: 1
- Forks: 0
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# remark-callout
[](https://badge.fury.io/js/@r4ai%2Fremark-callout)
[](https://codecov.io/gh/r4ai/remark-callout)
[](https://github.com/r4ai/remark-callout/actions/workflows/ci.yml)
[](https://github.com/r4ai/remark-callout/actions/workflows/deploy-packages.yml)
[](https://github.com/r4ai/remark-callout/actions/workflows/github-code-scanning/codeql)
[](https://nodei.co/npm/@r4ai/remark-callout/)
> [!important]
> Website: [https://r4ai.github.io/remark-callout](https://r4ai.github.io/remark-callout)
A remark plugin to add obsidian style callouts to markdown.
```md
> [!note] title here
> body here
```
## Installation
```sh
# npm
npm install @r4ai/remark-callout
# pnpm
pnpm install @r4ai/remark-callout
# bun
bun add @r4ai/remark-callout
```
## Usage
See [Usage](https://r4ai.github.io/remark-callout/docs/en/#usage).
## Quick Start
### Vanilla JS
```ts
import remarkParse from "remark-parse";
import { unified } from "unified";
import remarkCallout from "@r4ai/remark-callout";
import remarkRehype from "remark-rehype";
import rehypeRaw from "rehype-raw";
import rehypeStringify from "rehype-stringify";
const md = `
> [!note] title here
> body here
`;
const html = unified()
.use(remarkParse)
.use(remarkCallout)
.use(remarkRehype, { allowDangerousHtml: true })
.use(rehypeRaw)
.use(rehypeStringify)
.processSync(md)
.toString();
console.log(html);
```
yields:
```html
title here
body here
```
> [!WARNING]
> To display the callout icon as HTML using `options.icon` or `options.foldIcon`, you need to set the `allowDangerousHtml` option to `true` in `remark-rehype` and add `rehype-raw` as a plugin.
### Astro
1. Install the plugin:
```sh
npm install @r4ai/remark-callout
```
2. Add `@r4ai/remark-callout` to remark plugins in your astro config file (e.g. `astro.config.ts`):
```ts
// astro.config.ts
import remarkCallout from "@r4ai/remark-callout";
export default defineConfig({
// ...
markdown: {
// ...
remarkPlugins: [
// ...
remarkCallout,
],
},
});
```
Note: This plugin works fine in MDX files as well. For instructions on how to use MDX with Astro, see [@astrojs/mdx](https://docs.astro.build/en/guides/integrations-guide/mdx/).
3. Start using callouts in your markdown or mdx files:
```md
> [!note] title here
> body here
```
yields:
```html
title here
body here
```
Now you can style the callouts using CSS. Following is an example of how you can style the callouts using Tailwind CSS:
To use the above CSS, you need to configure Astro's TailwindCSS integration to support nested syntax:
```ts
// astro.config.ts
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
export default defineConfig({
integrations: [
tailwind({
// Example: Allow writing nested CSS declarations
// alongside Tailwind's syntax
nesting: true,
}),
],
});
```
cf.
Or if you are using MDX, you can use custom components to style the callouts:
```ts
// astro.config.ts
import { remarkCallout } from "@r4ai/remark-callout";
export default defineConfig({
// ...
markdown: {
// ...
remarkPlugins: [
// ...
[
remarkCallout,
{
root: (callout) => ({
tagName: "callout",
properties: {
calloutType: callout.type,
isFoldable: String(callout.isFoldable),
},
}),
title: (callout) => ({
tagName: "callout-title",
properties: {
calloutType: callout.type,
isFoldable: String(callout.isFoldable),
},
}),
},
],
],
},
});
```
```astro
---
// src/components/Callout.astro
type Props = {
calloutType: string
isFoldable: boolean
}
const { calloutType, isFoldable } = Astro.props
---
```
```astro
---
// src/components/CalloutTitle.astro
type Props = {
callouType: string
isFoldable: boolean
}
const { calloutType, isFoldable } = Astro.props
---
```
```astro
---
// src/pages/callout-example.astro
import { Content, components } from "../content.mdx";
import Callout from "../components/Callout.astro";
import CalloutTitle from "../components/CalloutTitle.astro";
---
```
## Options
See [r4ai.github.io/remark-callout/docs/en/api-reference/type-aliases/options](https://r4ai.github.io/remark-callout/docs/en/api-reference/type-aliases/options)
## Development
### Commands
| Command | Description |
| ----------------------- | ----------------------- |
| `bun install` | Install dependencies |
| `bun run build` | Build the packages |
| `bun run test` | Run tests |
| `bun run test:coverage` | Run tests with coverage |
| `bun run check` | Check the code |
| `bun run check:write` | Check and fix the code |
| `bun run changeset` | Create a changeset |
### Directory Structure
| Directory | Description |
| ------------------------- | -------------------------------------------- |
| `examples/nextjs` | Example Next.js project |
| `packages/remark-callout` | The remark-callout package |
| `packages/website` | The documentation website for remark-callout |
### Getting Started
1. Install dependencies:
```bash
bun install
```
2. Build the packages:
```bash
bun run build
```
3. Check and fix the code:
```bash
bun run check:write
```
4. Run tests with coverage:
```bash
bun run test:coverage
```
5. Launch the documentation website:
```bash
bun run --cwd packages/website dev
```