Feuillets CSL

Feuillets CSL is the optional citation engine companion for Feuillets in Obsidian. It adds native Citation Style Language (CSL) processing while Feuillets remains responsible for the writing interface, Markdown/Pandoc parsing, project configuration, and bibliography and style resource resolution.

Requirements

• Obsidian 1.13.0 or later.
• Feuillets 3.4.0 or later, installed and enabled.
• Feuillets CSL enabled alongside Feuillets.

API v2 discovery is available in Feuillets 3.4.0 or later, but API discovery alone does not guarantee compatibility with every diagnostic. Full isolation of cited incompatible, duplicate or cyclic references requires a Feuillets release containing the recoverable-diagnostics fix (6ed59b6). The published 3.5.2 release does not contain that fix. Update Feuillets first, then the companion; no bibliography replacement is required. See the tested compatibility matrix. Check the Feuillets releases and Feuillets CSL releases for available downloads.

Feuillets CSL is optional: Feuillets remains usable without it. Install and enable both plugins to use native CSL rendering.

What it adds

• Author-date, numeric, and note-based citation styles.
• Stateful note citations, including subsequent citations and ibid. where defined by the CSL style.
• Bibliography generation with the style's formatting and ordering.
• Grouped citations, locators, prefixes, and suffixes.
• Structured citation modes supplied by Feuillets: normal, suppress-author, author-only, and composite (author in the sentence with the remaining citation following it).

Feuillets supplies Pandoc citekeys and uses the provider's results in Live Preview, Reading Mode, Continuous mode, paginated Preview, native PDF, DOCX, EPUB, ODT, and generated bibliographies where CSL rendering is selected and applicable. These writing surfaces and exports are provided by Feuillets.

Citation syntax

Write Pandoc citations normally:

[@smith2024]
[@smith2024, p. 42]
[@smith2024; @doe2023]
@smith2024

These examples show a citation, a page locator, a grouped citation, and a citation in the sentence. Feuillets parses the Markdown/Pandoc syntax. Feuillets CSL receives structured citation clusters, not raw manuscript Markdown.

Bibliography and CSL resources

Configure the bibliography and CSL style in Feuillets. There is no separate Feuillets CSL settings interface. Feuillets resolves the active workspace or project resources and passes their contents to the provider; Feuillets CSL does not scan the Vault for bibliography or style files.

The supported bibliography input is BibTeX/BibLaTeX content, processed through the bundled adapter. JSON bibliographies are not supported.

Citekeys must match bibliography entries exactly. An unknown, incompatible, ambiguous or cyclic reference leaves its entire citation cluster unresolved, with an error diagnostic identifying the cluster and key; other valid clusters still render with a compatible Feuillets host. Unused rejected entries produce library warnings. No item is invented, and a group containing a rejected key is never rendered partially. Genuine source, style or engine failures remain global failures.

Locales

The supported runtime locales are en-US and fr-FR. Both full locale files are bundled locally from the official CSL locale project. If Feuillets supplies no locale, the engine defaults to en-US.

An unsupported requested runtime locale fails closed rather than silently switching language. Runtime locales supply language terms and date conventions; this does not restrict CSL styles to English or French styles.

Local and private

Feuillets CSL processes the resources supplied by Feuillets locally. It requires no account and has no telemetry, citation-processing network service, runtime CSL locale download, or remote bibliography lookup.

Fail-closed behavior

When a citation cannot be safely processed, Feuillets preserves the raw citation syntax. This safety fallback avoids inventing a citation or silently substituting another reference or language.

Unknown and rejected keys affect only their whole cluster with a compatible host. Missing providers or resources, invalid CSL styles, inconsistent results and engine failures preserve raw syntax for the complete document. The engine excludes unresolved clusters from citeproc, retaining the original note indices and the ordered state of resolved citations. Position decisions within the same note use only resolved citations; the engine cannot infer an unknown work's bibliographic identity.

Installation

Community Plugins

After the plugin is published in the Obsidian Community directory, open Settings → Community plugins → Browse, search for Feuillets CSL, then install and enable it. Feuillets must also be installed and enabled.

Manual installation

1. Install and enable Feuillets 3.4.0 or later. For full bibliography error isolation, use a release containing the recoverable-diagnostics fix described in the compatibility matrix.
2. Download main.js and manifest.json from a Feuillets CSL GitHub release.
3. Create the folder .obsidian/plugins/feuillets-csl/ inside your Vault and place both files there.
4. Reload Obsidian and enable Feuillets CSL in Community plugins.

Usage

1. Install and enable Feuillets and Feuillets CSL.
2. Configure a bibliography and CSL style in Feuillets.
3. Write Pandoc citations normally.
4. Select CSL citation rendering in Feuillets where applicable.
5. Preview your manuscript or export it.

Troubleshooting

If citations remain raw, check that:

• Both plugins are enabled and Feuillets is 3.4.0 or later.
• For partial rendering around cited incompatible, duplicate or cyclic references, Feuillets also includes the recoverable-diagnostics fix. Published Feuillets 3.5.2 rejects those new errors and keeps the complete document raw. Update Feuillets before updating the companion.
• CSL citation rendering is selected for the relevant Feuillets surface or export.
• The active project has a bibliography and CSL style configured in Feuillets, and both files exist and are valid.
• Each citekey exists exactly once in the supplied bibliography, with matching spelling and case.
• The requested runtime locale is en-US or fr-FR.

Raw syntax is a safety fallback when resources, citekeys, or the provider are unavailable or incompatible. Feuillets CSL reconnects automatically when Feuillets becomes available or is reloaded.

Architecture

The companion connects through Feuillets citation provider API v2:

Feuillets
  → parses Markdown and resolves resources
  → CitationDocumentRequest
Feuillets CSL
  → citeproc processing
  → CitationDocumentResult / safe semantic AST
Feuillets
  → renders the result in each surface/export

See the engine contract for session, lifecycle, cache, and safe-output details.

Development

npm install
npm run typecheck
npm run build
npm test
npm run lint
npm run lint:obsidian
npm run audit:network

Engine testing tools

npm run probe:engine builds an isolated browser engine bundle in the ignored .engine-audit/ directory for dependency inspection and size reporting. npm run benchmark:engine measures bibliography adaptation, initial rendering, incremental appends, and rebuilds. The test and benchmark tooling requires a Node.js version with native TypeScript support and node:module.registerHooks support for the test loader.

CI and release checks also run Feuillets' mandatory npm run test:csl-integration against this checkout. Configure repository variable FEUILLETS_HOST_REF with a full, reviewed, remotely available Feuillets commit SHA containing the integration gate. A missing pin, host, browser, skipped integration test or failed assertion fails the check. Before releasing the companion, that pin must identify a publicly released Feuillets commit. See compatibility and integration.

License and third-party software

Feuillets CSL is licensed under AGPL-3.0-or-later. See THIRD_PARTY_NOTICES.md for third-party software and CSL locale attribution and licenses.