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

``bash
$ npm install ngx-showdown --save
`
and install peer dependencies (@angular/common/http for SourceDirective)
`bash
$ npm install showdown @angular/common @angular/platform-browser --save
`
and install type package of Showdown for TypeScript
`bash
$ npm install @types/showdown --save-dev
`

Usage

For more information and explanations, see the full documentation.

$3

Add ShowdownModule to imports of App.
`typescript
import { NgModule } from '@angular/core';
import { ShowdownModule } from 'ngx-showdown';

@NgModule({
imports: [ ShowdownModule ]
})
export class AppModule {}
`
Or with config (it will init ShowdownConfig provider)
`typescript
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).
`json
"build": {
"builder": "@angular-devkit/build-angular:browser",
"options": {
"allowedCommonJsDependencies": [
"showdown"
]
...
}
...
},

`


$3


#### Binding to [value] property
Bind markdown value to value property of showdown component.
`html


`

Bind value and options.
`typescript
import { Component } from '@angular/core';
import * as Showdown from 'showdown';

@Component({
selector: 'some',
template: ''
})
export class SomeComponent {
text: string =

h1

h2

;
options: Showdown.ShowdownOptions = {...};
// ...
}
`

As directive on anther element
`html



`

#### Markdown in component content
A markdown value in the component content.
`html



H1

H2

`

With options
`html

* a
* b
* c

`

As directive on anther element
`html
:showdown:howdown
`

#### Load .md content (by SourceDirective)
Load markdown content of url source.
`html

`

Bind input url to src directive.
`html

No Url..
`
Note: Loading markdown content requires HttpClient of @angular/common/http

#### Mixing sources
When both Content and [value], It will render [value].
`html
# Content
`

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

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

`

#### Binding options
Bind options object (it init root ShowdownConfig and then set the bind options)
`typescript
import { Component } from '@angular/core';
import * as Showdown from 'showdown';

@Component({
selector: some,
template:
})
export class SomeComponent {
text: string = '# Some';
options: Showdown.ShowdownOptions = {noHeaderId: true};
// ...
}
`
Or
`html
# abc
`
Bind single option (it have input properties for all showdown options).
`html
# abc
`

#### Sanitize the convert html output
Sanitize the convert html output by DomSanitizer.
`html



Some


Click
__Foo__

`
Also sanitize content of src url.
`html

`

$3

Transform markdown value of text property to html.
`html
{{ text | showdown }}
`

Transform value with options (it init root ShowdownConfig and then set the pipe options)
`typescript
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};
// ...
}
`

$3

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

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

$3


Set root config that will be injected to ShowdownComponent, ShowdownPipe, ShowdownConverter when they are created.
`typescript
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.
`typescript
import { Component } from '@angular/core';
import { ShowdownConfig } from 'ngx-showdown';

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

Set the config manually by the converter methods.
`typescript
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: '# Header'
})
export class SomeComponent {
constructor(showdownComponent: ShowdownComponent) {
showdownComponent.addExtension(highlightExtension);
showdownComponent.setFlavor('ghost');
showdownComponent.setOptions({emoji: true});
}
}
`

#### Flavor
Set root flavor (Showdown flavors).
`typescript
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).
`typescript
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.
`typescript
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 {} ({}) 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.
`html

* a
* 1
* 2
* b

`
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.
`typescript
text =
# A
## B
;
`
`html

`
With smartIndentationFix
`


A

B

`
Without smartIndentationFix
`
# A
## B
`

Contribute

Pull requests are welcome!

Development

This project built with Angular Cli.

Install dependencies
`bash
$ yarn install
`
Run test
`bash
$ yarn test
`
Build for release
`bash
$ yarn build
`

Credits


This project use Showdown library to convert Markdown to Html`.

License

Copyright © Yisrael Eliav,
Licensed under the MIT license.