Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/JulianCataldo/remark-embed
A `remark` plugin for embedding remote / local Markdown or code snippets inside Markdown.
https://github.com/JulianCataldo/remark-embed
markdown remark remark-plugin
Last synced: about 1 month ago
JSON representation
A `remark` plugin for embedding remote / local Markdown or code snippets inside Markdown.
- Host: GitHub
- URL: https://github.com/JulianCataldo/remark-embed
- Owner: JulianCataldo
- License: isc
- Created: 2022-09-20T00:30:45.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2022-09-22T17:57:46.000Z (about 2 years ago)
- Last Synced: 2024-08-03T22:07:36.687Z (about 2 months ago)
- Topics: markdown, remark, remark-plugin
- Language: TypeScript
- Homepage:
- Size: 144 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# `remark-embed`
[](https://www.npmjs.com/package/remark-embed)
[](./LICENSE)
[](https://makeapullrequest.com)
[](https://unifiedjs.com)
[](http://www.typescriptlang.org/)
[](https://prettier.io)
[](https://editorconfig.org)
[](https://eslint.org)
Embed local or remote files as plain text or nodes tree.
``
``
> **Warning**: Work-in-progress
> Basic features below are working well, but more tests in different contexts are required.
> Also, more features are to be added.
## Features
- **Remote** URL Markdown embed.
- **Local** file Markdown embed.
`remark-embed` injects living AST into current pipeline node tree.
That means all of your further transformations affect these embedded trees, too.
> **Note**: There is a special option for Astro which doesn't seems to apply its `remark-gfm`, whereas all other remark plugin are working fine. _Needs more investigation_.
## Installation
```sh
pnpm i remark-embed
```
Inside a **unified** pipeline:
```js
import remarkEmbed from 'remark-embed';
/* … */
.use(remarkEmbed, { logLevel: 'info' })
/* … */
```
_-Or-_ in an **Astro** configuration:
```js
import remarkEmbed, { Settings as RemarkEmbedSettings } from 'remark-embed';
import remarkGfm from 'remark-gfm';
export default defineConfig({
/* … */
markdown: {
remarkPlugins: [
[remarkEmbed, { logLevel: 'info' } as RemarkEmbedSettings],
// You need to include GFM again, as using a custom remark plugin list
// with Astro will discard its internal GFM plugin.
remarkGfm,
],
},
/* … */
});
```
> **Warning** 1: You need a Node.js version which support the native `fetch` API.
> **Warning** 2: It's not tested with MDX yet.
Package is **100% ESM**, including dependencies.
## Usage
In your Markdown file, just drop an ``:
```markdown
…**My Markdown**…
# Remote Mardown file
> Job is done
# Local Mardown file
> Job is done
```
## Use cases
Collect:
- **Remotely hosted** MD's for when it's not practical to gather them locally.
- **Local** READMEs in a mono-repo. for a documentation website to use.
Regarding **local** embeds, why not just use relative paths for local MD outside current project, instead of embedding it?
Reasons are:
- Having everything in the current working directory.
- Some bundler doesn't like importing stuff from outer directory.
- Not having to deal with symbolic links, which are sometimes unpredictable.
- Re-compose / selectively embedded Markdowns file or parts depending on context.
> **Warning**: Security concerns.
> Use this plugin at your own risk.
> **You should trust your sources**.
## Demos
https://user-images.githubusercontent.com/603498/191607897-3fe0f1ac-56ea-459a-ac2d-d833ecff0edd.mp4
---
https://user-images.githubusercontent.com/603498/191610234-af1d8db0-02b5-4b78-9d17-ffef1a799da1.mp4
## Interface
```ts
export interface Settings {
/**
* Load GitHub flavored Markdown again (useful for Astro).
*
* **Default**: `true`
*/
useGfm?: boolean;
/**
* **Default**: `'silent'`
*/
logLevel?: 'silent' | 'info' | 'debug';
/**
* For remote files.
*
* **Default**: `true`
*/
useCache?: boolean;
}
```
## Features ideas
It might be useful to:
- Embed **arbitrary files as plain text**, without AST transformation. E.g. for code snippets in fences.
- Target specific lines range with **hash** `embed:../foo.md#L22-L45`.
- Target a specific CSS ID (maybe classes?) to embed: `embed:../foo.md#main`.
## Similar / inspired by:
- [gridsome-remark-embed-snippet](https://github.com/sammndhr/gridsome-remark-embed-snippet/blob/master/index.js)
- [gatsby/gatsby-remark-embed-snippet](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-remark-embed-snippet/src/index.js)
- [gatsby-remark-embed-markdown](https://github.com/jtstodola/gatsby-remark-embed-markdown/blob/gatsby-remark-embed-markdown/index.js)
- [markdown-magic](https://github.com/DavidWells/markdown-magic)
---
Related projects:
- [retext-case-police](https://github.com/JulianCataldo/retext-case-police): Check popular names casing. Example: ⚠️ `github` → ✅ `GitHub`
- [remark-lint-frontmatter-schema](https://github.com/JulianCataldo/remark-lint-frontmatter-schema): Validate your Markdown frontmatter data against a JSON schema.
- [astro-content](https://github.com/JulianCataldo/astro-content): A text based, structured content manager, for edition and consumption.
---
🔗 [JulianCataldo.com](https://www.juliancataldo.com)