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)

Searching Database…

11.8K ·GitHub
ReLaXed
这是什么？ReLaXed 是一个工具，可以用 Pug 或 HTML 编写文档并将其生成为 PDF 文件，让你用 CSS 和 JavaScript 来排版，而不必和 LaTeX 或图形界面编辑器较劲。
这是图形界面编辑器还是命令行工具？它是一个命令行工具。你可以用任意文本编辑器编写 Pug/HTML 文件，然后运行 'relaxed' 命令，它会监视这些文件，每次保存时重新生成 PDF。
我该如何安装并生成第一个 PDF？通过 NPM 全局安装（不要使用 sudo），即可获得 'relaxed' 命令；然后运行 'relaxed mydocument.pug'，即可监视文件并持续重新生成 PDF；或者添加一个参数，只渲染一次然后停止。
生成 PDF 的背后究竟是哪些组件在工作？Chokidar 负责监视你的文件，多个 JS 库把 SCSS、Pug、Markdown 和图表编译成 HTML 页面，然后由 Puppeteer 驱动的无界面 Chromium 实例将该页面打印为 PDF。
安装时有哪些已知的坑？有的。README 明确指出 NPM 安装可能失败，并附有专门的故障排除页面，这很可能与通过 Puppeteer 捆绑无界面 Chromium 有关。
能在任何操作系统上运行吗？有 Docker 选项吗？通过 Puppeteer 使用无界面 Chromium，ReLaXed 可以在 Linux、macOS 和 Windows 上运行；如果你不想在本地安装，还有一个单独的 Docker 镜像，由另一个仓库维护。
ReLaXed 支持数学公式、CSV 表格和图表吗？支持。它可以通过 MathJax 显示 LaTeX 风格的数学公式，将 CSV 转换为 HTML 表格，通过 Vega-Lite 或 Chart.js 绘制图表，并通过 Mermaid 绘制图示，所有这些都可以在你的 Pug/HTML 文件中使用。
我能把 ReLaXed 当作 Node.js 库使用，而不是命令行工具吗？可以。它的核心模块（MasterToPDF.js）作为包的主导出对外开放，因此你可以直接在自己的 Node.js 代码中调用它，而无需运行命令行工具。
作者为什么要自己开发，而不用 LaTeX 或 MS Word？作者希望结合 CSS 框架简洁现代的样式、庞大的 JavaScript 生态（绘图、语法高亮、公式），以及 Pug 这种轻量的标记语法；同时避开 LaTeX 晦涩的语法和图形界面编辑器的不一致性。
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