{"_id":"@amaplex-software/ngx-markdown","_rev":"1-1671e6ae7135bb9702d30191ad925740","name":"@amaplex-software/ngx-markdown","dist-tags":{"latest":"9.1.1"},"versions":{"9.1.1":{"name":"@amaplex-software/ngx-markdown","version":"9.1.1","description":"Angular library that uses marked to parse markdown to html combined with Prism.js for synthax highlights","homepage":"https://github.com/jfcere/ngx-markdown","license":"MIT","author":{"name":"Jean-Francois Cere","email":"jfcere@sherweb.com"},"repository":{"type":"git","url":"git+https://github.com/jfcere/ngx-markdown.git"},"keywords":["angular","ngx","markdown","parser","marked","marked.js","prism","prism.js","katex","emoji"],"dependencies":{"@types/marked":"^0.7.4","emoji-toolkit":"^5.5.0","katex":"^0.11.0","marked":"^1.1.0","prismjs":"^1.20.0","tslib":"^1.10.0"},"peerDependencies":{"@angular/common":"^8.0.0 || ^9.0.0","@angular/core":"^8.0.0 || ^9.0.0","@angular/platform-browser":"^8.0.0 || ^9.0.0","rxjs":"^6.0.0","zone.js":"^0.9.0 || ^0.10.0"},"main":"bundles/ngx-markdown.umd.js","module":"fesm5/ngx-markdown.js","es2015":"fesm2015/ngx-markdown.js","esm5":"esm5/ngx-markdown.js","esm2015":"esm2015/ngx-markdown.js","fesm5":"fesm5/ngx-markdown.js","fesm2015":"fesm2015/ngx-markdown.js","typings":"ngx-markdown.d.ts","metadata":"ngx-markdown.metadata.json","sideEffects":false,"bugs":{"url":"https://github.com/jfcere/ngx-markdown/issues"},"_id":"@amaplex-software/ngx-markdown@9.1.1","_nodeVersion":"14.17.1","_npmVersion":"6.14.12","dist":{"integrity":"sha512-9HUyFtcKs5rAkfsi7joaMHBzfu/A9PotKfunKBtFpVScE4qOwkXc/a8EiCcOz6+sYmH5D1fWw1rkHCntiym4aw==","shasum":"f025aa1c7a913dc92e98a5474b17a675166939f1","tarball":"https://registry.npmjs.org/@amaplex-software/ngx-markdown/-/ngx-markdown-9.1.1.tgz","fileCount":48,"unpackedSize":397320,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDu9SH9YBfR15dEBifb6i0sKRe7JTxsxOkQyvvPinxSbgIhAJW8dUFUa9LDV0jfjoeZR6nZoDhMaMWTF4v+AVV2uwYW"}]},"_npmUser":{"name":"adrien-fery","email":"contact@adrien-fery.com"},"directories":{},"maintainers":[{"name":"adrien-fery","email":"contact@adrien-fery.com"},{"name":"grumpy-cat","email":"thomas.vasbinder@amanote.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/ngx-markdown_9.1.1_1701711265236_0.4431864273272281"},"_hasShrinkwrap":false}},"time":{"created":"2023-12-04T17:34:25.132Z","9.1.1":"2023-12-04T17:34:25.414Z","modified":"2024-05-14T20:02:31.784Z"},"maintainers":[{"email":"contact@adrien-fery.com","name":"adrien-fery"}],"description":"Angular library that uses marked to parse markdown to html combined with Prism.js for synthax highlights","homepage":"https://github.com/jfcere/ngx-markdown","keywords":["angular","ngx","markdown","parser","marked","marked.js","prism","prism.js","katex","emoji"],"repository":{"type":"git","url":"git+https://github.com/jfcere/ngx-markdown.git"},"author":{"name":"Jean-Francois Cere","email":"jfcere@sherweb.com"},"bugs":{"url":"https://github.com/jfcere/ngx-markdown/issues"},"license":"MIT","readme":"<p align=\"center\">\n  <img alt=\"Ngx-Markdown Logo\" src=\"https://github.com/jfcere/ngx-markdown/raw/master/demo/src/assets/ngx-markdown.png\">\n</p>\n<p align=\"center\">\n  <a href=\"https://circleci.com/gh/jfcere/ngx-markdown\">\n    <img alt=\"CircleCI Status\" src=\"https://circleci.com/gh/jfcere/ngx-markdown/tree/master.svg?style=shield\">\n  </a>\n  <a href=\"https://coveralls.io/github/jfcere/ngx-markdown?branch=master\">\n    <img alt=\"Coverage Status\" src=\"https://coveralls.io/repos/github/jfcere/ngx-markdown/badge.svg?branch=master\">\n  </a>\n  <a href=\"https://www.npmjs.com/package/ngx-markdown\">\n    <img alt=\"NPM Version\" src=\"https://img.shields.io/npm/v/ngx-markdown.svg?style=flat\">\n  </a>\n  <a href=\"https://opensource.org/licenses/MIT\">\n    <img alt=\"License\" src=\"https://img.shields.io/npm/l/ngx-markdown.svg\">\n  </a>\n    <a href=\"https://www.npmjs.com/package/ngx-markdown\">\n    <img alt=\"Monthly Downloads\" src=\"https://img.shields.io/npm/dm/ngx-markdown.svg\">\n  </a>\n  <br>\n  <a href=\"https://david-dm.org/jfcere/ngx-markdown?path=lib\">\n    <img alt=\"Dependencies Status\" src=\"https://david-dm.org/jfcere/ngx-markdown/status.svg?path=lib\">\n  </a>\n  <a href=\"https://david-dm.org/jfcere/ngx-markdown?path=lib&type=peer\">\n    <img alt=\"PeerDependencies Status\" src=\"https://david-dm.org/jfcere/ngx-markdown/peer-status.svg?path=lib\">\n  </a>\n</p>\n\n# ngx-markdown\n\nngx-markdown is an [Angular](https://angular.io/) library that combines...\n- [Marked](http://marked.js.org/) to parse markdown to HTML\n- [Prism.js](http://prismjs.com/) for language syntax highlight\n- [Emoji-Toolkit](https://github.com/joypixels/emoji-toolkit) for emoji support\n- [KaTeX](https://katex.org/) for math expression rendering\n\nDemo available @ [https://jfcere.github.io/ngx-markdown](https://jfcere.github.io/ngx-markdown)  \nStackBlitz available @ [https://stackblitz.com/edit/ngx-markdown](https://stackblitz.com/edit/ngx-markdown)\n\n### Table of contents\n\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Renderer](#renderer)\n- [Syntax highlight](#syntax-highlight)\n- [Demo application](#demo-application)\n- [AoT compilation](#aot-compilation)\n- [Road map](#road-map)\n- [Contribution](#contribution)\n- [Support Development](#support-development)\n\n## Installation\n\n### ngx-markdown\n\nTo add ngx-markdown library to your `package.json` use the following command.\n\n```bash\nnpm install ngx-markdown --save\n```\n\nAs the library is using [Marked](https://github.com/chjj/marked) parser you will need to add `node_modules/marked/lib/marked.js` to your application.\n\nIf you are using [Angular CLI](https://cli.angular.io/) you can follow the `angular.json` example below...\n\n```diff\n\"scripts\": [\n+ \"node_modules/marked/lib/marked.js\"\n]\n```\n\n### Syntax highlight\n\n> :bell: Syntax highlight is **optional**, skip this step if you are not planning to use it\n\nTo activate [Prism.js](http://prismjs.com/) syntax highlight you will need to include...\n- prism.js core library - `node_modules/prismjs/prism.js` file\n- a highlight css theme - from `node_modules/prismjs/themes` directory\n- desired code language syntax files - from `node_modules/prismjs/components` directory\n\n_Additional themes can be found by browsing the web such as [Prism-Themes](https://github.com/PrismJS/prism-themes) or [Mokokai](https://github.com/Ahrengot/Monokai-theme-for-Prism.js) for example._\n\nIf you are using [Angular CLI](https://cli.angular.io/) you can follow the `angular.json` example below...\n\n```diff\n\"styles\": [\n  \"styles.css\",\n+ \"node_modules/prismjs/themes/prism-okaidia.css\"\n],\n\"scripts\": [\n+ \"node_modules/prismjs/prism.js\",\n+ \"node_modules/prismjs/components/prism-csharp.min.js\", # c-sharp language syntax\n+ \"node_modules/prismjs/components/prism-css.min.js\" # css language syntax\n]\n```\n\n#### Line Numbers plugin\n\nTo use the [line numbers plugin](http://prismjs.com/plugins/line-numbers/) 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:\n\n- CSS styling for line numbers - `prism-line-numbers.css`\n- line numbers plugin script - `prism-line-numbers.js`\n\nIf you are using [Angular CLI](https://cli.angular.io/) you can follow the `angular.json` example below...\n\n```diff\n\"styles\": [\n  \"src/styles.css\",\n  \"node_modules/prismjs/themes/prism-okaidia.css\",\n+ \"node_modules/prismjs/plugins/line-numbers/prism-line-numbers.css\"\n],\n\"scripts\": [\n  \"node_modules/prismjs/prism.js\",\n  \"node_modules/prismjs/components/prism-csharp.min.js\",\n  \"node_modules/prismjs/components/prism-css.min.js\",\n+ \"node_modules/prismjs/plugins/line-numbers/prism-line-numbers.js\"\n]\n```\n\nUsing `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.\n\nAdditionally, you can use `start` input property to specify the offset number for the first display line.\n\n```html\n<markdown [src]=\"path/to/file.js\" lineNumbers [start]=\"5\"></markdown>\n```\n\n#### Line Highlight plugin\n\nTo use the [line highlight plugin](http://prismjs.com/plugins/line-highlight/) 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:\n\n- CSS styling for line highlight - `prism-line-highlight.css`\n- line highlight plugin script - `prism-line-highlight.js`\n\nIf you are using [Angular CLI](https://cli.angular.io/) you can follow the `angular.json` example below...\n\n```diff\n\"styles\": [\n  \"src/styles.css\",\n  \"node_modules/prismjs/themes/prism-okaidia.css\",\n+ \"node_modules/prismjs/plugins/line-highlight/prism-line-highlight.css\"\n],\n\"scripts\": [\n  \"node_modules/prismjs/prism.js\",\n  \"node_modules/prismjs/components/prism-csharp.min.js\",\n  \"node_modules/prismjs/components/prism-css.min.js\",\n+ \"node_modules/prismjs/plugins/line-highlight/prism-line-highlight.js\"\n]\n```\n\nUsing `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.\n\nUse `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.\n\n```html\n<markdown [src]=\"path/to/file.js\" lineHighlight [line]=\"'6, 10-16'\" [lineOffset]=\"5\"></markdown>\n```\n\n### Emoji support\n\n> :bell: Emoji support is **optional**, skip this step if you are not planning to use it\n\nTo activate [Emoji-Toolkit](https://github.com/joypixels/emoji-toolkit) for emoji suppport you will need to include...\n- Emoji-Toolkit library - `node_modules/emoji-toolkit/lib/js/joypixels.min.js`\n\nIf you are using [Angular CLI](https://cli.angular.io/) you can follow the `angular.json` example below...\n\n```diff\n\"scripts\": [\n  \"node_modules/marked/lib/marked.js\",\n+ \"node_modules/emoji-toolkit/lib/js/joypixels.min.js\",\n]\n```\n\n#### Emoji plugin\n\nUsing `markdown` component and/or directive, you will be able to use the `emoji` property to activate [Emoji-Toolkit](https://github.com/joypixels/emoji-toolkit) plugin that converts emoji shortnames such as `:heart:` to native unicode emojis.\n\n```html\n<markdown emoji>I :heart: ngx-markdown</markdown>\n```\n\n> :blue_book: You can refer to this [Emoji Cheat Sheet](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md) for a complete list of _shortnames_.\n\n### Math rendering\n\n> :bell: Math rendering is **optional**, skip this step if you are not planning to use it\n\nTo activate [KaTeX](https://katex.org/) math rendering you will need to include...\n- KaTex JavaScript library - `node_modules/katex/dist/katex.min.js` file\n- KaTex CSS customization - `node_modules/katex/dist/katex.min.css` file\n\nIf you are using [Angular CLI](https://cli.angular.io/) you can follow the `angular.json` example below...\n\n```diff\n\"styles\": [\n  \"styles.css\",\n+ \"node_modules/katex/dist/katex.min.css\"\n],\n\"scripts\": [\n  \"node_modules/marked/lib/marked.js\",\n+ \"node_modules/katex/dist/katex.min.js\",\n]\n```\n\n#### KaTeX plugin\n\nUsing `markdown` component and/or directive, you will be able to use the `katex` property to activate [KaTeX](https://katex.org/) plugin that render mathematical expression to HTML.\n\n```html\n<markdown [src]=\"path/to/file.md\" katex></markdown>\n```\n\nOptionally, you can use `katexOptions` property to specify [KaTeX options](https://katex.org/docs/options.html).\n\n```typescript\nimport { KatexOptions } from 'ngx-markdown';\n\npublic options: KatexOptions = {\n  displayMode: true,\n  throwOnError: false,\n  errorColor: '#cc0000',\n  ...\n};\n```\n\n```html\n<markdown [src]=\"path/to/file.md\" katex [katexOptions]=\"options\"></markdown>\n```\n\n> :blue_book: Follow official [KaTeX options](https://katex.org/docs/options.html) documentation for more details on the available options.\n\n## Configuration\n\n### Main application module\n\nYou must import `MarkdownModule` inside your main application module (usually named AppModule) with `forRoot` to be able to use `markdown` component and/or directive.\n\n```diff\nimport { NgModule } from '@angular/core';\n+ import { MarkdownModule } from 'ngx-markdown';\n\nimport { AppComponent } from './app.component';\n\n@NgModule({\n  imports: [\n+   MarkdownModule.forRoot(),\n  ],\n  declarations: [AppComponent],\n  bootstrap: [AppComponent],\n})\nexport class AppModule { }\n```\n\nIf you want to use the `[src]` attribute to directly load a remote file, in order to keep only one instance of `HttpClient` and avoid issues with interceptors, you also have to provide `HttpClient`:\n\n```diff\nimports: [\n+  HttpClientModule,\n+  MarkdownModule.forRoot({ loader: HttpClient }),\n],\n```\n\n#### Sanitization\n\nAs of ngx-markdown v9.0.0 **sanitization is enabled by default** and uses Angular `DomSanitizer` with `SecurityContext.HTML` to avoid XSS vulnerabilities. The `SecurityContext` level can be changed using the `sanitize` property when configuring `MarkdownModule`.\n\n```typescript\nimport { SecurityContext } from '@angular/core';\n\n// enable default sanitization\nMarkdownModule.forRoot()\n\n// turn off sanitization\nMarkdownModule.forRoot({\n  sanitize: SecurityContext.NONE\n})\n```\n\n> :blue_book: Follow [Angular DomSanitizer](https://angular.io/api/platform-browser/DomSanitizer#sanitize) documentation for more information on sanitization and security contexts.\n\n#### MarkedOptions\n\nOptionally, markdown parsing can be configured by passing [MarkedOptions](https://marked.js.org/#/USING_ADVANCED.md#options) to the `forRoot` method of `MarkdownModule`.\n\nImports:\n```typescript\nimport { MarkdownModule, MarkedOptions } from 'ngx-markdown';\n```\n\nDefault options:\n```typescript\n// using default options\nMarkdownModule.forRoot(),\n```\n\nCustom options and passing `HttpClient` to use `[src]` attribute:\n```typescript\n// using specific options with ValueProvider and passing HttpClient\nMarkdownModule.forRoot({\n  loader: HttpClient, // optional, only if you use [src] attribute\n  markedOptions: {\n    provide: MarkedOptions,\n    useValue: {\n      gfm: true,\n      breaks: false,\n      pedantic: false,\n      smartLists: true,\n      smartypants: false,\n    },\n  },\n}),\n```\n\n#### MarkedOptions.renderer\n\n`MarkedOptions` also exposes the `renderer` property which allows you to override token rendering for your whole application.\n\nThe example below overrides the default blockquote token rendering by adding a CSS class for custom styling when using Bootstrap CSS:\n\n```typescript\nimport { MarkedOptions, MarkedRenderer } from 'ngx-markdown';\n\n// function that returns `MarkedOptions` with renderer override\nexport function markedOptionsFactory(): MarkedOptions {\n  const renderer = new MarkedRenderer();\n\n  renderer.blockquote = (text: string) => {\n    return '<blockquote class=\"blockquote\"><p>' + text + '</p></blockquote>';\n  };\n\n  return {\n    renderer: renderer,\n    gfm: true,\n    breaks: false,\n    pedantic: false,\n    smartLists: true,\n    smartypants: false,\n  };\n}\n\n// using specific option with FactoryProvider\nMarkdownModule.forRoot({\n  loader: HttpClient,\n  markedOptions: {\n    provide: MarkedOptions,\n    useFactory: markedOptionsFactory,\n  },\n}),\n```\n\n### Other application modules\n\nUse `forChild` when importing `MarkdownModule` into other application modules to allow you to use the same parser configuration across your application.\n\n```diff\nimport { NgModule } from '@angular/core';\n+ import { MarkdownModule } from 'ngx-markdown';\n\nimport { HomeComponent } from './home.component';\n\n@NgModule({\n  imports: [\n+   MarkdownModule.forChild(),\n  ],\n  declarations: [HomeComponent],\n})\nexport class HomeModule { }\n```\n\n## Usage\n\n`ngx-markdown` provides different approaches to help you parse markdown to your application depending on your needs.\n\n> :bulb: As of Angular 6, the template compiler strips whitespace by default. Use `ngPreserveWhitespaces` directive to preserve whitespaces such as newlines in order for the markdown-formatted content to render as intended.  \nhttps://angular.io/api/core/Component#preserveWhitespaces\n\n### Component\n\nYou 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. You can get a hook on load complete using `load` output event property, on loading error using `error` output event property or when parsing is completed using `ready` output event property.\n\n```html\n<!-- static markdown -->\n<markdown ngPreserveWhitespaces>\n  # Markdown\n</markdown>\n\n<!-- loaded from remote url -->\n<markdown [src]=\"'path/to/file.md'\" (load)=\"onLoad($event)\" (error)=\"onError($event)\"></markdown>\n\n<!-- variable binding -->\n<markdown [data]=\"markdown\" (ready)=\"onReady()\"></markdown>\n```\n\n### Directive\n\nThe same way the component works, you can use `markdown` directive to accomplish the same thing.\n\n```html\n<!-- static markdown -->\n<div markdown ngPreserveWhitespaces>\n  # Markdown\n</div>\n\n<!-- loaded from remote url -->\n<div markdown [src]=\"'path/to/file.md'\" (load)=\"onLoad($event)\" (error)=\"onError($event)\"></div>\n\n<!-- variable binding -->\n<div markdown [data]=\"markdown\" (ready)=\"onReady()\"></div>\n```\n\n### Pipe\n\nUsing `markdown` pipe to transform markdown to HTML allow you to chain pipe transformations and will update the DOM when value changes.\n\n```html\n<!-- chain `language` pipe with `markdown` pipe to convert typescriptMarkdown variable content -->\n<div [innerHTML]=\"typescriptMarkdown | language : 'typescript' | markdown\"></div>\n```\n\n### Service\n\nYou can use `MarkdownService` to have access to markdown parser and syntax highlight methods.\n\n```typescript\nimport { Component, OnInit } from '@angular/core';\nimport { MarkdownService } from 'ngx-markdown';\n\n@Component({ ... })\nexport class ExampleComponent implements OnInit() {\n  constructor(private markdownService: MarkdownService) { }\n\n  ngOnInit() {\n    // outputs: <p>I am using <strong>markdown</strong>.</p>\n    console.log(this.markdownService.compile('I am using __markdown__.'));\n  }\n}\n```\n\n## Renderer\n\nTokens can be rendered in a custom manner by either...\n- providing the `renderer` property with the `MarkedOptions` when importing `MarkdownModule.forRoot()` into your main application module (see [Configuration](#markedoptionsrenderer) section)\n- using `MarkdownService` exposed `renderer`\n\nHere is an example of overriding the default heading token rendering through `MarkdownService` by adding an embedded anchor tag like on GitHub:\n\n```typescript\nimport { Component, OnInit } from '@angular/core';\nimport { MarkdownService } from 'ngx-markdown';\n\n@Component({\n  selector: 'app-example',\n  template: '<markdown># Heading</markdown>',\n})\nexport class ExampleComponent implements OnInit() {\n  constructor(private markdownService: MarkdownService) { }\n\n  ngOnInit() {\n    this.markdownService.renderer.heading = (text: string, level: number) => {\n      const escapedText = text.toLowerCase().replace(/[^\\w]+/g, '-');\n      return '<h' + level + '>' +\n               '<a name=\"' + escapedText + '\" class=\"anchor\" href=\"#' + escapedText + '\">' +\n                 '<span class=\"header-link\"></span>' +\n               '</a>' + text +\n             '</h' + level + '>';\n    };\n  }\n}\n```\n\nThis code will output the following HTML:\n\n```html\n<h1>\n  <a name=\"heading\" class=\"anchor\" href=\"#heading\">\n    <span class=\"header-link\"></span>\n  </a>\n  Heading\n</h1>\n```\n\n> :blue_book: Follow official [marked.renderer](https://marked.js.org/#/USING_PRO.md#renderer) documentation for the list of tokens that can be overriden.\n\n## Syntax highlight\n\nWhen using static markdown you are responsible to provide the code block with related language.\n\n```diff\n<markdown ngPreserveWhitespaces>\n+  ```typescript\n    const myProp: string = 'value';\n+  ```\n</markdown>\n```\n\nWhen using remote URL ngx-markdown will use the file extension to automatically resolve the code language.\n\n```html\n<!-- will use html highlights -->\n<markdown [src]=\"'path/to/file.html'\"></markdown>\n\n<!-- will use php highlights -->\n<markdown [src]=\"'path/to/file.php'\"></markdown>\n```\n\nWhen 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).\n\n```html\n<markdown [data]=\"markdown | language : 'typescript'\"></markdown>\n```\n\n## Demo application\n\nA demo is available @ [https://jfcere.github.io/ngx-markdown](https://jfcere.github.io/ngx-markdown) and its source code can be found inside the `demo` directory.\n\nThe following commands will clone the repository, install npm dependencies and serve the application @ [http://localhost:4200](http://localhost:4200)\n\n```bash\ngit clone https://github.com/jfcere/ngx-markdown.git\nnpm install\nnpm start\n```\n\n## AoT compilation\n\nBuilding with AoT is part of the CI and is tested every time a commit occurs so you don't have to worry at all.\n\n## Road map\n\nHere is the list of tasks that will be done on this library in the near future ...\n\n- Add copy-to-clipboard feature\n- Add a FAQ section to the README.md\n\n## Contribution\n\nContributions are always welcome, just make sure that ...\n\n- Your code style matches with the rest of the project\n- Unit tests pass\n- Linter passes\n\n## Support Development\n\nThe use of this library is totally free and no donation is required.\n\nAs the owner and primary maintainer of this project, I am putting a lot of time and effort beside my job, my family and my private time to bring the best support I can by answering questions, addressing issues and improving the library to provide more and more features over time.\n\nIf this project has been useful, that it helped you or your business to save precious time, don't hesitate to give it a star and to consider a donation to support its maintenance and future development.\n\n## License\n\nLicensed under [MIT](https://opensource.org/licenses/MIT).\n","readmeFilename":"README.md"}