Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rreusser/gulp-markdown-equations
A gulp plugin that makes it easy to replace latex equations in a markdown file with rendered images
https://github.com/rreusser/gulp-markdown-equations
Last synced: 2 months ago
JSON representation
A gulp plugin that makes it easy to replace latex equations in a markdown file with rendered images
- Host: GitHub
- URL: https://github.com/rreusser/gulp-markdown-equations
- Owner: rreusser
- License: mit
- Created: 2015-07-21T19:06:00.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2015-07-24T23:23:25.000Z (over 9 years ago)
- Last Synced: 2024-10-14T00:01:41.317Z (2 months ago)
- Language: JavaScript
- Size: 363 KB
- Stars: 11
- Watchers: 3
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# gulp-markdown-equations
[](https://travis-ci.org/rreusser/gulp-markdown-equations) [](http://badge.fury.io/js/gulp-markdown-equations) [](https://david-dm.org/rreusser/gulp-markdown-equations)
A gulp plugin that makes it easy to replace markdown latex equations with rendered images
## Introduction
This module exposes the tools necessary to to transform 
equations in a markdown document into rendered raster or vector images. It uses the [transform-markdown-mathmode](https://www.npmjs.com/package/transform-markdown-mathmode) node module to locate and transform equations and reconnects with the gulp pipeline after the results have been rendered to complete the transformation using information from the result.
This means you can just mix into your markdown document. For example,
```markdown
It handles inline equations like $\nabla \cdot \vec{u} = 0$ and display equations like $$\frac{D\rho}{Dt} = 0.$$
```
gets transformed into:
It handles inline equations like 
and display equations like
Of course it's gulp plugin though, so that means you can really do whatever you want with it!
## Installation
To install, run:
```bash
$ npm install gulp-markdown-equations
```
## Example
The following is a gulp task that locates equations in markdown, renders them, and lets you do whatever you want with the result! First things first, here's the data flow:
```javascript
var gulp = require('gulp')
, mdEqs = require('gulp-markdown-equations')
, tap = require('gulp-tap')
, filter = require('gulp-filter')
, latex = require('gulp-latex')
, pdftocairo = require('gulp-pdftocairo')
gulp.task('mdtex',function() {
var texFilter = filter('*.tex')
var mdFilter = filter('*.md')
// Instantiate the transform and set some defaults:
var transform = mdEqs({
defaults: {
display: { margin: '1pt' },
inline: {margin: '1pt'}
}
})
return gulp.src('*.mdtex')
// Locate equations in the markdown stream and pass them as separate
// *.tex file objects:
.pipe(transform)
// Filter to operate on *.tex documents:
.pipe(texFilter)
// Render the equations to pdf:
.pipe(latex())
// Convert the pdf equations to png:
.pipe(pdftocairo({format: 'png'}))
// Send them to the images folder:
.pipe(gulp.dest('images'))
// Match the output images up with the closures that are still waiting
// on their callbacks from the `.pipe(transform)` step above. That means
// we can use metadata from the image output all the way back up in
// the original transform. Sweet!
.pipe(tap(function(file) {
transform.completeSync(file,function() {
var img = '
'
return this.display ? '
'+img+'
' : img
})
}))
// Restore and then change filters to operate on the *.md document:
.pipe(texFilter.restore()).pipe(mdFilter)
// Output in the current directory:
.pipe(gulp.dest('./'))
})
```
The task is run with:
```bash
$ gulp mdtex
```
## API
#### `require('gulp-markdown-mathmode')( [options] )`
Create a gulp-compatible buffered file stream transform. Options are:
- `defaults`: Parameters that get added to each equation object and passed to the templator. A good example is setting default margins that can be overridden later on with config variables added to a specific equation.
- `inline`: an associative array of key/value pairs for inline equations, into which preprocessed parameters are merged
- `display`: an associative array of key/value pairs for displaystyle equations, into which preprocessed parameters are merged
- `preprocessor`: a function that extracts equation-specific parameters. In other words, if your equation is `$[margin=10pt] y=x$`, the preprocessor extracts `{margin: '10pt'}`. Default preprocessor is [square-parameters](https://github.com/rreusser/square-parameters). If `null`, preprocessor step is skipped. See below for more details.
- `templator`: a function of format `function( tex, params ) {}` that receives the preprocessed `\LaTeX` and parameters and returns a templated document. If null, the original tex string will be passed through unmodified. Default templator is [equation-to-latex](https://github.com/rreusser/equation-to-latex). See below for more detail.
### Methods:
#### `.completeSync( file, callback )`
Once a file has been processed, you *must* tap into the stream and complete the markdown transformation. See above for an example. `callback` is executed with `this` set to an object containing equation metadata. The value you return is inserted into the markdown document.
The metadata contains all information about the processed equation, including the fully processed file at this point in the pipeline. If image dimensions are available, they will be added. For example:
```javascript
{ display: false,
inline: true,
margin: '0 1pt 0pt 0pt',
path: 'docs/images/latex-d3a0aa2938.png',
height: 38,
width: 104,
equation:
{ tex: '\\LaTeX',
alt: '\LaTeX',
templated: '\\documentclass[10pt] ... \end{document}\n',
file: > } }
```
#### `.complete( file, callback )`
An asynchronous version of `.complete()`. The format of the callback is `function( resultCallback ) { … }`. Once you've computed the value, you may pass the result to `resultCallback` (e.g. `resultCallback('
')`) and it will be inserted into the markdown document.
## Internals
### Preprocessor
The preprocessor is just a function that operates on the content of an equation before it's inserted in the LaTeX template in order to extract equation-specific config. The extracted parameters are merged into this equation's parameters. The default preprocessor [square-parameters](https://github.com/rreusser/square-parameters). Sample usage:
```javascript
var pre = require('square-parameters')`
pre("[name=parabola][margin=10pt 0pt]y=x^2")
// => { params: { name: "parabola", margin: "10pt 0pt" }, content: "y=x^2" }
```
### Templator
The templator's job is to insert into a full document. It receives configuration first from preprocessed parameters, then from the display/inline defaults passed as transform options. By default, the delimiters (`$$...$$` or `$...$`) add parameters `{display:true, inline: false}` or `{display:false, inline:true}`, respectively. The default templator is [equation-to-latex](https://github.com/rreusser/equation-to-latex), but in general it only must be a function of form:
```javscript
function templator( content, parameters ) {
// your logic
return "\\documentclass... "
}
```
## Credits
(c) 2015 Ricky Reusser. MIT License