Awesome
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:
- Displaying code blocks with a custom code editor.
- Displaying custom tooltips over certain elements.
- Allowing custom actions with buttons or links.
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:
- The headings of depth 1 are customized with a red color.
- The
remarkTemplate
attribute must be set to the name of the MDAST node type. - The
let-node
attribute is required to make thenode
variable available in the template. Thenode
variable is of typeNode
and can be used to access the properties of the node. - Since the heading node might have children (in particular
text
nodes), theremarkNode
directive is used to render the children of the node.
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>