https://github.com/thom4parisot/asciidoctor-prism-extension
Highlight code listings with Prism.js, server side, with no front-end dependencies.
https://github.com/thom4parisot/asciidoctor-prism-extension
asciidoc asciidoctor asciidoctor-js prismjs syntax-highlighting
Last synced: about 2 months ago
JSON representation
Highlight code listings with Prism.js, server side, with no front-end dependencies.
- Host: GitHub
- URL: https://github.com/thom4parisot/asciidoctor-prism-extension
- Owner: thom4parisot
- License: mit
- Created: 2019-01-01T12:46:37.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-03-10T23:25:40.000Z (about 2 months ago)
- Last Synced: 2025-03-17T01:21:32.561Z (about 2 months ago)
- Topics: asciidoc, asciidoctor, asciidoctor-js, prismjs, syntax-highlighting
- Language: JavaScript
- Homepage: https://npmjs.com/asciidoctor-prism-extension
- Size: 58.6 KB
- Stars: 6
- Watchers: 3
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# asciidoctor-prism-extension [](https://github.com/thom4parisot/asciidoctor-prism-extension/actions/workflows/test.yml)
> Highlight Asciidoc code listings with Prism.js, server side, with no front-end dependencies.
This module is intended to be used with [Asciidoctor.js][], and Node.js (v10+). It adds a new syntax highlighter, to be used when converting Asciidoc to HTML5 documents. The syntax highlighting happens during the document conversion.
# Install
```bash
$ npm install @asciidoctor/core asciidoctor-prism-extension
```
# Configure
## Register the extension
```js
const asciidoctor = require('@asciidoctor/core')();
const prismExtension = require('asciidoctor-prism-extension');
asciidoctor.SyntaxHighlighter.register('prism', prismExtension);
```
## Change the rendering
This extension relies on [Asciidoc attributes](asciidoc-attributes) to affect the **theme** and the **highlighted syntaxes**.
```asciidoc
= Document
:source-highlighter: prism
:prism-languages: bash,docker,jsx
...
```
| Attribute | Default | Possible values
| --- | --- | ---
| `prism-theme` | `prism.css` | [Any filename in this list][prism-themes].
| `prism-languages` | `asciidoc,bash,json,markdown,typescript,yaml` | [Any supported language][prism-languages].
Theme can be disabled with the negated attribute (`!` character):
```asciidoc
= Document
:source-highlighter: prism
:prism-theme!:
:prism-languages: bash,docker,jsx
...
```
## Render document
Then you convert as usual:
```js
asciidoctor.convertFile('document.adoc', {
to_file: 'document.html',
backend: 'html5'
});
```
**Note**: attributes can be specified at this stage too. [Have a look at Asciidoctor.js API][asciidoc-api] to learn more about it.
# Use
Author your documents as you would regularly do. The second argument of a _code listing_ hints the language to the syntax highlighter.
In the following example, `yaml` is going to be used to colour the output:
```asciidoc
[source,yaml]
.example.yml
----
language: node_js
node_js: node
script: npm test
----
```
# About
## Prism
[Prism][] is a highly configurable **syntax highlighter**.
## License
[MIT](LICENSE).
[Prism]: https://prismjs.com
[prism-themes]: https://github.com/PrismJS/prism/tree/master/themes
[prism-languages]: https://prismjs.com/#languages-list
[Asciidoctor.js]: https://github.com/asciidoctor/asciidoctor.js/
[Asciidoctor]: https://asciidoctor.org
[asciidoc-api]: https://github.com/asciidoctor/asciidoctor.js/blob/master/docs/manual.adoc#api
[asciidoc-code-blocks]: https://asciidoctor.org/docs/user-manual/#source-code-blocks
[asciidoc-attributes]: https://asciidoctor.org/docs/user-manual/#attributes