exhesham / ngx-markdown

Angular 2+ markdown component/directive to parse static or remote content to html

ngx-markdown

v1.4.0 Repository has been renamed from ng2-markdown-to-html to ngx-markdown. Follow v1.4.0 release notes for quick required changes.

ngx-markdown is an Angular 2+ library that uses marked to parse markdown to html combined with Prism.js for syntax highlight.

Demo available @ jfcere.github.io/ngx-markdown

Table of contents

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

Installation

Use the following command to add ngx-markdown library to your package.json file.

npm install ngx-markdown --save

Configuration

To activate Prism.js syntax highlight you will need to choose a css theme file from node_modules/prismjs/themes directory and add it to your application along with @types/prismjs types file.

Note that you can also find additional themes by browsing the web such as Prism-Themes or Mokokai for example.

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

.angular-cli.json

"styles": [
  "styles.css",
+ "../node_modules/prismjs/themes/prism-okaidia.css"
],

tsconfig.app.json

"compilerOptions": {
  "types": [
+   "prismjs"
  ]
},

Usage

You must import MarkdownModule inside your module to be able to use markdown component and/or directive.

import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
+ import { MarkdownModule } from 'ngx-markdown';

import { HomeComponent } from './home.component';

@NgModule({
  imports: [
    CommonModule,
+    MarkdownModule.forRoot(),
  ],
  declarations: [HomeComponent],
})

ngx-markdown provides one component and one directive to parse your markdown to your web application.

Component

You can use markdown component to either parse static markdown directly from your html markup, load the content from a remote url using src property or bind a variable to your component using data property.

<!-- static markdown -->
<markdown>
  # Markdown
</markdown>

<!-- loaded from remote url -->
<markdown [src]="'path/to/file.md'"></markdown>

<!-- variable binding -->
<markdown [data]="markdown"></markdown>

Directive

The same way the component works, you can use markdown directive to accomplish the same thing.

<!-- static markdown -->
<div markdown>
  # Markdown
</div>

<!-- loaded from remote url -->
<div markdown [src]="'path/to/file.md'"></div>

<!-- variable binding -->
<div markdown [data]="markdown"></div>

Syntax highlight

When using static markdown you are responsible to provide the code block with related language.

<markdown>
+  ```typescript
    const myProp: string = 'value';
+  ```
</markdown>

When using remote url ngx-markdown will use file extension to automatically resolve the code language.

<!-- will use html highlights -->
<markdown [src]="'path/to/file.html'"></markdown>

<!-- will use php highlights -->
<markdown [src]="'path/to/file.php'"></markdown>

When using variable binding you can optionally use language pipe to specify the language of the variable content (default value is markdown when pipe is not used).

<markdown [data]="markdown | language : 'typescript'"></markdown>

Demo application

A demo is available @ https://jfcere.github.io/ngx-markdown and it source code can be found inside the src/app/markdown-demo directory.

The following commands will clone the repository, install npm dependencies and serve the application @ http://localhost:4200

git clone https://github.com/jfcere/ngx-markdown.git
npm install
ng serve

AoT compilation

Building with AoT is part of the CI and is tested every time a commit occurs so you don't have to worry at all.

Road map

Here is the list of tasks that will be done on this library in a near future ...

• Add CircleCI integration
• Publish demo on github pages
• Add variable binding feature
• Transpile library to Javascript
• Make Prism highlight optional
• Support Prism.js customizing options (line-numbers, line-height, ...)

Contribution

Contributions are always welcome, just make sure that ...

• Your code style matches with the rest of the project
• Unit tests pass
• Linter passes

License

Licensed under MIT.