ReLaXed README

The project's README from github.com/RelaxedJS/ReLaXed. As one markdown file: README.md.

ReLaXed

Build Status

ReLaXed creates PDF documents interactively using HTML or Pug (a shorthand for HTML). It allows complex layouts to be defined with CSS and JavaScript, while writing the content in a friendly, minimal syntax close to Markdown or LaTeX.

Here it is in action in the Atom editor:

And here are a few output examples:

Book - source / PDF Letter - Source / PDF Resume - Source / PDF Visit card - Source / PDF
Slides - Source / PDF Report - Source / PDF Paper - Source / PDF Poster - Source / PDF

ReLaXed has support for Markdown, LaTeX-style mathematical equations (via MathJax), CSV conversion to HTML tables, plot generation (via Vega-Lite or Chart.js), and diagram generation (via mermaid). Many more features can be added simply by importing an existing JavaScript or CSS framework.

Installing ReLaXed

Install ReLaXed via NPM with this command (do not use sudo):

npm i -g relaxedjs

This will provide your system with the relaxed command. If the installation fails, refer to the troubleshooting page. You can also use ReLaXed via Docker (see this repository)

Getting started

To start a project, create a new document my_document.pug with the following Pug content:

h1 My document's title
p A paragraph in my document

Then start ReLaXed from a terminal:

relaxed my_document.pug

ReLaXed will generate my_document.pdf from my_document.pug, then watch its directory and subdirectories so that every time a file changes, my_document.pdf will be re-generated.

It is also possible to generate the PDF file just once, with no sub-sequent file-watching, with this command:

relaxed my_document.pug --build-once

To go further:

Why yet another PDF document creator?

Many of us prefer markup languages (Markdown, LaTeX, etc.) to GUI document-editors like MS Office or Google Docs. This is because markup languages make it easier to quickly write documents in a consistent style.

However, Markdown is limited to the title/sections/paragraphs structure, and LaTeX has obscure syntax and errors that also make it difficult to stray from the beaten track.

On the other hand, web technologies have never looked so good.

ReLaXed is an attempt at finding the most comfortable way to leverage this for desktop PDF creation.

How ReLaXed works

ReLaXed consists of a few lines of code binding together other software. It uses Chokidar to watch the file system. When a file is changed, several JavaScript libraries are used to compile SCSS, Pug, Markdown, and diagram files (mermaid, flowchart.js, Chart.js) into an HTML page which is then printed to a PDF file by a headless instance of Chromium (via Puppeteer).

Using it as a Node Module

MasterToPDF.js is exposed by default as main package, which can be used directly.

An Example: 

const { masterToPDF } = require('relaxedjs');
const puppeteer = require('puppeteer');
const plugins = require('relaxedjs/src/plugins');
const path = require('path');

class HTML2PDF {
  constructor() {
    this.puppeteerConfig = {
      headless: true,
      args: [
        '--no-sandbox',
        '--disable-translate',
        '--disable-extensions',
        '--disable-sync',
      ],
    };

    this.relaxedGlobals = {
      busy: false,
      config: {},
      configPlugins: [],
    };

    this._initializedPlugins = false;
  }

  async _initializePlugins() {
    if (this._initializedPlugins) return; // Do not initialize plugins twice
    for (const [i, plugin] of plugins.builtinDefaultPlugins.entries()) {
      plugins.builtinDefaultPlugins[i] = await plugin.constructor();
    }
    await plugins.updateRegisteredPlugins(this.relaxedGlobals, '/');

    const chrome = await puppeteer.launch(this.puppeteerConfig);
    this.relaxedGlobals.puppeteerPage = await chrome.newPage();
    this._initializedPlugins = true;
  }

  async pdf(templatePath, json_data, tempHtmlPath, outputPdfPath) {
    await this._initializePlugins();
    if (this._initializedPlugins) {
      // Paths must be absolute
      const defaultTempHtmlPath = tempHtmlPath || path.resolve('temp.html');
      const defaultOutputPdfPath =
        outputPdfPath || path.resolve('output.pdf');

      await masterToPDF(
        templatePath,
        this.relaxedGlobals,
        defaultTempHtmlPath,
        defaultOutputPdfPath,
        json_data
      );
    }
  }
}

module.exports = new HTML2PDF();

Usage:

const HTML2PDF = require('./HTML2PDF.js');
(async () => {
    await HTML2PDF.pdf('./template.pug', {"a":"b", "c":"d"});
})();

Contribute!

ReLaXed is an open-source framework originally written by Zulko and released on Github under the ISC licence. Everyone is welcome to contribute!

For bugs and feature requests, open a Github issue. For support or Pug/HTML-related questions, ask on Stackoverflow or on the brand new reddit/r/relaxedjs forum, which can be used for any kind of discussion.

Projects members:

License

ISC

ReLaXed (RelaxedJS/ReLaXed)

puppeteer
Searching Database…

11.8K ·GitHub
ReLaXed
What is this?ReLaXed is a tool that lets you write documents in Pug or HTML and turns them into PDF files, so you can lay things out with CSS and JavaScript instead of fighting LaTeX or a GUI editor.
Is this a GUI editor or a command-line tool?It is a command-line tool. You write Pug/HTML files in any text editor you like, then run the 'relaxed' command, which watches the files and regenerates the PDF every time you save.
How do I install it and generate my first PDF?Install it globally through NPM without sudo, which gives you the 'relaxed' command, then run 'relaxed mydocument.pug' to watch and continuously rebuild the PDF, or add a flag to render once and stop.
What's actually working behind the scenes to produce the PDF?Chokidar watches your files, several JS libraries compile SCSS, Pug, Markdown and diagrams into an HTML page, and that page is then printed to PDF by a headless Chromium instance driven by Puppeteer.
Are there known installation pitfalls?Yes, the README explicitly flags that the NPM install can fail and points to a dedicated troubleshooting page, likely tied to bundling headless Chromium via Puppeteer.
Can I run it on any OS, and is there a Docker option?Headless Chromium via Puppeteer lets ReLaXed run on Linux, macOS and Windows, and there's also a separate Docker image maintained in another repository if you'd rather not install it locally.
Does ReLaXed support math equations, CSV tables and diagrams?Yes - it supports LaTeX-style math via MathJax, CSV-to-HTML-table conversion, charts via Vega-Lite or Chart.js, and diagrams via Mermaid, all usable inside your Pug/HTML files.
Can I use ReLaXed as a Node.js library instead of the CLI?Yes, its core module (MasterToPDF.js) is exposed as the main package export, so you can call it directly from your own Node.js code instead of running the CLI.
Why did the author build this instead of using LaTeX or MS Word?The author wanted the clean, modern styling of CSS frameworks and the huge JavaScript ecosystem (plotting, syntax highlighting, equations) combined with lightweight markup like Pug, avoiding LaTeX's obscure syntax and the inconsistency of GUI editors.
What are similar projects?bentopdf, handout-remake, sghtmltopdf, liteparse, pandoc, gotenberg, Filee, MiniPdf
Which topics is it in?pdf-converter, pdf-generation, headless-browser, puppeteer, scss, document, converter, chromium, csv, latex, charts, document-processing
Creator
RelaxedJS
Size
0.8 MB
Stars
11.8K
Updated
CommitSep 07
Age
8y
Commits · 90 Days