gulp-markdown-equations

A gulp plugin that makes it easy to replace markdown latex equations with rendered images

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-mathmodenode 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,

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:

$ 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:

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 = '<img alt="'+this.alt+'" valign="middle" src="'+this.path+
                  '" width="'+this.width/2+'" height="'+this.height/2+'">'
        return this.display ? '<p align="center">'+img+'</p>' : 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:

$ 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. If null, preprocessor step is skipped. See below for more details.
  • templator: a function of format function( tex, params ) {}that receives the preprocessed \LaTeXand parameters and returns a templated document. If null, the original tex string will be passed through unmodified. Default templator is equation-to-latex. See below for more detail.

Methods:

.completeSync( file, callback )

Once a file has been processed, you musttap into the stream and complete the markdown transformation. See above for an example. callbackis executed with thisset 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:

{ 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: <File "latex-d3a0aa2938.png" <Buffer 89 50 ... >> } }

.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('<img src="...">')) 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. Sample usage:

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, but in general it only must be a function of form:

function templator( content, parameters ) {
  // your logic
  return "\\documentclass... <latex>"
}

Credits

(c) 2015 Ricky Reusser. MIT License

Repository

https://github.com/rreusser/gulp-markdown-equations


上一篇:richardson-extrapolation
下一篇:integrate-simpson

相关推荐

  • 读marked.js源码-markdown是怎么变成html的

    很好奇markdown是怎么变成html的,偶然间看到 github(https://github.com/markedjs/marked)上的这一篇星星✨很高的源码,就来研究研究 下载打开在lib文...

    2 年前
  • 自己撸个 vue markdown loader

    最近,当我把 vueloader 升级到 v15 后发现,自己项目中所使用的一个 vuemarkdownloader 因为兼容问题而没法用了,正当我一筹莫展的时候,无意间看到 vuepress 中使用...

    2 年前
  • 自己动手写一个支持公式和图表的markdown 编辑器

    背景 在公司写周报时经常会用到markdown,并且曾经还为了能够解决团队每个人写完周报之后还要汇总的效率问题专门开发过一款内部使用的周报markdown编辑器,团队成员可以根据项目写相应的周报,最后...

    3 个月前
  • 简单谈谈gulp-changed插件

    前言 gulpchanged插件的作用,是用来过滤未被修改过的文件,只有修改后的文件才能通过管道。这样做的好处时,只处理修改后的文件,减少后续程序的执行时间。 根据官方给出的例子: 检测SR...

    3 年前
  • 程序员的专属微信公众号编辑器:定制 Markdown 转 HTML

    效果(Gif) 仓库地址 背景 在程序员的世界里,只要习惯用 Git,写文章必然就是 Markdown 了。 近来几天,重新玩起了微信公众号,最不能忍受的就是那个编辑器,效率很低。

    1 年前
  • 用gulp构建一个简单常用的的原生环境

    gulp作为一个自动化构建工具,在前端开发中大大的提高了开发效率,前端开发者们可以利用他减少许多繁复无脑的操作。 这里简单构建一个小环境,就可以在以后的学习中,直接新建各种test.html测试我们新...

    2 年前
  • 用gulp实现传统的多页面自动化构建,一句命令行完成混淆压缩

    工作的项目,摄像头的设置页面,要求整站大小只能在100k作用,也就是说vue之类的框架,jquery库这些最好不要用,我们就用js原生语言写,并且每次写完要整站都要压缩混淆再上传,考虑到浏览器文件缓存...

    5 个月前
  • 春季新增开源项目:见过能斗图的 Markdown 编辑器吗

    (https://img.javascriptcn.com/8a1626f48d0cd90dbf0558744e98d3c8) 每月新增开源项目。顾名思义,每月更新一期。

    2 年前
  • 整理笔记:前端工程构建工具gulp篇

    gulp ,基于 NodeJS 的项目,自动化构建的工具增强你的工作流程! 一、工作原理 前端构建工具,gulp是基于Nodejs,自动化地完成 javascript、coffee、sass、less...

    3 个月前
  • 微信小程序Markdown、HTML解析库(支持wepy)

    Towxml 是一个可将、转为微信小程序(WeiXin Markup Language)的渲染库。 用于解决在微信小程序中、不能直接渲染的问题。 特色 支持代码语法高亮 支持emo...

    2 年前

官方社区

扫码加入 JavaScript 社区