https://github.com/jirutka/asciidoctor-katex

Asciidoctor extension for converting latexmath using KaTeX at build time
https://github.com/jirutka/asciidoctor-katex

asciidoc asciidoctor asciidoctor-extension katex latex math-expressions

Last synced: 2 months ago
JSON representation

Asciidoctor extension for converting latexmath using KaTeX at build time

• Host: GitHub
• URL: https://github.com/jirutka/asciidoctor-katex
• Owner: jirutka
• License: mit
• Created: 2018-08-11T17:07:53.000Z (over 6 years ago)
• Default Branch: master
• Last Pushed: 2023-02-08T00:32:28.000Z (almost 2 years ago)
• Last Synced: 2024-10-05T18:47:12.297Z (4 months ago)
• Topics: asciidoc, asciidoctor, asciidoctor-extension, katex, latex, math-expressions
• Language: Ruby
• Homepage:
• Size: 57.6 KB
• Stars: 17
• Watchers: 3
• Forks: 5
• Open Issues: 4
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE

Awesome Lists containing this project

README

        
= Asciidoctor KaTeX

:source-language: shell

// custom

:gem-name: asciidoctor-katex

:gh-name: jirutka/{gem-name}

:gh-branch: master

:codacy-id: 58f6aa6e3ef04c8aad1ecd276a8a2c35

ifdef::env-github[]

image:https://github.com/{gh-name}/workflows/CI/badge.svg[CI Status, link=https://github.com/{gh-name}/actions?query=workflow%3A%22CI%22]

image:https://api.codacy.com/project/badge/Coverage/{codacy-id}["Test Coverage", link="https://www.codacy.com/app/{gh-name}"]

image:https://api.codacy.com/project/badge/Grade/{codacy-id}["Codacy Code quality", link="https://www.codacy.com/app/{gh-name}"]

image:https://img.shields.io/gem/v/{gem-name}.svg?style=flat[Gem Version, link="https://rubygems.org/gems/{gem-name}"]

image:https://img.shields.io/npm/v/{gem-name}.svg?style=flat[npm Version, link="https://www.npmjs.org/package/{gem-name}"]

image:https://img.shields.io/badge/yard-docs-blue.svg[Yard Docs, link="http://www.rubydoc.info/github/{gh-name}/{gh-branch}"]

endif::env-github[]

// This is used for testing on CI.

ifdef::env-test[]

:stem: latexmath

stem:[E = mc^2]

endif::env-test[]

This project provides an http://asciidoctor.org/[Asciidoctor] extension for converting block and inline https://asciidoctor.org/docs/user-manual/#activating-stem-support[STEM] in TeX notation (latexmath) to HTML using https://khan.github.io/KaTeX[KaTeX] library right during document conversion (instead of in browser on client-side).

== Requirements

ifndef::npm-readme[]

=== Ruby

* https://www.ruby-lang.org/[Ruby] 2.3+ or http://jruby.org/[JRuby] 9.1+

* https://rubygems.org/gems/asciidoctor/[Asciidoctor] 1.5.6+

* https://rubygems.org/gems/katex[katex (gem)] ~> 0.8.0

* JavaScript engine supported by https://github.com/rails/execjs#execjs[ExecJS]

* https://rubygems.org/gems/thread_safe/[thread_safe] (not required, but recommended for Ruby MRI)

=== Node.js

endif::npm-readme[]

* https://nodejs.org/[Node.js] >=8

* https://www.npmjs.com/package/@asciidoctor/core[@asciidoctor/core] >=2.0.0 <2.2.0

* https://www.npmjs.com/package/katex[katex (module)] >=0.9.0

== Installation

ifndef::npm-readme[]

=== Ruby

Install {gem-name} from Rubygems:

[source, subs="+attributes"]

gem install {gem-name}

or to install the latest development version:

[source, subs="+attributes"]

gem install {gem-name} --pre

=== Node.js

endif::npm-readme[]

Install {gem-name} from npmjs.com:

[source, sh, subs="+attributes"]

npm install --save {gem-name}

== Usage

ifndef::npm-readme[]

=== CLI

If you invoke Asciidoctor from command-line, use option `-r` to load the extension:

[source, subs="+attributes"]

asciidoctor -r {gem-name} README.adoc

=== Ruby

Just `require '{gem-name}'`.

However, if you don’t want the extension to be automatically registered in Asciidoctor, `require 'asciidoctor/katex/treeprocessor'` instead.

IMPORTANT: Bundler automatically _requires_ all the specified gems.

           To prevent it, use +

           `gem '{gem-name}', require: false`.

=== Node.js

endif::npm-readme[]

[source, js, subs="+attributes"]

----

// Load asciidoctor.js and {gem-name}.

const asciidoctor = require('@asciidoctor/core')()

const asciidoctorKatex = require('{gem-name}')

// See documentation at the end of this section.

const options = {

  katexOptions: {

    macros: {

      "\\RR": "\\mathbb{R}",

    },

  },

}

// Configure the extension and register it into global registry.

asciidoctorKatex.register(asciidoctor.Extensions, options)

// Convert the content to HTML.

const content = `

:stem: latexmath

Do some math: stem:[E = mc^2]

`

const html = asciidoctor.convert(content)

console.log(html)

----

You may also register the extension into a custom extensions registry:

[source, js]

const registry = asciidoctor.Extensions.create()

asciidoctorKatex.register(registry, options)

.*Options:*

katex::

  The katex object to use for rendering.

  Defaults to `require('katex')`.

requireStemAttr::

  Whether to require `stem` attribute to be defined (Asciidoctor’s standard behaviour).

  Set to `false` to process latexmath even when `stem` attribute is not defined.

  Default is `true`. +

  Note that the default stem type hard-coded by Asciidoctor is `asciimath` (not `latexmath`), so `[stem]` block and `++stem:[...]++` macro will not be rendered anyway (only `[latexmath]` block and `++latexmath:[...]++` macro).

katexOptions::

  The default options for `katex.render()`.

  Defaults to empty object.

== License

This project is licensed under http://opensource.org/licenses/MIT/[MIT License].

For the full text of the license, see the link:LICENSE[LICENSE] file.