Home

Awesome

Build project npm version

ngx-remark

This library allows to render Markdown with custom HTML templates in Angular.

Most libraries for rendering Markdown in Angular first transform the Markdown to HTML and then use the innerHTML attribute to render the HTML. The problem of this approach is that there is no way to use Angular components or directives in any part of the generated HTML.

In contrast, this library uses Remark to parse the Markdown into an abstract syntax tree (AST) and then uses Angular to render the AST as HTML. The <remark> component renders all standard Markdown elements with default built-in templates, but it also allows to override the templates for any element.

Typical use cases include:

Installation

Install the library with npm:

npm install ngx-remark

Importing the library

Import the RemarkModule in your application module:

import { RemarkModule } from 'ngx-remark';

@NgModule({
  imports: [
    RemarkModule
  ]
})
export class AppModule { }

Usage

Use the <remark> component to render Markdown:

<remark markdown="# Hello World"></remark>

The above renders the HTML will all default templates.

You can customize the Remark processing pipeline with the optional processor input (the default is unified().use(remarkParse)):

<remark [markdown]="markdown" [processor]="processor"></remark>

As an example, the following uses the remark-gfm plugin to support GitHub Flavored Markdown:

import { RemarkGfm } from 'remark-gfm';

processor = unified().use(remarkParse).use(RemarkGfm);

You can override the templates for any node type with the <ng-template> element and the remarkTemplate directive:

<remark markdown="# Hello World">

  <ng-template remarkTemplate="heading" let-node>
    <h1 *ngIf="node.depth === 1" [remarkNode]="node" style="color: red;"></h1>
    <h2 *ngIf="node.depth === 2" [remarkNode]="node"></h2>
    ...
  </ng-template>

</remark>

In the above example, note the following:

It is possible to use the structural shorthand syntax for the remarkTemplate directive:

<remark markdown="This is a paragraph with [link](https://example.com)">

  <span *remarkTemplate="'link'; let node" style="color: green;">
    This is a link: <a [href]="node?.url" [title]="node.title ?? ''" [remarkNode]="node"></a>
  </span>

</remark>

If the node type doesn't have children, the [remarkNode] directive isn't required:

<remark [markdown]="markdownWithCodeBlocks">

  <my-code-editor *remarkTemplate="'code'; let node"
    [code]="node.code"
    [language]="node.lang">
  </my-code-editor>

</remark>

You can customize various node types by adding as many templates as needed:

<remark [markdown]="markdownWithCodeBlocks">

  <my-code-editor *remarkTemplate="'code'; let node"
    [code]="node.code"
    [language]="node.lang">
  </my-code-editor>

  <span *remarkTemplate="'link'; let node" style="color: green;">
    This is a link: <a [href]="node?.url" [title]="node.title ?? ''" [remarkNode]="node"></a>
  </span>

</remark>