@uniweb/scholar
v1.1.3
Published
Academic content utilities for Uniweb - numbered equations with cross-references, bibliographic references, and inline citations
Readme
@uniweb/scholar
Academic content utilities for Uniweb: math rendering, bibliographic references, and inline citations.
Installation
npm install @uniweb/scholar
# or
pnpm add @uniweb/scholarFeatures
- Numbered Equations - Cross-referenceable display equations
- Bibliography - Format references in APA, MLA, Chicago, and IEEE styles
- Citations - Track inline citations with automatic bibliography generation
- BibTeX - Parse and export BibTeX format
- UI Components - Ready-to-use citation buttons, author lists, and DOI links
Plain LaTeX math (inline
$x$, display$$x$$, fenced```math) is handled by Uniweb's content pipeline — the markdown parser compiles LaTeX to MathML Core at build time and the browser renders it natively. No runtime math library needed; no<Math>component required.
Quick Start
Numbered Equations
import { Equation, EquationRef, EquationProvider } from '@uniweb/scholar/math'
<EquationProvider>
<Equation id="einstein">E = mc^2</Equation>
<p>As shown in <EquationRef id="einstein" />, energy equals mass times the speed of light squared.</p>
</EquationProvider>Citations and Bibliography
import { CitationProvider, Citation, Bibliography } from '@uniweb/scholar/citations'
const references = [
{
id: 'smith2024',
type: 'article',
authors: [{ family: 'Smith', given: 'John' }],
title: 'A Study of Something Important',
journal: 'Journal of Studies',
year: 2024,
volume: '10',
pages: '1-15',
doi: '10.1234/example'
}
]
<CitationProvider references={references} style="apa">
<p>
Recent research <Citation id="smith2024" /> has shown significant progress.
</p>
<p>
According to <Citation id="smith2024" format="narrative" />, the findings are clear.
</p>
<Bibliography title="References" />
</CitationProvider>BibTeX Support
import { CitationProvider, Citation, Bibliography } from '@uniweb/scholar/citations'
const bibtex = `
@article{smith2024,
author = {Smith, John and Doe, Jane},
title = {A Study of Something Important},
journal = {Journal of Studies},
year = {2024},
volume = {10},
pages = {1--15},
doi = {10.1234/example}
}
`
<CitationProvider references={bibtex} style="apa">
<p>Research shows <Citation id="smith2024" /> that...</p>
<Bibliography />
</CitationProvider>API Reference
Math Module
Scholar does not ship a math renderer. Plain LaTeX in markdown is compiled to MathML by Uniweb's content pipeline and rendered natively by the browser — see the framework docs for the $x$, $$x$$, and ```math fence syntax.
<Equation> and <EquationRef> cover the distinct feature of numbered cross-referenceable equations. They consume pre-compiled MathML from content.math and are fully SSR-safe.
Label an equation in markdown with a :<id> suffix on the fence:
```math:einstein
E = mc^2
```Then in a foundation's section component:
import { Equation, EquationProvider, EquationRef } from '@uniweb/scholar/math'
function MyBlock({ content }) {
return (
<EquationProvider>
{content.math?.filter(m => m.id).map(m => (
<Equation key={m.id} id={m.id} mathml={m.mathml} />
))}
<p>As shown in <EquationRef id="einstein" />, energy equals mc².</p>
</EquationProvider>
)
}<Equation>
Numbered display equation rendered from pre-compiled MathML.
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| id | string | auto | Identifier for cross-referencing |
| mathml | string | - | Pre-compiled MathML from content.math[i].mathml |
| label | string | - | Override the auto-number with a custom label |
| className | string | - | CSS classes on the wrapper |
<EquationRef>
Link to a numbered equation within the same <EquationProvider>.
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| id | string | - | ID of equation to reference |
| format | string | 'parentheses' | 'parentheses', 'plain', or 'equation' |
<EquationProvider>
Context provider for equation numbering. Wrap content containing equations and their references.
Citations Module
<CitationProvider>
Manages citation state for a document.
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| references | Array\|string | - | Reference objects or BibTeX string |
| style | string | 'apa' | Citation style |
| children | ReactNode | - | Document content |
<Citation>
Renders an inline citation.
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| id | string | - | Reference ID to cite |
| ids | string[] | - | Multiple reference IDs |
| page | string | - | Page number(s) |
| prefix | string | - | Text before citation |
| suffix | string | - | Text after citation |
| suppressAuthor | boolean | false | Show only year |
| format | string | 'parenthetical' | 'parenthetical', 'narrative', 'numeric' |
<Bibliography>
Renders the list of cited references.
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| title | string | 'References' | Section title |
| showTitle | boolean | true | Whether to show title |
| showAll | boolean | false | Show all refs, not just cited |
Bibliography Module
formatReference(publication, options)
Format a reference in a specific style.
import { formatReference } from '@uniweb/scholar/bibliography'
const ref = formatReference({
type: 'article',
authors: [{ family: 'Smith', given: 'John' }],
title: 'A Study',
journal: 'Journal',
year: 2024
}, { style: 'apa' })A style prints words of its own: "and", "et al.", "vol.", "pp.", month names, quotation marks.
They are English unless you pass a locale pack from
@citestyle/locales, one per CSL language:
import fr from '@citestyle/locales/fr-FR'
formatReference(pub, { style: 'mla', locale: fr })
// … « Bridging Human Expertise and AI ». …, vol. 12, nᵒ 8, mars 2023, p. 78‑89.A foundation carries every pack it imports, about 3–4 KB gzipped each, so import the languages
its sites use (npm install @citestyle/locales) and pick one by the page's language. A language
with no pack keeps the style's English words.
import { useWebsite } from '@uniweb/kit'
import fr from '@citestyle/locales/fr-FR'
import de from '@citestyle/locales/de-DE'
const PACKS = { fr, de }
function Reference({ pub }) {
const { website } = useWebsite()
const locale = PACKS[website.getActiveLocale()?.split('-')[0]]
return <p>{formatReference(pub, { style: 'apa', locale }).text}</p>
}parseBibtex(bibtex) / exportBibtex(publication)
Parse BibTeX to objects or export objects to BibTeX.
import { parseBibtex, exportBibtex } from '@uniweb/scholar/bibliography'
const refs = parseBibtex(bibtexString)
const bibtex = exportBibtex(publication)UI Components
<CiteButton>
Dropdown button to copy citations in various formats.
import { CiteButton } from '@uniweb/scholar/components'
<CiteButton
publication={pub}
styles={['apa', 'mla', 'bibtex']}
/>Its words are props, so a site in any language can give its own: label names the button
(Cite when not given), styleLabels names the menu's entries by style id (scholar's names, such
as APA (7th ed.), for any it leaves out), and copiedLabel is what an entry says once its citation
is copied (✓ and the entry's name when not given). Its colours are the theme's tokens, so it
follows the section it sits in.
<CiteButton
publication={pub}
styles={['apa', 'chicago', 'bibtex']}
label="Citer"
styleLabels={{ apa: 'APA (7e éd.)', chicago: 'Chicago (auteur-date)' }}
copiedLabel="Copié ✓"
locale={fr}
/>locale is a locale pack, as for formatReference, so the citations it copies read in the
page's language too.
<BibtexBlock>
Display copyable BibTeX entry.
import { BibtexBlock } from '@uniweb/scholar/components'
<BibtexBlock entry={publication} /><AuthorList>
Formatted author names with optional ORCID links.
import { AuthorList } from '@uniweb/scholar/components'
<AuthorList
authors={[
{ family: 'Smith', given: 'John', orcid: '0000-0001-2345-6789' }
]}
style="apa"
/><DoiLink>
DOI with automatic link.
import { DoiLink } from '@uniweb/scholar/components'
<DoiLink doi="10.1234/example" />Citation Styles
| Style | Description |
|-------|-------------|
| apa | APA 7th Edition |
| mla | MLA 9th Edition |
| chicago | Chicago Author-Date |
| ieee | IEEE (numeric) |
Reference Object Structure
{
id: 'smith2024', // Citation key
type: 'article', // article, book, inproceedings, etc.
authors: [ // Array of author objects
{ family: 'Smith', given: 'John', orcid: '...' }
],
title: 'Article Title',
journal: 'Journal Name', // For articles
bookTitle: 'Book Title', // For chapters
year: 2024,
volume: '10',
issue: '2',
pages: '1-15',
publisher: 'Publisher',
doi: '10.1234/example',
url: 'https://...',
abstract: '...',
keywords: ['keyword1', 'keyword2']
}Bundle Size
Scholar ships no math renderer — MathML is pre-compiled upstream and rendered natively by the browser. Approximate subpath sizes:
| Module | Size | |--------|------| | bibliography (formatters, parsers) | ~15KB | | math (numbered equations, refs) | ~5KB | | citations | ~10KB | | components | ~8KB |
License
Apache-2.0
