canpress

v0.3.0

Published

3 years ago

Everything you need for markdown-driven academic web press, condensed in a single can.

0High
0Medium
0Low

condensedmilk

markdown-it markdown academic press bibliography citation latex maths katex r-markdown

CanPress

A web-oriented R-markdown style academic text formatting from markdown to HTML, featuring minimal configurable templates and live preview in the browser.

This is a work in progress.

Installation

It is recommended to use it as a dev dependency in your project, as it has some vulnerabilities.

npm i -D canpress

For CLI usage on daily basis, it can be installed globally, although make sure you know what you are doing.

npm i -g canpress

CLI Usage

USAGE
    canpress <input_file.md> <flags>

FLAGS
    -i <path/to/input.md>
        Input file path. This flag is required.

    -o <path/to/file.html>
        Output rendered HTML to given path. Defaults to the input file name.

    -b <path/to/bibliography.bib>
        Bibliography file path. Defaults to 'bibliography.bib' in working directory.
        This can also be specified in the front-matter of markdown file under 'bibPath' attribute.

    -t <path/to/template.html>
        Custom template file path. The built-in template is used by default.

    -nt
        No template. Produces just the HTML which is supposed to be inside the document body.

    -l
        Live server with preview in the browser. Refreshes when changes are made to markdown file.

    -p <port_number>
        Custom port number for the live server. 8080 by default.

Here's a quick guide on citations and bibliography made possible with markdown-it-biblatex.

A quick overview of maths with KaTeX also contains links to available functions.

Library Usage

Basic Usage

const CanPress = require("canpress");

// Instantiate canpress with configuration
const canpress = new CanPress({
  // Path to bibliography file
  bibPath: "./bibliography.bib",
  // Path to template
  templatePath: "my-template.html",
  // Use default template (false by default)
  defaultTemplate: false,
  // markdown-it-biblatex plugin configuration
  mdBiblatexConfig: {},
});

// Assuming you have a written markdown file
const result = canpress.render("./input.md", "./bibliography.bib"); // bibliography can also be specified here
console.log(result);

For configuring markdown-it-biblatex, see the documentation of the library.

Custom MarkdownIt Plugins

Since this library is just a preconfigured extendable collection of markdown-it plugins, you can add your own. CanPress has an instance of MarkdownIt as its property.

const canpress = new CanPress({});

canpress.markdownIt.use(require("markdown-it-highlightjs"));

Templates & Templatization

Templates are used to make a plain HTML output more interesting by adding HTML skeleton, scripts, styles, meta tags, and most importantly - rendering front-matter data and document body in spots designated by "marks".

A basic template might look like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>[TITLE]</title>
  </head>
  <style>
    body {
      background: black;
      color: white;
    }
  </style>
  <body>
    <main>
      <article>
        <h1>[TITLE]</h1>
        <h2>[AUTHOR]</h2>
        [CONTENT]
      </article>
    </main>
  </body>
</html>

If we use the above template for the following markdown text:

---
title: "The Title"
author: "John Doe"
---

This is content

We will get the following output:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>The Title</title>
  </head>
  <style>
    body {
      background: black;
      color: white;
    }
  </style>
  <body>
    <main>
      <article>
        <h1>The Title<h1>
        <h2>John Doe</h2>
        <p>This is content</p>
      </article>
    </main>
  </body>
</html>

By default CanPress only knows these three marks: [TITLE], [AUTHOR], [CONTENT]. It replaces every instance of these marks with their respective data values in the front matter, the exception being [CONTENT] which represents the markdown document body.

The templatization and marks can be configured.

In marks object, each key corresponds to the front-matter key specified in the markdown file. The values of the front-matter keys then replace the corresponding marks that share the same key in CanPress.marks object.

// Default marks. Can be modified.
canpress.marks = {
  content: "[CONTENT]",
  title: "[TITLE]",
  author: "[AUTHOR]",
};

The CanPress.templatize function places front matter values and markdown body in the template. The content parameter is the parsed markdown file by the front-matter library. All the front-matter attributes are under the content.attributes property, while the body is in content.body. The md parameter is the instance of MarkdownIt that needs to render the markdown body.

// Default templatize function. Can be modified.
canpress.templatize = function (content, template, md) {
  let html = template.replace(canpress.marks.content, md.render(content.body));

  for (const key in canpress.marks) {
    html = html.replaceAll(canpress.marks[key], content.attributes[key] || "");
  }

  return html;
};

Libraries used

This is not a standalone library, but rather a combination of these preconfigured libraries:

To do

General

Full unit tests coverage
Documentation on citation, configuration, custom templates, etc.:
- Make it accessable from the preview template
- Build it from markdown using this very library (custom little build-doc script)
- Write tests that makes sure modified documentations in markdown have been built
Fix occasional infinite refresh loop on live server.
Use configuration JSON file.

Library

Param documentation

Long-term

Allow the library to use not just paths to files (input file and bibliography file) to render output, but just simple strings. This has to be added to markdown-it-biblatex.