@kensingtontech/ngx-highlightjs
v11.4.0
Published
Instant code highlighting, auto-detect language
Downloads
15
Maintainers
Readme
Angular Highlight.js
Instant code highlighting, auto-detect language.
Differences from the original
- Uses [email protected].
- Built with and requires Angular@^13.0.0.
- Supports ESM module imports.
- Renamed some files for more intuitive usage.
- Removed HighlightLibrary interface in favour of highlight.js' own Typescript definition
- All other changes associated with Highlight.js 11.
Table of Contents
Installation
Install with NPM
npm i @kensingtontech/ngx-highlightjs
Usage
Import HighlightModule
in your app
Top Tip:: Do this in app.module, not in a lazy-loaded module
import { HighlightModule, HIGHLIGHT_OPTIONS } from 'ngx-highlightjs';
@NgModule({
imports: [
HighlightModule
],
providers: [
{
provide: HIGHLIGHT_OPTIONS,
useValue: {
fullLibraryLoader: () => import('highlight.js'),
}
}
],
})
export class AppModule { }
Note: This will add highlight.js library including all languages to your bundle.
To avoid import everything from highlight.js library, you should import each language you want to highlight manually.
Import only the core library and the needed highlighting languages
import { HighlightModule, HIGHLIGHT_OPTIONS } from 'ngx-highlightjs';
@NgModule({
imports: [
HighlightModule
],
providers: [
{
provide: HIGHLIGHT_OPTIONS,
useValue: {
coreLibraryLoader: () => import('highlight.js/lib/core'),
lineNumbersLoader: () => import('highlightjs-line-numbers.js'), // Optional, only if you want the line numbers
languages: {
typescript: () => import('highlight.js/lib/languages/typescript'),
css: () => import('highlight.js/lib/languages/css'),
xml: () => import('highlight.js/lib/languages/xml')
}
}
}
],
})
export class AppModule { }
HighlightOptions API
| Name | Description |
|-------------------|-------------------------------------------------------------------------------------------------------------------------|
| fullLibraryLoader | A function that returns a promise that loads highlight.js
full script |
| coreLibraryLoader | A function that returns a promise that loads highlight.js
core script |
| lineNumbersLoader | A function that returns a promise that loads line-numbers
script which adds line numbers to the highlight code |
| languages | The set of languages to register. |
| config | Set highlight.js config, see configure-options |
NOTE: Since the update of [email protected], should use
coreLibraryLoader: () => import('highlight.js/lib/core')
instead ofcoreLibraryLoader: () => import('highlight.js/lib/highlight')
Import highlighting theme
Import highlight.js theme from the node_modules directory in angular.json
"styles": [
"styles.css",
"../node_modules/highlight.js/styles/github.css",
]
Or import it in src/style.scss
@import '~highlight.js/styles/github.css';
List of all available themes from highlight.js
Use highlight directive
The following line will highlight the given code and append it to the host element
<pre><code [highlight]="code"></code></pre>
Options
| Name | Type | Description |
|-------------------|-----------------|------------------------------------------------------------------------------------------------------------|
| [highlight] | string | Accept code string to highlight, default null
|
| [languages] | string[] | An array of language names and aliases restricting auto detection to only these languages, default: null
|
| [lineNumbers] | boolean | A flag that indicates adding line numbers to highlighted code element |
| (highlighted) | HighlightResult | Stream that emits the result object when element is highlighted |
NOTE
In Angular 10, when building your project, you might get a warning WARNING in ... CommonJS or AMD dependencies can cause optimization bailouts.
To avoid this warning, add the following in your angular.json
{
"projects": {
"project-name": {
"architect": {
"build": {
"options": {
"allowedCommonJsDependencies": [
"highlight.js"
]
}
}
}
}
}
}
Read more about CommonJS dependencies configuration
Plus package
In version >= 4, a new sub-package were added with the following features:
- Highlight gists using gists API
- Highlight code directly from URL
Usage
import { HighlightPlusModule } from 'ngx-highlightjs/plus';
@NgModule({
imports: [
HighlightPlusModule
]
})
export class AppModule {
}
Highlight a gist file
- Use
[gist]
directive with the gist id to get the response through the output(gistLoaded)
. - Once
(gistLoaded)
emits, you will get access to the gist response. - Use
gistContent
pipe to extract the file content from gist response using gist file name.
Example:
<pre [gist]="gistId" (gistLoaded)="gist = $event">
<code [highlight]="gist | gistContent: 'main.js'"></code>
</pre>
Highlight all gist files
To loop over gist?.files
, use keyvalue
pipe to pass file name into gistContent
pipe.
Example:
<ng-container [gist]="gistId" (gistLoaded)="gist = $event">
<pre *ngFor="let file of gist?.files | keyvalue">
<code [highlight]="gist | gistContent: file.key"></code>
</pre>
</ng-container>
Highlight code from URL directly
Use the pipe codeFromUrl
with the async
pipe together to get the code text from a raw URL.
Example:
<pre>
<code [highlight]="codeUrl | codeFromUrl | async"></code>
</pre>
Development
This project uses Angular CLI to build the package.
$ ng build ngx-highlightjs
Issues
Sorry, I'm not actively supporting this module. It's for my own use and am sharing it with those who might find it useful.
Author
Tim Underhay
Original Author
Murhaf Sousli