bebraw / highlight-loader

Applies highlight.js to given HTML (MIT)

highlight-loader - Applies highlight.js to given module

This loader can apply syntax-highlighting via highlight.js in two ways:

1. Given HTML (either straight HTML or the output of something like markdown-loader), it will replace the contents of <code> blocks with syntax-highlighted HTML generated by highlight.js. This is the default behavior.

2. Given a raw file, it will return syntax-highlighted HTML generated by highlight.js. This can be enabled by using the raw parameter.

You probably want to pass the HTML output of this loader through html-loader.

Parameters

raw

If any value is provided, the loader will interpret its input as a raw string to run through highlight.js.

By default, the language is auto-detected. To specify a language, use the lang parameter.

lang

Specify a language for highlight.js. Only works in combination with the raw parameter.

(To specify a language for non-raw input, apply lang-[something] classes to your <code> blocks.)

exec

Execute the input that highlight-loader receives. Useful in cases when chaining another loader which returns a function. One use case is to combine this with the apply-loader.

By default, exec is false and simply treats its input as a string.

Installation

Install with npm:

npm install highlight-loader --save-dev

Make sure highlightjs is included and initialized on your page.

Usage

Add highlight-loader as a webpack loader:

module: {
  loaders: [
    {
      test: /\.md$/,
      loader: 'html!highlight!markdown',
      include: PATHS.markdown
    }
  ]
}

Examples

// Reading HTML from parsed markdown
var highlightedMarkdown = require('html!highlight!markdown!./README.md');

// Reading a file's raw contents and auto-detecting the language
var highlightedRaw = require('html!highlight?raw=true!./example-script.js');

// Reading a file's raw contents and specifying the language
var highlightedRawCss = require('html!highlight?raw=true&lang=css!./example-stylesheet.css');

// Reading HTML from a template loader
var highlightedRenderedJadeTemplate = require('html!highlight?exec!apply!jade!./index.jade')

Contributors

• David Clark - Added raw and lang parameters
• Zane Miller - Added missing hljs class to pre element
• Javier Castro - Added Node support
• Sidd Sridharan - Added support for exec parameter
• M.K. Safi - Added installation instructions

License

highlight-loader is available under MIT. See LICENSE for more details.

highlight-loader's Issues

Whether to consider support for line numbers?

I know highlight.js don't support line number. Whether we can add this feature?

NodeJS compat: this.cacheable() not found

I'm trying to use this module server-side on my NodeJS app.

this.cacheable()

is not there.

Not working with markdown-loader >= 3.0.0

Since markdown-loader 3.0.0, as it follows marked 0.4.0, language prefix is changed from lang to language, but this loader only accepts lang.

Highlight raw files

I would like to be able to use this in combination with raw-loader to highlight raw files that do not contain the <code> tag (or any HTML).

For example, I'd like to:

var myCodeHighlighted = require('!!raw!highlight!myCode.js');

Any interest in adding this feature? If so, I could work on a PR for it.

hljs class does not get applied to pre element

When parsing markdown (the suggested use for this loader) the hljs class does not get applied to the pre element, causing all built in themes to not render the container correctly.

Option to receive both raw and highlighted code

I'd love to get both raw and highlighted code from the input file.

Right now my workaround is to require it twice: once with the raw-loader, once with the highlight-loader.

I'd love it if I could set an option on this loader to export an object instead of a string — an object with raw and highlighted properties.

What do you think? (Happy to work on a PR if you like the idea.)

Adding "Copy to Clipboard"

I would like to add a copy to clipboard option to the code section. I wonder how I can do it.

One option is to add the button using css :after and then listen to click events. However I still need to be able to get raw content from somewhere. Is it possible to add it as, for example, data-raw attribute to the code element?

Allow highlighter to be swapped?

It might make sense to decouple the loader from highlight.js. Maybe it could still remain as default. Allowing it to be replaced with something else could be a good move.

Inline language declaration throws unknown language

I'm using this with the markdown and html loaders as shown in the examples here. However, if my markdown code block uses inline language declaration then it throws errors about an unknown language.

ERROR in ./src/components/switch/docs/readme.md
Module build failed: Error: Unknown language: "language-typescript"
    at highlight (C:\dev\WebCommon-HtmlShare\node_modules\highlight.js\lib\highlight.js:494:13)
    at highlightCode (C:\dev\WebCommon-HtmlShare\node_modules\highlight-loader\index.js:50:12)
    at Object.<anonymous> (C:\dev\WebCommon-HtmlShare\node_modules\highlight-loader\index.js:38:12)
    at initialize.<anonymous> (C:\dev\WebCommon-HtmlShare\node_modules\cheerio\lib\api\manipulation.js:275:74)
    at exports.domEach (C:\dev\WebCommon-HtmlShare\node_modules\cheerio\lib\utils.js:52:24)
    at initialize.exports.replaceWith (C:\dev\WebCommon-HtmlShare\node_modules\cheerio\lib\api\manipulation.js:268:3)
    at Object.module.exports (C:\dev\WebCommon-HtmlShare\node_modules\highlight-loader\index.js:25:13)
 @ ./src/components/switch/docs/index.ts 4:0-48 4:0-48
 @ ./src/docs.ts
 @ multi (webpack)-dev-server/client?http://localhost:8080 ./src/docs.ts
i ｢wdm｣: Failed to compile.

the portion causing the problem in the md file:

```typescript
import { Switch } from '@salespad/html-share';
const switch = new Switch(document.getElementById('switch-example'));
/```

and the relevant portion of the config:

{
          test: /\.md$/,
          loader: 'html-loader!highlight-loader!markdown-loader'
}

Make hightlight.js a peer dependency

Please make highlight.js a peer dependency as recommended by webpack.

Peer Dependencies

If the loader you're working on is a simple wrapper around another package, then you should include the package as a peerDependency. This approach allows the application's developer to specify the exact version in the package.json if desired.

For instance, the sass-loader specifies node-sass as peer dependency like so:

{
  "peerDependencies": {
    "node-sass": "^4.0.0"
  }
}

https://webpack.js.org/contribute/writing-a-loader/#peer-dependencies