Mark-rs

Mark-rs is a multithreaded, 100% Commonmark-compliant Markdown parser and static site generator written in Rust. It is designed to be fast, efficient, and easy to use.

Table of Contents

• Mark-rs
  • Table of Contents
  • Features
  • Installation
  • Usage
    • Options
  • Configuration
  • ⚠️Note: Raw HTML

Features

• Fast Markdown parsing
• HTML generation
• Multithreaded
• Custom configuration
• Easy-to-use CLI

Preview

For the example input:

# Hello, World

This is some sample Markdown content.
Here's a picture saying "Hello, World!":
![Image with a black background and white text saying "Hello, World!"](https://www.dummyimage.com/600x400/000/fff&text=Hello,+World!)

The following HTML page will be generated:

Installation

To install Mark-rs, you need to have Rust installed on your system. You can install Rust using rustup.

Install via Cargo

Once you have Rust installed, you can install Mark-rs using Cargo:

cargo install mark-rs

Note: Make sure to have the ~/.cargo/bin directory in your PATH environment variable so you can run the markrs command from anywhere.

If it isn't already in your PATH, you can adding the following line to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc, etc.):

export PATH="$HOME/.cargo/bin:$PATH"

On Windows, you can add the C:\Users\your_user\.cargo\bin directory to your PATH environment variable.

Install via Pre-built Binaries

You can also download pre-built binaries for your platform from the releases page

From there, you can download the appropriate binary for your operating system and architecture, extract it, and use it directly.

Updates

If Mark-rs was installed using Cargo, you can update it to the latest version by running:

cargo install mark-rs

If you installed Mark-rs using pre-built binaries, you can download the latest version from the releases page

Usage

To use Mark-rs, you can run the following command in your terminal:

markrs [OPTIONS] <INPUT_DIR>

Where <INPUT_DIR> is the path to the directory of Markdown files you want to parse. The output will be written to /output by default.

Options

You can also use the following CLI arguments to customize the behavior of Mark-rs:

• -c, --config <CONFIG>: Specify a custom configuration file (default: ./config.toml).
• -o, --output-dir <OUTPUT_DIR>: Specify the output directory for the generated HTML files (default: /output).
• -n --num_threads <NUM_THREADS>: Specify the number of threads to use (default: 4).
• -r, --recursive: Recursively parse all Markdown files in the specified directory and its subdirectories. (default: false if not present)
• -v, --verbose: Enable verbose output, which will print additional information while the program is running.
• -h, --help: Display help information.
• -V, --version: Display the version of Mark-rs.

Configuration

You can customize Mark-rs's behavior by specifying a config file to use. If a config file is not specified, then the default configuration directory will be checked; if no config file already exists, then the default config.toml file will be written.

The default configuration directories (defined by the dirs crate ) are:

Here is the default configuration:

# Tokenization
[lexer]
tab_size = 4

# HTML Generation
[html]
css_file = "default" # "default" for the default styles
favicon_file = ""    # Empty for no favicon
use_prism = false    # If "true", the CDN links for PrismJS will be used for codeblock highlighting
# Note that `use_prism = true` this will add `<script>` and `<link>` elements to the page
prism_theme = "vsc-dark-plus" # Will only take effect if "use_prism" is set to "true"
# See https://github.com/PrismJS/prism-themes for themes and https://cdnjs.com/libraries/prism-themes for what to set "prism_theme" to
sanitize_html = true # If "true", the HTML will be sanitized to prevent XSS attacks

Note: Raw HTML

Mark-rs supports using raw HTML in input Markdown files, but it should be noted that using raw HTML can lead to security vulnerabilities, such as XSS (Cross-Site Scripting) attacks, if the input is not properly sanitized. Therefore, it is recommended to use raw HTML with caution and only when necessary. By default, Mark-rs will sanitize the generated HTML before it is written to each file, but you should still be careful when using raw HTML.

If you want to use raw HTML without any sanitizing, you can disable HTML sanitizing by setting sanitize_html = false in your config.toml file.

For more information on XSS attacks, see OWASP and the OWASP XSS Prevention Cheat Sheet.