TypeScript icon, indicating that this package has built-in type declarations

1.3.1 • Public • Published


NPM ISC License PRs Welcome
TypeScript Prettier EditorConfig ESLint

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

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

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.


  • 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.


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.
  /* … */

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.


In your Markdown file, just drop an <!-- embed:./<file>.md -->:

**My Markdown**# Remote Mardown file

<!-- embed: -->

> Job is done

# Local Mardown file

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

> Job is done

Use cases


  • 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.



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:../
  • Target a specific CSS ID (maybe classes?) to embed: embed:../

Similar / inspired by:

Related projects:


Package Sidebar


npm i remark-embed

Weekly Downloads






Unpacked Size

19.1 kB

Total Files


Last publish


  • julian.cataldo