ngx-showdown

Angular Showdown

ngx-showdown is an Angular (>=2) integration for Showdown, A Markdown to HTML converter.

---

Demo

• Demo app in source code (live).
• You can play with it in Stackblitz and Plunker.

Install

$ npm install ngx-showdown --save

and install peer dependencies (@angular/common/http for SourceDirective)

$ npm install showdown @angular/common @angular/platform-browser --save

and install type package of Showdown for TypeScript

$ npm install @types/showdown --save-dev

Usage

For more information and explanations, see the full documentation.

Setup ShowdownModule in your app.

Add ShowdownModule to imports of App.

import { NgModule } from '@angular/core';
import { ShowdownModule } from 'ngx-showdown';

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

Or with config (it will init ShowdownConfig provider)

import { NgModule } from '@angular/core';
import { ShowdownModule } from 'ngx-showdown';

@NgModule({
  imports: [ ShowdownModule.forRoot({emoji: true, noHeaderId: true, flavor: 'github'}) ]
})
export class AppModule {}

Add showdown to allowedCommonJsDependencies in the build config of the angular.json file (From angular >= 10).

"build": {
  "builder": "@angular-devkit/build-angular:browser",
  "options": {
     "allowedCommonJsDependencies": [
        "showdown"
     ]
     ...
   }
   ...
},

Use ShowdownComponent in the template

Binding to [value] property

Bind markdown value to value property of showdown component.

<input type="text" [(ngModel)]="text"/>
<showdown [value]="text"></showdown>

Bind value and options.

import { Component } from '@angular/core';
import * as Showdown from 'showdown';

@Component({
  selector: 'some',
  template: '<showdown [value]="text" [options]="options"></showdown>'
})
export class SomeComponent {
  text: string = `
# h1
## h2
`;
  options: Showdown.ShowdownOptions = {...};
  // ...
}

As directive on anther element

<div showdown="# Static" noHeaderId></div>

Markdown in component content

A markdown value in the component content.

<showdown>
# H1
## H2
</showdown>

With options

<showdown [options]="{smartIndentationFix: true}">
    * a
    * b
    * c
</showdown>

As directive on anther element

<span showdown emoji>:showdown:**howdown**</span>

Load .md content (by SourceDirective)

Load markdown content of url source.

<showdown src="README.md"></showdown>

Bind input url to src directive.

<input type="text" placeholder="Url" [(ngModel)]="url"/>
<showdown #sd [src]="url" (error)="sd.render('**Not found..**')">**No Url..**</showdown>

Note: Loading markdown content requires HttpClient of @angular/common/http

Mixing sources

When both Content and [value], It will render [value].

<showdown value="# Value"># Content</showdown>

When both Content and [src], It will render Content and when src loads then results will be src content.

<showdown src="README.md"># Content</showdown>

When both [value] and [src], It will render [value] and when src loads then results will be src content.

<showdown value="# Value" src="README.md"></showdown>

Binding options

Bind options object (it init root ShowdownConfig and then set the bind options)

import { Component } from '@angular/core';
import * as Showdown from 'showdown';

@Component({
  selector: `some`,
  template: `<showdown [value]="text" [options]="options"></showdown>`
})
export class SomeComponent {
  text: string = '# Some';
  options: Showdown.ShowdownOptions = {noHeaderId: true};
  // ...
}

Or

<showdown [options]="{noHeaderId: true}"># abc</showdown>

Bind single option (it have input properties for all showdown options).

<showdown noHeaderId [headerLevelStart]="2" [tables]="options.tables"># abc</showdown>

Sanitize the convert html output

Sanitize the convert html output by DomSanitizer.

<showdown sanitize>
# Some
<a href="javascript:alert('Hello!')">Click</a>
__Foo__
</showdown>

Also sanitize content of src url.

<showdown [value]="# Loading.." src="README.md" sanitize="true"></showdown>

Use ShowdownPipe in the template

Transform markdown value of text property to html.

{{ text | showdown }}

Transform value with options (it init root ShowdownConfig and then set the pipe options)

import { Component } from '@angular/core';
import * as Showdown from 'showdown';

@Component({
  selector: 'some',
  template: '{{ text | showdown:options }}'
})
export class SomeComponent {
  text: string = `
      # h1
      ## h2
  `;
  options: Showdown.ShowdownOptions = {smartIndentationFix: true};
  // ...
}

Use ShowdownConverter service

import { Injectable } from '@angular/core';
import { ShowdownConverter } from 'ngx-showdown';

@Injectable()
export class SomeService {
  constructor(showdownConverter: ShowdownConverter){
    console.log(showdownConverter.makeHtml('# Showdown'));
  }
}

Set config provider (ShowdownConfig)

Set root config that will be injected to ShowdownComponent, ShowdownPipe, ShowdownConverter when they are created.

import { NgModel } from '@angular/core';
import { ShowdownModule, ShowdownConverter } from 'ngx-showdown';
import * as Showdown from 'showdown';

let colorExtension: Showdown.FilterExtension = {
  type: 'output',
  filter(text: string, converter: ShowdownConverter){
    return text.replace('$color', converter.getOption('color') || 'green')
  }
};

@NgModel({
  imports:[
    ShowdownModule.forRoot({
      flavor: 'original',
      emoji: true,
      color: 'red',
      extensions: [ colorExtension ]
    })
  ]
})
export class AppModule {}

Override the root config provider value.

import { Component } from '@angular/core';
import { ShowdownConfig } from 'ngx-showdown';

@Component({
  selector: 'some',
  template: '<showdown># Header</showdown>',
  providers: [ {provide: ShowdownConfig, useValue: {underline: true, emoji: false}} ]
})
export class SomeComponent {}

Set the config manually by the converter methods.

import { Component } from '@angular/core';
import { ShowdownComponent } from 'ngx-showdown';
import highlightExtension from 'showdown-highlight';
import 'highlight.js/styles/default.css';

@Component({
  selector: 'some',
  template: '<showdown># Header</showdown>'
})
export class SomeComponent {
  constructor(showdownComponent: ShowdownComponent) {
    showdownComponent.addExtension(highlightExtension);
    showdownComponent.setFlavor('ghost');
    showdownComponent.setOptions({emoji: true});
  }
}

Flavor

Set root flavor (Showdown flavors).

import { NgModel } from '@angular/core';
import { ShowdownModule } from 'ngx-showdown';

@NgModel({
  imports:[
    ShowdownModule.forRoot({flavor: 'github'})
  ]
})
export class AppModule {}

Note: If flavor is not set then the default value is 'vanilla' flavor.

ConverterOptions

Set root ConverterOptions (Showdown options).

import { NgModel } from '@angular/core';
import { ShowdownModule } from 'ngx-showdown';

@NgModel({
  imports:[
    ShowdownModule.forRoot({underline: true, emoji: false})
  ]
})
export class AppModule {}

Extensions

Set root Extensions (Showdown extensions). With extension can be made changes to the Markdown input ('lang') and the Html output also listen to parse event, you can make extension or search in npm for existing extension.

import { NgModel } from '@angular/core';
import { ShowdownModule } from 'ngx-showdown';
import * as Showdown from 'showdown';
import highlightExtension from 'showdown-highlight';
import 'highlight.js/styles/default.css';

let someExtension: Showdown.ShowdownExtension = {
  type: 'lang',
  regex: new RegExp('markdown', 'g'),
  replace: 'showdown'
};


@NgModel({
  imports: [ 
    ShowdownModule.forRoot({extensions: [ someExtension, highlightExtension ]}) 
  ]
})
export class AppModule {}

Troubleshoot

Interpolation

Using unescaped {} (<showdown>{}</showdown>) in template causes an template parse error (@angular/angular/#11859), The solution is to use escape chars (html char code etc.), Anther solution is to override the default interpolation.

Whitespaces

Angular aot compiler remove whitespaces by default, use ngPreserveWhitespaces to preserve whitespaces.

<showdown ngPreserveWhitespaces>
* a
  * 1
  * 2
* b
</showdown>

With ngPreserveWhitespaces

* a
  * 1
  * 2
* b

Without ngPreserveWhitespaces

* a * 1 * 2
* b

Indentation

Showdown converter smartIndentationFix option can fix string indentation problems of es6 template and html.

text = `
  # A
  ## B
`;

<showdown [value]="text" smartIndentationFix></showdown>

With smartIndentationFix

# A
## B

Without smartIndentationFix

  # A
  ## B

Contribute

Pull requests are welcome!

Development

This project built with Angular Cli.

Install dependencies

$ yarn install

Run test

$ yarn test

Build for release

$ yarn build

Credits

This project use Showdown library to convert Markdown to Html.

License

Copyright © Yisrael Eliav, Licensed under the MIT license.