https://github.com/plus1tv/markademic
🏫 A tool for rendering academically flavored markdown.
https://github.com/plus1tv/markademic
academic bibjson latex markdown syntax-highlighting
Last synced: 2 months ago
JSON representation
🏫 A tool for rendering academically flavored markdown.
- Host: GitHub
- URL: https://github.com/plus1tv/markademic
- Owner: plus1tv
- License: mit
- Created: 2016-09-13T02:34:52.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2023-01-30T21:08:56.000Z (over 2 years ago)
- Last Synced: 2025-03-25T23:51:28.440Z (3 months ago)
- Topics: academic, bibjson, latex, markdown, syntax-highlighting
- Language: TypeScript
- Homepage:
- Size: 1.45 MB
- Stars: 10
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
- License: license.md
Awesome Lists containing this project
README
# Markademic
[![Npm Package][npm-img]][npm-url]
[![License][license-img]][license-url]
[![Unit Tests][travis-img]][travis-url]
[![Coverage Tests][codecov-img]][codecov-url]
```bash
npm i markademic -S
```
A tool for rendering academically flavored markdown.
## Features
- 😲 Markdown rendering powered by [Remarkable](https://github.com/jonschlinkert/remarkable).
- 👥 Citation support following the [BibJSON](http://okfnlabs.org/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](https://khan.github.io/KaTeX/).
- 🖊️ Syntax highlighting for 170 languages powered by [highlight.js](http://highlightjs.org).
- 🌠 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:
```ts
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.
```js
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
```markdown
> 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]](#sweeny2015).
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](https://stackedit.io)). This uses the [BibJSON specification](https://github.com/plus1tv/bibtex-bibjson), 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](https://twitter.com/alainxyz), [GitHub](https://github.com/alaingalvan), [LinkedIn](https://linkedin.com/in/alaingalvan), Discord, Zoom, Email, etc. If you enter in their social media information in the `author` object, it can be displayed more prominently by Markademic:
```json
{
"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](https://en.gravatar.com/site/implement/images/).
These will be displayed by markademic as so: ` (@)`.
```ts
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:
```tex
\gamma = \mu \chi + \beta
```
becomes:
Easily describe mathematical proofs, formulas, or formalize some algorithms.
### Syntax Highlighting
```glsl
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!)](https://highlightjs.org/static/demo/).
[cover-img]: assets/cover.gif
[cover-url]: http://codepen.io/alaingalvan/details/EgjbKP/
[release-img]: https://img.shields.io/badge/release-0.1.0-4dbfcc.svg?style=flat-square
[license-img]: http://img.shields.io/:license-mit-blue.svg?style=flat-square
[license-url]: https://opensource.org/licenses/MIT
[travis-img]: https://img.shields.io/travis/plus1tv/markademic.svg?style=flat-square
[travis-url]:https://www.travis-ci.com/github/plus1tv/markademic
[codecov-img]:https://img.shields.io/codecov/c/github/plus1tv/markademic.svg?style=flat-square
[codecov-url]: https://codecov.io/gh/plus1tv/markademic
[npm-img]: https://img.shields.io/npm/v/markademic.svg?style=flat-square
[npm-url]: http://npm.im/markademic
[npm-download-img]: https://img.shields.io/npm/dm/markademic.svg?style=flat-square