markademic

markademic

A markdown parser for academic articles, powered by Remarkable, BibJSON, Katex, and highlight.js.

Install

npm i markademic -S

Usage

Make a config object literal of the following type:

type Config = {

  // Input markdown string
  input: string,

  // BibJSON file you're using in file.
  citations?: BibJSON,

  // Symbols used in formulas.
  symbols?: {[latexSymbol: string]: {type: string, description: string}},

  // Reroute any relative links
  rerouteLinks?: ((str: string) => string)

};

Then pass that config to the markademic default export to get back a string of html.

import markademic from 'markademic';
import citations from './citations.json';
import fs from 'fs';
import path from 'path';

let config = {
  input: fs.readFileSync('./input.md').toString(),
  citations: require('./citations.json'),
  symbols: require('./symbols.json'),
  rerouteLinks: (link) => path.join('https://alain.xyz/myblogpost/', link)
}

let html = markademic(config);

In your project you will need the katex css files, as well as highlight.js css files.

Features

• Citation support following the BibJSON specification.
• Symbol definitions for LaTex math expressions.
• Syntax highlighting for 170 languages powered by highlight.js
• Reroute relative links for publishing to different platforms or syncing your output with the permalink of your website.
• Tooltip support powered by hint.css. (In Progress)

Markdown Additions

Citations

> I sometimes worry my life's work will be reduced to a 200-line @Shadertoy submission.[^timsweeny]

Similar to Latex References, to place references, simply write [^yourrefname], and this will be matched with your BibJSON object's key of the same name (minus the ^). (This is directly inspired by the same feature on stackedit.io).

On the bottom of your markdown file there will be some autoamtically generated references that look like this:

References
[gregory2014] Game Engine Architecture, Second Edition. Gregory, Jason CRC Press, 2014.
[moller2008] Real Time Rendering, Third Edition. Akenine-Moller, Thomas CRC Press, 2008.

LaTex

Latex is a markup language that's really suited for writing math equations:

\gamma = \mu \chi + \beta

Easily describe mathematical proofs, formulas, or formalize some algorithms. Marademic features a latex parser as well as a symbols config parameter where you can specify what the symbols used in your document mean. Then on the bottom of the page just before references, this will appear (formatted of course!).

Symbol	Type	Description
( \hat{n} )	( \mathbb{R}^2 )	Normal to surface point ( X )

Inspired by the same feature in The Graphics Codex.

Tooltips

Suround any statement with [@Your tooltip text here](the same code as a link or image, but with an @ at the front), and you'll have a tooltip. You can even put it around latex expressions!

Syntax Highlighting

vec4 integrate( in vec4 sum, in float dif, in float density, in vec3 bgcol, in float time )
{
    //Colors
    vec3 gray = vec3(0.65);
    vec3 lightgray = vec3(1.0,0.95,0.8);
    vec3 bluegray = vec3(0.65,0.68,0.7);
    vec3 orangegray =  vec3(0.7, 0.5, 0.3);

    //Density Colors
    vec4 col = vec4( mix( 1.15 * lightgray, gray, density ), density );
    vec3 lin =  (1.3 * bluegray) + (0.5 * orangegray * dif);
    col.xyz *= lin;
    col.xyz = mix( col.xyz, bgcol, 1.0 - exp(-0.003*time*time) );

    //Front to Back Blending
    col.a *= 0.4;
    col.rgb *= col.a;
    return sum + col*(1.0 - sum.a);
}

The same syntax highlighting featured in Github flavored markdown, odds are it supports your language (170 and counting!).