Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release/10.0.0 #261

Merged
merged 11 commits into from
Jun 25, 2023
Merged

Release/10.0.0 #261

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
447b0c2
Update dependencies
MurhafSousli Jun 25, 2023
d5ccd86
Update README
MurhafSousli Jun 25, 2023
7f8f551
fix: Add line-numbers as a sub package, closes #234
MurhafSousli Jun 25, 2023
5d2ccb9
refactor: Update deprecated rxjs usage
MurhafSousli Jun 25, 2023
3a47071
chore: bumps up version
MurhafSousli Jun 25, 2023
cadcd11
feat: Migrate to standalone components, closes #260
MurhafSousli Jun 25, 2023
2bcdbaf
Update README
MurhafSousli Jun 25, 2023
aa39154
Make test happy again!
MurhafSousli Jun 25, 2023
fa14c30
Update changelog
MurhafSousli Jun 25, 2023
891b654
Update universal for demo
MurhafSousli Jun 25, 2023
a5a3635
Make test happy again!
MurhafSousli Jun 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# Changelog

## 10.0.0

- feat: Migrate to Angular standalone components, closes [#260](https://github.com/MurhafSousli/ngx-highlightjs/issues/260) in [cadcd11](https://github.com/MurhafSousli/ngx-highlightjs/pull/261/commits/cadcd11564adc23bda9d9a0f2bc6b9d26651bee1).
- fix: Add line-numbers as a sub package, closes [#234](https://github.com/MurhafSousli/ngx-highlightjs/issues/234) in [7f8f551](https://github.com/MurhafSousli/ngx-highlightjs/pull/261/commits/7f8f551a044d6f783ecfa98e2d61299ea41f0294).
- refactor: Update deprecated rxjs usage.

### Breaking changes

- When using `HighlightPlusModule`, you must have `provideHttpClient()` provided in your `main.ts` file in order to make the http requests work.

## 9.0.0

- Update to Angular 16.
Expand Down
195 changes: 136 additions & 59 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,46 +39,39 @@ npm i ngx-highlightjs

## Usage

### Import `HighlightModule` in your app
### Provide the config for `HIGHLIGHT_OPTIONS` in `main.ts` file

```typescript
import { HighlightModule, HIGHLIGHT_OPTIONS } from 'ngx-highlightjs';
import { HIGHLIGHT_OPTIONS } from 'ngx-highlightjs';

@NgModule({
imports: [
HighlightModule
],
bootstrapApplication(AppComponent, {
providers: [
{
provide: HIGHLIGHT_OPTIONS,
useValue: {
fullLibraryLoader: () => import('highlight.js'),
fullLibraryLoader: () => import('highlight.js')
}
}
],
]
})
export class AppModule { }
```

> Note: This will add highlight.js library including all languages to your bundle.
> 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 { HighlightModule, HIGHLIGHT_OPTIONS } from 'ngx-highlightjs';

@NgModule({
imports: [
HighlightModule
],
import { HIGHLIGHT_OPTIONS } from 'ngx-highlightjs';

bootstrapApplication(AppComponent, {
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
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'),
Expand All @@ -87,9 +80,8 @@ import { HighlightModule, HIGHLIGHT_OPTIONS } from 'ngx-highlightjs';
themePath: 'path-to-theme.css' // Optional, and useful if you want to change the theme dynamically
}
}
],
]
})
export class AppModule { }
```

### HighlightOptions API
Expand All @@ -103,15 +95,19 @@ export class AppModule { }
| 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 highlight.js@v10.x.x, should use `coreLibraryLoader: () => import('highlight.js/lib/core')` instead of `coreLibraryLoader: () => import('highlight.js/lib/highlight')`
> **NOTE:** Since the update of highlight.js@v10.x.x, 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.
**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.
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: [
Expand All @@ -124,7 +120,9 @@ Set the theme path in the global config, this makes it possible to change the th
}
]
```
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.

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.

Expand All @@ -143,7 +141,7 @@ export class AppComponent {
}
```

> You can still use the traditional way
> You can still use the traditional way


**Traditional way**
Expand All @@ -169,27 +167,41 @@ _[List of all available themes from highlight.js](https://github.com/isagalaev/h

The following line will highlight the given code and append it to the host element

```html
<pre><code [highlight]="code"></code></pre>
```ts
import { HighlightModule } from 'ngx-highlightjs';

@Component({
selector: 'app-root',
template: `
<pre><code [highlight]="code"></code></pre>
`,
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 |
| 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.`
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": {
Expand All @@ -207,27 +219,32 @@ To avoid this warning, add the following in your `angular.json`
}
}
```

Read more about [CommonJS dependencies configuration](https://angular.io/guide/build#configuring-commonjs-dependencies)

## Plus package

In version >= 4, a new sub-package were added with the following features:
This package contains the following features:

- Highlight gists using gists API
- Highlight code directly from URL

### Usage

```typescript
import { HighlightPlusModule } from 'ngx-highlightjs/plus';

@NgModule({
imports: [
HighlightPlusModule
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: // ...
}
]
})
export class AppModule {
}
```

### Highlight a gist file
Expand All @@ -238,10 +255,21 @@ export class AppModule {

**Example:**

```html
<pre [gist]="gistId" (gistLoaded)="gist = $event">
<code [highlight]="gist | gistContent: 'main.js'"></code>
</pre>
```ts
import { HighlightPlusModule } from 'ngx-highlightjs';

@Component({
selector: 'app-root',
template: `
<pre [gist]="gistId" (gistLoaded)="gist = $event">
<code [highlight]="gist | gistContent: 'main.js'"></code>
</pre>
`,
standalone: true,
imports: [HighlightPlusModule]
})
export class AppComponent {
}
```

### Highlight all gist files
Expand All @@ -250,12 +278,23 @@ To loop over `gist?.files`, use `keyvalue` pipe to pass file name into `gistCont

**Example:**

```html
<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>
```ts
import { HighlightPlusModule } from 'ngx-highlightjs';

@Component({
selector: 'app-root',
template: `
<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>
`,
standalone: true,
imports: [HighlightPlusModule, CommonModule]
})
export class AppComponent {
}
```

### Highlight code from URL directly
Expand All @@ -264,11 +303,48 @@ Use the pipe `codeFromUrl` with the `async` pipe together to get the code text f

**Example:**

```html
<pre>
<code [highlight]="codeUrl | codeFromUrl | async"></code>
</pre>
```
```ts
import { HighlightPlusModule } from 'ngx-highlightjs';

@Component({
selector: 'app-root',
template: `
<pre>
<code [highlight]="codeUrl | codeFromUrl | async"></code>
</pre>
`,
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'
}
},
]
})
```

<a name="development"/>

Expand All @@ -284,13 +360,14 @@ $ 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).
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).

<a name="author"/>

## Author

**Murhaf Sousli**
**Murhaf Sousli**

- [github/murhafsousli](https://github.com/MurhafSousli)
- [twitter/murhafsousli](https://twitter.com/MurhafSousli)
Expand Down
Loading