2  Getting started

2.1 Install and activate the extension

You need Quarto 1.6 or later and Python 3.10 or later with pip available. For ordinary rendering, install Quarto-Needs as a Quarto extension:

quarto add lsbjordao/quarto-needs

A direct GitHub install is stored by Quarto under _extensions/lsbjordao/quarto-needs/. Installation alone does not activate the extension. Register the filter in _quarto.yml:

filters:
  - quarto-needs

Then render normally:

quarto render

The extension supplies its own pre-render step and provisions the matching Python engine into a project-local managed runtime. You do not need to add project.pre-render: quarto-needs scan or install the standalone CLI just to render.

The engine is installed as quarto-needs==<extension version> from the package index, into .quarto-needs/runtime/. When that index is unreachable — an air-gapped machine, or a version not published yet — QUARTO_NEEDS_ENGINE_SOURCE overrides where it comes from:

QUARTO_NEEDS_ENGINE_SOURCE=/path/to/quarto-needs quarto render

The value must be a local filesystem path to a checkout or a wheel. A remote URL is refused, and so is a path that does not exist; the override cannot be set from a project file. When provisioning fails, the render stops with an actionable message naming this variable rather than producing a partially rendered book.

For a new project, the starter template bundles and activates the extension:

quarto use template lsbjordao/quarto-needs/templates/starter

2.2 Minimal structure

A Quarto-Needs project is a Quarto project with the extension installed and an optional policy in .quarto-needs.toml.

my-project/
├── _quarto.yml
├── .quarto-needs.toml
├── index.qmd
├── requirements.qmd
└── architecture.qmd

2.3 Optional margin-sidebar toggle

For HTML books and websites that use Quarto’s right-hand page table of contents, Quarto-Needs can add a persistent collapse/expand control:

quarto-needs:
  margin-sidebar-toggle: true

The option is disabled by default. When enabled, the control targets Quarto’s #quarto-margin-sidebar, stores the reader’s preference in the browser, and expands the content layout while the margin sidebar is collapsed. On narrow viewports, Quarto’s own responsive layout remains authoritative.

This option is independent of the left navigation sidebar. For a Quarto Book, use Quarto’s native book.sidebar.collapse-level option to control how deeply the left navigation tree is expanded by default.

2.4 First object

::: {.need #REQ-001 type="system-requirement" status="approved" priority="high" tags="security"}
## Authenticate before issuing a session

The system shall authenticate the identity before issuing a session.

### Rationale

Prevents sessions from being created for unauthenticated requesters.
:::

Each block declares an object with an ID, type, status, attributes, body, and relations. The parser turns those declarations into a canonical snapshot before rendering.

2.5 Relations

::: {.need #REQ-002 type="functional-requirement" status="approved"}
derives-from: REQ-001
implemented-by: COMP-001
verified-by: TC-001

## Require a second factor
...
:::

Relations are typed. The catalog defines semantic family, direct/inverse labels, source/target roles, and impact-propagation direction.

2.6 Optional standalone CLI

The extension-managed runtime is enough for quarto render. Install the Python package separately only when you want command-line engineering workflows or editor tooling:

pip install quarto-needs

That installation provides:

quarto-needs scan
quarto-needs check
quarto-needs coverage
quarto-needs trace REQ-001
quarto-needs quality

scan materializes declarations, check applies validation and rules, coverage summarizes traceability, trace traverses the graph, and quality evaluates configured metrics and gates.

2.7 Multilingual manual

This manual uses babelquarto: unsuffixed files are the canonical English source and *.pt-BR.qmd contains the Brazilian Portuguese translation. IDs, relation keywords, and structured examples remain invariant across languages.