Rops NPM | npm.io

Rops; A lightweight publishing tool with github integration

Github: fuzmish/rops
NPM: rops

Rops is a lightweight static site generator for publishing markdown-based documents as web pages.

Getting Started

By using npx command, you can build your documents without any setups:

$ cd workspace
$ mkdir src
$ echo "# Hello Rops page" > src/index.md
$ npx rops
$ cat docs/index.html
<!DOCTYPE html>
<html>
...
  <h1>Hello Rops page</h1>
...

Example project: https://github.com/fuzmish/rainbowful-of-pockets

Features

Rops (and its built-in template) provides the following features:

Git integration: If the document is maintained in a git repository, the document will be published with information based on the commit information.
Github integration: If your Git repository is hosted on Github, you can display the commit information and links to the source files on your web page.
Works with Github Actions / Pages: Rops is designed to be deployed to Github Pages using Github Actions. In this strategy, you can publish a web page by simply pushing the .md source to the repository.
Math extension: Provides a markdown extension that supports LaTeX-style mathematical expressions and cross-references of equations. Detail
File watcher mode: If you prepare a development web server that supports hot-reload (such as live-server, reload), you can write documentation while previewing the build results locally.

Backends

Rops markdown renderer consists of the following OSSs:

markdown-it; A neat markdown processor with a lot of plugins..
KaTeX; Fast math typesetting for the web.
MarTeX; A helper library for extending Markdown for mathematical documents.

Guide

Deploying to GitHub Pages with Github Actions (CI/CD)

Summary:

Example workflow: https://github.com/fuzmish/rainbowful-of-pockets/blob/master/.github/workflows/node.js.yml
- Mainly uses peaceiris/actions-gh-pages

Configure Rops

Summary (the details are under preparation...):

You can use rops.config.js file (schema) to configure Rops behaviors.
Altenatively, you can pass any configuration in rops.config.js via CLI options. See $ rops -h.

Development

Rops is written in TypeScript. You can start development of Rops itself as follows:

$ git clone https://github.com/fuzmish/rops.git
$ cd rops
# dependencies and devDependencies would install
$ npm install
# build
$ npm run build

Please contribute to this project via Github.

FAQs / Troubleshoots

Please report issues via Github.

How to configure the renderers (such as markdown processor, math renderer, ...)?
- Currently, it is not provided. We are planning to do that.
How to modify the templates (the design of the web pages)?
- You can create your own templates, and pass them to Rops via rops.config.js's template property or CLI option -c '{"template":"/path/to/template/dir"}'. The default templates are here. Rops uses ejs as a template engine.
Got Error: Unbalanced tags:
- Your markdown source contains some unbalanced HTML tags (such as <div></p></div>). To process correctly, fix them.