CLI Tool

The @seqyuan/rst-cli package provides a rst-render command for converting RST files from the terminal.

For general reStructuredText syntax and project-specific template rules, see RST Writing Rules.

Installation

pnpm add -g @seqyuan/rst-cli

Usage

# HTML output (default)
rst-render input.rst

# HTML to file
rst-render input.rst -o output.html

# Markdown output
rst-render input.rst --md

# React component output
rst-render input.rst --react

# Jinja2 template rendering with project data + wildcard scans
rst-render report.rst.j2 -t -d project.json --scan plots=upload/plots/*_umap.png

Options

Option	Description
`-o, --output <path>`	Write output to file (default: stdout)
`-s, --standalone`	Bundle into self-contained HTML (inline CSS + images)
`--md, --markdown`	Output Markdown instead of HTML
`--react`	Output React component code
`-t, --template`	Render input as a Jinja2 template before HTML output
`-d, --data <path>`	JSON file with template context data
`-v, --var key=value`	Template variable (repeatable)
`--scan name=glob`	Scan files relative to the template directory and inject them into the template context
`--expand-includes`	Resolve `.. include::` directives relative to the input file before parsing
`-h, --help`	Show help message

Example: Project-Level Bioinformatics Report

For a complete end-to-end walkthrough (directory layout, shared QC fragments, pipeline integration), see Bioinformatics Report Tutorial.

For CLI-based bioinformatics reporting, input.rst should usually be a template, not a fully expanded report. Put project metadata in a JSON file, and use --scan to inject wildcard-matched result files.

Directory Layout

report/
├── assets/
│   └── seqyuan-logo.png
├── project.json
├── report.rst.j2
└── upload/
    └── plots/
        ├── KO_Treated_24h_umap.png
        ├── KO_Treated_48h_umap.png
        └── WT_Control_umap.png

Project Metadata

Save this as project.json:

{
  "project_name": "单细胞 RNA-seq 分析报告",
  "project_id": "PRJ-2026-001",
  "analysis_date": "2026-06-05",
  "species": "Human (GRCh38)",
  "reference": "refdata-gex-GRCh38-2024-A",
  "samples": [
    {
      "name": "WT_Control",
      "fastq_dir": "/data/fastq/WT_Control",
      "note": "野生型对照组"
    },
    {
      "name": "KO_Treated_24h",
      "fastq_dir": "/data/fastq/KO_Treated_24h",
      "note": "敲除处理 24 小时"
    },
    {
      "name": "KO_Treated_48h",
      "fastq_dir": "/data/fastq/KO_Treated_48h",
      "note": "敲除处理 48 小时"
    }
  ]
}

RST Template

Save this as report.rst.j2:

.. container:: report-header

   .. image:: assets/seqyuan-logo.png
      :width: 140px
      :alt: SeqYuan Logo

   项目编号 {{ project_id }}  ·  分析日期 {{ analysis_date }}

{{ project_name }}
========================

项目信息
--------

:物种: {{ species }}
:参考基因组: {{ reference }}
:样本数: {{ samples|length }}

样本信息
--------

.. list-table::
   :header-rows: 1
   :widths: 10 20 35 35

   * - 编号
     - 样本名称
     - FASTQ 目录
     - 备注
{% for sample in samples %}
   * - {{ loop.index }}
     - {{ sample.name }}
     - {{ sample.fastq_dir }}
     - {{ sample.note }}
{% endfor %}

UMAP 图集
---------

{% for plot in plots %}
**{{ plot.stem }}**

.. image:: {{ plot.path }}
   :width: 600px
   :alt: {{ plot.stem }}

{% endfor %}

结论与建议
----------

1. 项目级信息来自 `project.json`
2. UMAP 图由 `--scan` 自动发现
3. 模板中不需要硬编码 `upload/plots/WT_Control_umap.png` 这类路径

Render It

rst-render report.rst.j2 \
  -t \
  -d project.json \
  --scan plots=upload/plots/*_umap.png \
  --expand-includes \
  -v analysis_date=2026-06-06 \
  -o report.html \
  -s

-v/--var values override the same keys from project.json, which is useful for build dates, environment tags, or pipeline version numbers.

Scan Context

--scan plots=upload/plots/*_umap.png injects an array named plots into the template context. The same data is also available at scans.plots.

Each matched file has this shape:

[
  {
    path: 'upload/plots/WT_Control_umap.png',
    absPath: '/abs/path/to/report/upload/plots/WT_Control_umap.png',
    name: 'WT_Control_umap.png',
    stem: 'WT_Control_umap',
    ext: '.png',
    dir: 'upload/plots',
    size: 182734,
  },
]

This makes project-level report generation work the same way many bioinformatics pipelines do it: template + external variables + wildcard scans, instead of hardcoding every output file path into input.rst.

Optional Include Expansion

If you split reusable report fragments into multiple files, enable include expansion:

.. include:: shared/qc-summary.rst

CLI example:

rst-render report.rst.j2 -t -d project.json --expand-includes -o report.html

This is a lightweight pre-processing step for report reuse. It is not intended to reproduce full Sphinx include behavior.

Adding Your Company Logo

The RST .. image:: directive handles logos natively. Place your logo file alongside the RST source and reference it by relative path:

.. image:: assets/my-company-logo.png
   :width: 160px
   :alt: Company Logo

Architecture notes:

The builtin parser and rst-compiler adapter both support .. image::
Images are referenced by path; they are not embedded in the HTML by default
Use relative paths that work in your deployment context
For standalone HTML (see below), images can be base64-inlined

Standalone HTML (Self-Contained File)

Use --standalone (or -s) to produce a single HTML file with all CSS, images, and scripts inlined. Perfect for sending reports to clients.

# Generate + bundle in one command
rst-render report.rst -o report.html --standalone

# Template with project data + wildcard scans
rst-render report.rst.j2 -t -d project.json --scan plots=upload/plots/*_umap.png --expand-includes -o report.html -s

What it does:

<link rel="stylesheet"> → <style> with inline CSS
<img src="logo.png"> → <img src="data:image/png;base64,...">
<script src="app.js"> → <script> with inline JS

Remote URLs (http/https) and already-inlined data URIs are left untouched.

# Before: report.html (references logo.png + styles.css)
# After: report.html (single file, no external deps)
#
#   Size increase depends on image sizes.
#   SVG logos add negligible overhead.

CLI Tool

On this page