ngx-markdown

ngx-markdown

ngx-markdown is an Angular library that combines...

• Marked to parse markdown to HTML
• Prism.js for language syntax highlight
• Emoji-Toolkit for emoji support
• KaTeX for math expression rendering
• Mermaid for diagrams and charts visualization
• Clipboard.js to copy code blocks to clipboard

Demo available @ https://jfcere.github.io/ngx-markdown
StackBlitz available @ https://stackblitz.com/edit/ngx-markdown

Table of contents

• Installation
• Configuration
• Usage
• Renderer
• Syntax highlight
• Demo application
• AoT compilation
• Road map
• Contribution
• Support Development

Installation

ngx-markdown

To add ngx-markdown along with the required marked library to your package.json use the following commands.

npm install ngx-markdown marked@^18.0.0 --save

Syntax highlight

:bell: Syntax highlight is optional, skip this step if you are not planning to use it

To add Prism.js library to your package.json use the following command.

npm install prismjs@^1.30.0 --save

To activate Prism.js syntax highlight you will need to include...

• prism.js core library - node_modules/prismjs/prism.js file
• a highlight css theme - from node_modules/prismjs/themes directory
• desired code language syntax files - from node_modules/prismjs/components directory

Additional themes can be found by browsing the web such as Prism-Themes or Mokokai for example.

If you are using Angular CLI you can follow the angular.json example below...

"styles": [
  "styles.css",
+ "node_modules/prismjs/themes/prism-okaidia.css"
],
"scripts": [
+ "node_modules/prismjs/prism.js",
+ "node_modules/prismjs/components/prism-csharp.min.js", # c-sharp language syntax
+ "node_modules/prismjs/components/prism-css.min.js" # css language syntax
]

Line Numbers plugin

To use the line numbers plugin that shows line numbers in code blocks, in addition to Prism.js configuration files, you will need to include the following files from prismjs/plugins/line-numbers directory to your application:

• CSS styling for line numbers - prism-line-numbers.css
• line numbers plugin script - prism-line-numbers.js

If you are using Angular CLI you can follow the angular.json example below...

"styles": [
  "src/styles.css",
  "node_modules/prismjs/themes/prism-okaidia.css",
+ "node_modules/prismjs/plugins/line-numbers/prism-line-numbers.css"
],
"scripts": [
  "node_modules/prismjs/prism.js",
  "node_modules/prismjs/components/prism-csharp.min.js",
  "node_modules/prismjs/components/prism-css.min.js",
+ "node_modules/prismjs/plugins/line-numbers/prism-line-numbers.js"
]

Using markdown component and/or directive, you will be able to use the lineNumbers property to activate the plugin. The property can be used in combination with either data for variable binding, src for remote content or using transclusion for static markdown.

Additionally, you can use start input property to specify the offset number for the first display line.

Line Highlight plugin

To use the line highlight plugin that highlights specific lines and/or line ranges in code blocks, in addition to Prism.js configuration files, you will need to include the following files from prismjs/plugins/line-highlight directory to your application:

• CSS styling for line highlight - prism-line-highlight.css
• line highlight plugin script - prism-line-highlight.js

If you are using Angular CLI you can follow the angular.json example below...

"styles": [
  "src/styles.css",
  "node_modules/prismjs/themes/prism-okaidia.css",
+ "node_modules/prismjs/plugins/line-highlight/prism-line-highlight.css"
],
"scripts": [
  "node_modules/prismjs/prism.js",
  "node_modules/prismjs/components/prism-csharp.min.js",
  "node_modules/prismjs/components/prism-css.min.js",
+ "node_modules/prismjs/plugins/line-highlight/prism-line-highlight.js"
]

Using markdown component and/or directive, you will be able to use the lineHighlight property to activate the plugin. The property can be used in combination with either data for variable binding, src for remote content or using transclusion for static markdown.

Use line input property to specify the line(s) to highlight and optionally there is a lineOffset property to specify the starting line of code your snippet represents.

Command Line Plugin

To use the command line plugin that displays a command line with a prompt and, optionally, the output/response from the commands, you will need to include the following files from prismjs/plugins/command-line directory to your application:

• CSS styling for command line - prism-command-line.css
• command line plugin script - prism-command-line.js

If you are using Angular CLI you can follow the angular.json example below...

"styles": [
  "src/styles.css",
  "node_modules/prismjs/themes/prism-okaidia.css",
+ "node_modules/prismjs/plugins/command-line/prism-command-line.css"
],
"scripts": [
  "node_modules/prismjs/prism.js",
  "node_modules/prismjs/components/prism-csharp.min.js",
  "node_modules/prismjs/components/prism-css.min.js",
+ "node_modules/prismjs/plugins/command-line/prism-command-line.js"
]

Using markdown component and/or directive, you will be able to use the commandLine property to activate the plugin. The property can be used in combination with either data for variable binding, src for remote content or using transclusion for static markdown.

For a server command line, specify the user and host names using the user and host input properties. The resulting prompt displays a # for the root user and $ for all other users. For any other command line, such as a Windows prompt, you may specify the entire prompt using the prompt input property.

You may also specify the lines to be presented as output (no prompt and no highlighting) through the output property in the following simple format:

• A single number refers to the line with that number
• Ranges are denoted by two numbers, separated with a hyphen (-)
• Multiple line numbers or ranges are separated by commas
• Whitespace is allowed anywhere and will be stripped off

Optionally, to automatically present some lines as output without providing the line numbers, you can prefix those lines with any string and specify the prefix using the filterOutput input property. For example, [filterOutput]="'(out)'" will treat lines beginning with (out) as output and remove the prefix.

'"
  [filterOutput]="'(out)'">
  ```powershell
  Get-Date
  (out)
  (out)Sunday, November 7, 2021 8:19:21 PM
  (out)
  `​``

Emoji support

:bell: Emoji support is optional, skip this step if you are not planning to use it

To add Emoji-Toolkit library to your package.json use the following command.

npm install emoji-toolkit@^11.0.0 --save

To activate Emoji-Toolkit for emoji suppport you will need to include...

• Emoji-Toolkit library - node_modules/emoji-toolkit/lib/js/joypixels.min.js

If you are using Angular CLI you can follow the angular.json example below...

"scripts": [
+ "node_modules/emoji-toolkit/lib/js/joypixels.min.js",
]

Emoji plugin

Using markdown component and/or directive, you will be able to use the emoji property to activate Emoji-Toolkit plugin that converts emoji shortnames such as :heart: to native unicode emojis.

  I :heart: ngx-markdown

:blue_book: You can refer to this Emoji Cheat Sheet for a complete list of shortnames.

Math rendering

:warning: Math rendering is optional, and no KaTeX packages are required if you are not planning to use it. However, Angular applications using the Vite-based application builder may need to add marked-katex-extension to externalDependencies in the build.options section of angular.json:

{
  "externalDependencies": ["marked-katex-extension"]
}

To add KaTeX math rendering support to your application install the KaTeX runtime and the parser extension:

npm install katex@^0.16.0 marked-katex-extension@^5.0.0 --save

Applications using the katex property must install both katex and marked-katex-extension.

To activate KaTeX math rendering you need to include the KaTeX stylesheet:

"styles": [
  "styles.css",
+ "node_modules/katex/dist/katex.min.css"
],

KaTeX plugin

Using the markdown component and/or directive, you can enable KaTeX rendering with the katex property:

Global configuration

Global KaTeX options can be provided with the KATEX_OPTIONS injection token when configuring provideMarkdown().

provideMarkdown({
  katexOptions: {
    provide: KATEX_OPTIONS,
    useValue: {
      displayMode: false,
      throwOnError: false,
    },
  },
}),

Component configuration

Optionally, you can specify the KaTeX options at the component-level through katexOptions property:

import { KatexOptions } from 'ngx-markdown';

public options: KatexOptions = {
  displayMode: true,
  throwOnError: false,
  errorColor: '#cc0000',
  delimiters: [...],
};

:blue_book: Follow official KaTeX options documentation for more details on available options.

Diagrams tool

:bell: Diagram support is optional, skip this step if you are not planning to use it

To add Mermaid library to your package.json use the following command.

npm install mermaid@^11.0.0 --save

To activate Mermaid diagramming and charting tool you will need to include...

• Mermaid JavaScript library - node_modules/mermaid/dist/mermaid.min.js file

If you are using Angular CLI you can follow the angular.json example below...

"scripts": [
+ "node_modules/mermaid/dist/mermaid.min.js",
]

Mermaid plugin

Using markdown component and/or directive, you will be able to use the mermaid property to activate Mermaid plugin that renders Markdown-inspired text definitions to create and modify diagrams dynamically.

Global configuration

You can provide a global configuration for mermaid configuration options to use across your application with the mermaidOptions when configuring provideMarkdown.

provideMarkdown({
  mermaidOptions: {
    provide: MERMAID_OPTIONS,
    useValue: {
      darkMode: true,
      look: 'handDrawn',
      ...
    },
  },
}),

Component configuration

Addi