Reports

A report is one paper: one .rst source, one HTML page, one PDF. The left sidebar is that paper's sections (Introduction, Motivation, …). A book (this guide) is the other shape: many chapters, sidebar = chapter list, one combined PDF.

If every file in the manifest is a report, uscribe also writes a catalog index.html — a table of links. You can ignore it when you only have one report.

Mark a file as a report

Start the .rst with a field list. :docclass: report (or a :trnumber: ) selects report layout: masthead, abstract, keywords, article PDF, section sidebar.

:title: Report Mode Example
:author: Uscribe Maintainers
:trnumber: 0
:date: 2026-08-07
:abstract: Minimal fixture for UTR-style report metadata, external
   links, sub/sup, and raw passthrough.
:docclass: report

Introduction
============

Headings in the body become the sidebar TOC. Explicit labels ( .. _sec-intro: ) become #sec-intro jump targets.

One report

Put the paper in its own directory. Author, title, and abstract stay in the .rst field list (above). The manifest is one line. You do not need a per-report .conf .

my-paper/
  book.manifest      # one line: paper.rst
  paper.rst
  book.conf          # optional: themePath (same file books use)

book.manifest :

paper.rst

Build from that directory (defaults pick up book.manifest and, if present, book.conf ):

uscribe --targetDir=./out

Open paper.html . The sidebar is that paper's sections. index.html is a one-row catalog; you can ignore it.

Optional book.conf is only build settings (theme, logo, themePath ), not author or abstract. If you omit title there, the sidebar uses the paper's :title: .

This guide's live fixture lives next to the user-guide book.conf , so the Makefile passes --config=report-example.conf to avoid picking up the guide settings. The paper is ex-report.html (after make -C doc/uscribe ).

Output:

out/
  paper.html       ← the report (section nav)
  paper.pdf        ← if you passed --format=pdf
  index.html
  search.html
  _static/
  _sources/

Several reports and an index

Same layout, more files in the manifest. Each paper is still one HTML page. book.conf title is the series name on the catalog (and the link back from each paper's sidebar).

my-reports/
  book.manifest
  book.conf          # title: My Technical Reports
  paper-a.rst
  paper-a.bib
  paper-b.rst

book.manifest :

paper-a.rst
paper-b.rst

uscribe --targetDir=./out

Open index.html for the table (number, title, author, date, pdf/txt). Open a row to read that paper; its sidebar is that paper's sections. Each paper's :cite: numbers start at 1, and .. bibliography:: lists only that paper's cited works from its own .bib .

The Unicon Technical Reports tree is this pattern: doc/utr/utr.manifest and doc/utr/book.conf , via make -C doc/utr html .

Live fixtures in this guide (again using a separate --config because they share a directory with the user guide): catalog index , first report , second report . The manifests are report-example.manifest (one file) and reports-example.manifest (two files).

Book vs report (summary)

Piece	Book	Report
Source	many chapters	one .rst per paper
Sidebar	other chapters	sections of this paper
index.html	ordered chapter list	catalog table of papers
PDF	one file for the whole book	one file per paper
When	manuals, this user guide	UTR, a standalone paper

A mixed manifest (some reports, some book chapters) is unusual. Each report page still gets a section sidebar; book chapters keep the chapter list. Prefer an all-report manifest or an all-book manifest.

See Markup Reference for the field-list keys and Command Line for --format / --manifest .