ngx-markdown

ngx-markdown is an Angular library designed to render Markdown content within Angular applications. It integrates several powerful tools to provide a rich Markdown experience:

• Marked: Parses Markdown into HTML.
• Prism.js: Provides language syntax highlighting for code blocks.
• Emoji-Toolkit: Enables emoji support.
• KaTeX: Renders mathematical expressions.
• Mermaid: Visualizes diagrams and charts.
• Clipboard.js: Adds functionality to copy code blocks to the clipboard.

For standalone applications, use provideMarkdown() in your ApplicationConfig providers array.

Remote Files: If using the [src] attribute to load remote files, you must also provide HttpClient and configure the loader: provideMarkdown({ loader: HttpClient }).

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideMarkdown({ loader: HttpClient }),
  ],
};

To highlight specific lines or ranges, include prism-line-highlight.css and prism-line-highlight.js in your angular.json. Activate it using the lineHighlight property. Use the line property to specify lines (e.g., '6, 10-16') and lineOffset for the starting line.

<markdown
  lineHighlight
  [line]="'6, 10-16'"
  [lineOffset]="5"
  [src]="path/to/file.js">
</markdown>

To convert emoji shortnames (like :heart:) to unicode, install emoji-toolkit and include node_modules/emoji-toolkit/lib/js/joypixels.min.js in your angular.json scripts. Activate it using the emoji property.

npm install emoji-toolkit@^10.0.0 --save

<markdown emoji>
  I :heart: ngx-markdown
</markdown>

To add ngx-markdown and the required marked library to your project, run the following command:

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

To use ngx-markdown in your Angular project, install the package via npm. (Note: Specific installation commands are typically found in the Installation section of the documentation).

npm install ngx-markdown

Syntax highlighting is optional. To use it, install prismjs and configure your angular.json to include the core library, a CSS theme, and the specific language syntax files you need.

Installation:

npm install prismjs@^1.30.0 --save

Angular CLI Configuration Example: Include the theme in styles and the core library plus language components in scripts.

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

To display a command line interface in code blocks, include prism-command-line.css and prism-command-line.js in your angular.json. Activate it with the commandLine property.

Configuration Options:

• user: Specify the user name.
• host: Specify the host name.
• prompt: Specify a custom prompt (e.g., for Windows).
• output: Specify lines to be treated as output using line numbers or ranges (e.g., '2, 4-8').
• filterOutput: Specify a prefix (e.g., '(out)') to automatically identify and strip output lines.

<markdown
  commandLine
  [user]="'chris'"
  [host]="'remotehost'"
  [output]="'2, 4-8'"
  [src]="'path/to/file.bash'">
</markdown>

To show line numbers in code blocks, include the prism-line-numbers.css and prism-line-numbers.js files in your angular.json. You can then activate the plugin using the lineNumbers property on the markdown component or directive. Use the start input to specify the starting line number.

<markdown
  lineNumbers
  [start]="5"
  [src]="path/to/file.js">
</markdown>

To allow users to copy code blocks with one click, install clipboard and include node_modules/clipboard/dist/clipboard.min.js in your angular.json scripts. Activate with the clipboard property.

Customization:

• Global: Provide a custom component via clipboardOptions using the CLIPBOARD_OPTIONS token.
• Local: Provide a custom component via [clipboardButtonComponent] or a template via [clipboardButtonTemplate] on the markdown component.

npm install clipboard@^2.0.11 --save

<markdown 
  clipboard 
  [clipboardButtonTemplate]="buttonTemplate">
</markdown>

ngx-markdown supports standard Markdown header syntax using the # symbol, as well as alternative Setext-style underlining for H1 and H2 headers.

Standard ATX-style headers

Use # followed by a space to define levels 1 through 6:

• # H1
• ## H2
• ### H3
• #### H4
• ##### H5
• ###### H6

Alternative Setext-style headers

For H1 and H2, you can use underlines:

• H1: Use = characters underneath the text.
• H2: Use - characters underneath the text.

To render diagrams, install mermaid and include node_modules/mermaid/dist/mermaid.min.js in your angular.json scripts. Activate with the mermaid property. You can configure Mermaid globally via mermaidOptions in provideMarkdown or locally via the mermaidOptions property on the component.

npm install mermaid@^11.0.0 --save

<markdown
  mermaid
  [src]="path/to/file.md">
</markdown>