Home

Awesome

remark-embed

NPM ISC License PRs Welcome
unified
TypeScript Prettier EditorConfig ESLint

<!-- [![Downloads](https://img.shields.io/npm/dw/remark-embed)](https://www.npmjs.com/package/remark-embed) --> <!-- [![Renovate](https://img.shields.io/badge/Renovate-enabled-17a2b8?logo=renovatebot)](https://app.renovatebot.com/dashboard) -->

Embed local or remote files as plain text or nodes tree.

<!-- embed:http://myremote.stuff/file.md -->
<!-- embed:../../../some-parent-dir/file.md -->

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

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

pnpm i remark-embed

Inside a unified pipeline:

import remarkEmbed from 'remark-embed';

/* … */
  .use(remarkEmbed, { logLevel: 'info' })
/* … */

-Or- in an Astro configuration:

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 <!-- embed:./<file>.md -->:

…**My Markdown**…

# Remote Mardown file

<!-- embed:https://raw.githubusercontent.com/JulianCataldo/JulianCataldo/master/README.md -->

> Job is done

# Local Mardown file

<!-- embed:../../../README.md -->

> Job is done

Use cases

Collect:

Regarding local embeds, why not just use relative paths for local MD outside current project, instead of embedding it?

Reasons are:

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

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:

Similar / inspired by:


Related projects:


🔗  JulianCataldo.com