readme.md

Markademic

npm i markademic -S

A tool for rendering academically flavored markdown.

Features

• 😲 Markdown rendering powered by Remarkable.

• 👥 Citation support following the BibJSON specification.

• 🔣 Symbol definition support for cases where you want to define the meaning of a math symbol used in a formula.

• 🧤 LaTeX rendering support with Katex.

• 🖊️ 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.

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,
  
  // 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'),
  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.

Markdown Additions

Citations

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

becomes:

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

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). This uses the BibJSON specification, which is just a JSON version of common LaTeX bibliographies.

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

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

Social Connections

Often times authors provide some means of contacting them, either via Twitter, GitHub, LinkedIn, Discord, Zoom, Email, etc. If you enter in their social media information in the author object, it can be displayed more prominently by Markademic:

{
  "satran2018": {
    "title": "Fence-Based Resource Management",
    "author": [
      {
      "name": "Michael Satran",
      "github": "https://github.com/msatranjr"
      },
      {
        "name": "Steven White",
        "github": "https://github.com/stevewhims"
      }
      ],
    "year": 2018,
    "publisher": "Microsoft",
    "link": [
      {
        "url": "https://docs.microsoft.com/en-us/windows/win32/direct3d12/fence-based-resource-management"
      }
    ]
  }
}

Since the authors each have a GitHub account, this can be used to get their profile picture.

Alternatively, emails can be queried by common community profile picture tools like Gravatar.

These will be displayed by markademic as so: <ProfilePicture/> <AuthorName href="{authorWebsite}"/> (@<TwitterHandle/>).

type BibTexAuthor =
{
  name: string,
  website?: string,
  github?: string,
  twitter?: string,
  email?: string
}

LaTeX

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

\gamma = \mu \chi + \beta

becomes:

Easily describe mathematical proofs, formulas, or formalize some algorithms.

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!).