Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/murhafsousli/ngx-highlightjs
Angular syntax highlighting module
https://github.com/murhafsousli/ngx-highlightjs
angular code gist highlightjs linenumbers prism syntax-highlighting
Last synced: 2 months ago
JSON representation
Angular syntax highlighting module
- Host: GitHub
- URL: https://github.com/murhafsousli/ngx-highlightjs
- Owner: MurhafSousli
- License: mit
- Created: 2017-07-25T01:43:45.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-04-01T05:40:45.000Z (3 months ago)
- Last Synced: 2024-04-25T15:02:00.435Z (2 months ago)
- Topics: angular, code, gist, highlightjs, linenumbers, prism, syntax-highlighting
- Language: TypeScript
- Homepage: https://ngx-highlight.netlify.com/
- Size: 3.86 MB
- Stars: 271
- Watchers: 3
- Forks: 34
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Lists
- angular-favorites - ngx-highlightjs
README
Angular Highlight.js
[](https://ngx-highlight.netlify.com/)
[](https://stackblitz.com/edit/ngx-highlightjs)
[](https://www.npmjs.com/package/ngx-highlightjs)
[](https://github.com/MurhafSousli/ngx-highlightjs/actions?query=workflow%3Atests)
[](https://www.npmjs.com/package/ngx-highlightjs)
[](https://www.npmjs.com/package/ngx-highlightjs)
[](https://bundlephobia.com/result?p=ngx-highlightjs)
[](/LICENSE)
Instant code highlighting, auto-detect language, super easy to use
___
## Table of Contents
- [Live Demo](https://ngx-highlight.netlify.com/) | [Stackblitz](https://stackblitz.com/edit/ngx-highlightjs)
- [Installation](#installation)
- [Usage](#usage)
- [Development](#development)
- [Issues](#issues)
- [Author](#author)
- [More plugins](#more-plugins)
## Installation
Install with **NPM**
```bash
npm i ngx-highlightjs
```
## Usage
### Provide the config for `HIGHLIGHT_OPTIONS` in `main.ts` file
```typescript
import { HIGHLIGHT_OPTIONS } from 'ngx-highlightjs';
bootstrapApplication(AppComponent, {
providers: [
{
provide: HIGHLIGHT_OPTIONS,
useValue: {
fullLibraryLoader: () => import('highlight.js')
}
}
]
})
```
> 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
```typescript
import { HIGHLIGHT_OPTIONS } from 'ngx-highlightjs';
bootstrapApplication(AppComponent, {
providers: [
{
provide: HIGHLIGHT_OPTIONS,
useValue: {
coreLibraryLoader: () => import('highlight.js/lib/core'),
lineNumbersLoader: () => import('ngx-highlightjs/line-numbers'), // 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')
},
themePath: 'path-to-theme.css' // Optional, and useful if you want to change the theme dynamically
}
}
]
})
```
### 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](http://highlightjs.readthedocs.io/en/latest/api.html#configure-option) |
| themePath | The path to highlighting theme CSS file |
> **NOTE:** Since the update of [email protected], should
> use `coreLibraryLoader: () => import('highlight.js/lib/core')` instead
> of `coreLibraryLoader: () => import('highlight.js/lib/highlight')`
### Import highlighting theme
**In version >=6.1.0**, A new way is available to load the theme dynamically! this is **OPTIONAL**, you can still use
the traditional way.
**Dynamic way**
Set the theme path in the global config, this makes it possible to change the theme on the fly, which is useful if you
have light and dark theme in your app.
```ts
providers: [
{
provide: HIGHLIGHT_OPTIONS,
useValue: {
// ...
themePath: 'assets/styles/solarized-dark.css'
}
}
]
```
If you want to import it from the app dist folder, then copy the themes you want to your `assets` directory, or you can
just use a CDN link to the theme.
When switching between the app themes you need to call the `setTheme(path)` from the `HighlightLoader` service.
```ts
import { HighlightLoader } from 'ngx-highlightjs';
export class AppComponent {
constructor(private hljsLoader: HighlightLoader) {
}
// Assume you have a callback function when your app theme is changed
onAppThemeChange(appTheme: 'dark' | 'light') {
this.hljsLoader.setTheme(appTheme === 'dark' ? 'assets/styles/solarized-dark.css' : 'assets/styles/solarized-light.css');
}
}
```
> You can still use the traditional way
**Traditional way**
To import highlight.js theme from the node_modules directory in `angular.json`
```
"styles": [
"styles.css",
"../node_modules/highlight.js/styles/github.css",
]
```
Or directly in `src/style.scss`
```css
@import '~highlight.js/styles/github.css';
```
_[List of all available themes from highlight.js](https://github.com/isagalaev/highlight.js/tree/master/src/styles)_
### Use highlight directive
The following line will highlight the given code and append it to the host element
```ts
import { HighlightModule } from 'ngx-highlightjs';
@Component({
selector: 'app-root',
template: `
`,
standalone: true,
imports: [
HighlightModule
]
})
export class AppComponent {
}
```
[Demo stackblitz](https://stackblitz.com/edit/ngx-highlightjs)
## 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)** | HighlightAutoResult | 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`
```json
{
"projects": {
"project-name": {
"architect": {
"build": {
"options": {
"allowedCommonJsDependencies": [
"highlight.js"
]
}
}
}
}
}
}
```
Read more about [CommonJS dependencies configuration](https://angular.io/guide/build#configuring-commonjs-dependencies)
## Plus package
This package contains the following features:
- Highlight gists using gists API
- Highlight code directly from URL
### Usage
The plus package relies on `HttpClient` to make the http requests, ensure that it is imported in your `main.ts` file
```ts
import { provideHttpClient } from '@angular/common/http';
bootstrapApplication(AppComponent, {
providers: [
provideHttpClient(),
{
provide: HIGHLIGHT_OPTIONS,
useValue: // ...
}
]
})
```
### Highlight a gist file
1. Use `[gist]` directive with the gist id to get the response through the output `(gistLoaded)`.
2. Once `(gistLoaded)` emits, you will get access to the gist response.
3. Use `gistContent` pipe to extract the file content from gist response using gist file name.
**Example:**
```ts
import { HighlightPlusModule } from 'ngx-highlightjs';
@Component({
selector: 'app-root',
template: `
`,
standalone: true,
imports: [HighlightPlusModule]
})
export class AppComponent {
}
```
### Highlight all gist files
To loop over `gist?.files`, use `keyvalue` pipe to pass file name into `gistContent` pipe.
**Example:**
```ts
import { HighlightPlusModule } from 'ngx-highlightjs';
@Component({
selector: 'app-root',
template: `
`,
standalone: true,
imports: [HighlightPlusModule, CommonModule]
})
export class AppComponent {
}
```
### Highlight code from URL directly
Use the pipe `codeFromUrl` with the `async` pipe together to get the code text from a raw URL.
**Example:**
```ts
import { HighlightPlusModule } from 'ngx-highlightjs';
@Component({
selector: 'app-root',
template: `
`,
standalone: true,
imports: [HighlightPlusModule, CommonModule]
})
export class AppComponent {
}
```
### Providing Gist API secret (Optional)
To take full advantage of the gist loader feature, the package provides `GIST_OPTIONS` token to set your `clientId`
and `clientSecret` with the gist http requests, you can provide it in `main.ts` like in this example:
```typescript
import { GIST_OPTIONS } from 'ngx-highlightjs/plus'
bootstrapApplication(AppComponent, {
providers: [
provideHttpClient(),
{
provide: HIGHLIGHT_OPTIONS,
useValue: // ...
},
{
provide: GIST_OPTIONS,
useValue: {
clientId: 'CLIENT_ID',
clientSecret: 'CLIENT_SECRET'
}
},
]
})
```
## Development
This project uses Angular CLI to build the package.
```bash
$ ng build ngx-highlightjs
```
## Issues
If you identify any errors in the library, or have an idea for an improvement, please open
an [issue](https://github.com/MurhafSousli/ngx-highlightjs/issues).
## Author
**Murhaf Sousli**
- [github/murhafsousli](https://github.com/MurhafSousli)
- [twitter/murhafsousli](https://twitter.com/MurhafSousli)
## More plugins
- [ngx-scrollbar](https://github.com/MurhafSousli/ngx-scrollbar)
- [ngx-sharebuttons](https://github.com/MurhafSousli/ngx-sharebuttons)
- [ngx-gallery](https://github.com/MurhafSousli/ngx-gallery)
- [ngx-progressbar](https://github.com/MurhafSousli/ngx-progressbar)
- [ngx-bar-rating](https://github.com/MurhafSousli/ngx-bar-rating)
- [ngx-disqus](https://github.com/MurhafSousli/ngx-disqus)
- [ngx-wordpress](https://github.com/MurhafSousli/ngx-wordpress)
- [ngx-teximate](https://github.com/MurhafSousli/ngx-teximate)