Citesmith brings easy Citations and Bibliographies to your MDX content as a remark plugin. Use the inline Cite component, optionally along with a CSL JSON file from your preferred reference manager to add inline references with a full bibliography at the end of your content.

Installation

Install Citesmith and its React peer dependency:

pnpm add @quackdev/citesmith react

Use the equivalent command for your package manager if you are not using pnpm:

npm install @quackdev/citesmith react
yarn add @quackdev/citesmith react

Usage

Add both remarkCite and recmaCite to your MDX pipeline. remarkCite collects <Cite> components from your MDX content and compiles the citation data. recmaCite embeds that data into the compiled MDX module, wraps the page content in the citation provider, and appends the bibliography.

import { recmaCite, remarkCite } from '@quackdev/citesmith'

const mdxOptions = {
  remarkPlugins: [
    [remarkCite, {
      defaultCitationStyle: 'ieee',
      defaultNumberingMode: 'source',
      globalCSLFile: './styles/site.csl',
      hoverPopup: true,
      referencesFileMode: 'default',
    }],
  ],
  recmaPlugins: [
    recmaCite,
  ],
}

globalCSLFile accepts an absolute path or a path relative to the project working directory. Its CSL style is used with defaultCitationStyle unless a document explicitly sets citations.style in frontmatter.

referencesFileMode controls where frontmatter-provided CSL JSON files may be loaded from:

• default allows canonical paths inside projectRoot (which defaults to the current working directory) or an explicitly configured referencesFileRoots directory.
• strict requires the JSON file and MDX document to have the same canonical directory.
• loose permits any filesystem location. Regular-file and size checks still apply, so this mode should only be enabled for trusted content.

Reference files are limited to 10 MiB by default. Use referencesFileMaxBytes to change the limit. Symlinks are checked using their real destinations, so a symlink outside an allowed root is rejected unless its destination is explicitly included in referencesFileRoots or loose mode is enabled.

The bundled citation styles are apa, chicago, harvard, ieee, mla, vancouver, and wiki.

Frontmatter

Per-document settings live under a citations frontmatter block:

---
citations:
  style: apa
  numberingMode: source
  popupEnabled: true
  referencesFile: ./references.json
  popupSettings:
    showSectionTitles: true
    dateOrder: DMY
    dateSeparator: /
    dateRangeSeparator: " to "
    dateCircaPrefix: "c. "
---

numberingMode can be source to reuse the same number for repeated citations of the same source, or occurrence to number every citation occurrence.

Inline Citations

You can provide citation metadata directly on the <Cite> element:

According to earlier work <Cite
  id="lovelace-notes"
  type="book"
  title="Notes on the Analytical Engine"
  author={{ given: "Ada", family: "Lovelace" }}
  issued={1843}
  page="42"
  citationNote="This note appears in the citation preview."
  showNote
/>.

CSL JSON References

For larger documents, export a CSL JSON file from your reference manager and point citations.referencesFile at it. Then cite items by ID:

[
  {
    "id": "lovelace-1843",
    "type": "book",
    "title": "Notes on the Analytical Engine",
    "author": [
      {
        "given": "Ada",
        "family": "Lovelace"
      }
    ],
    "issued": {
      "date-parts": [[1843]]
    }
  }
]

---
citations:
  style: ieee
  referencesFile: ./references.json
---

The idea appears in the notes <Cite id="lovelace-1843" page="42" />.

Components

When remarkCite and recmaCite are both enabled, you normally only need to write <Cite> in MDX. Citesmith automatically provides citation context and renders a bibliography.

If you need to import runtime components directly in client code, use the client entrypoint:

import { Bibliography, CitationProvider, Cite } from '@quackdev/citesmith/client'

Manual usage requires compiled citation data, so the automatic MDX plugin flow is the recommended integration path.

Section and row titles accept any React node, so applications can supply icons without Citesmith depending on an icon library. Wrap compiled MDX at runtime to use React nodes; build-time plugin options and YAML frontmatter remain string-only because they are serialized into the compiled module.

import { CitationPreviewProvider } from '@quackdev/citesmith/client'

import type { ReactNode } from 'react'

function ArticleWithPreviewIcons({ children }: { children: ReactNode }) {
  return (
    <CitationPreviewProvider
      settings={{
        sections: [
          {
            title: (
              <>
                <MetadataIcon aria-hidden />
                Metadata
              </>
            ),
            rows: [
              {
                title: (
                  <>
                    <CalendarIcon aria-hidden />
                    Date
                  </>
                ),
                type: 'issued',
              },
            ],
          },
        ],
      }}
    >
      {children}
    </CitationPreviewProvider>
  )
}

MetadataIcon and CalendarIcon above are application-provided components and can come from any icon library or custom SVG implementation.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before opening a merge request.

Security

If you discover a security vulnerability, please follow the process outlined in SECURITY.md.

License

Citesmith is licensed under the MIT License.

Citesmith uses citeproc, which declares its license as AGPL 1.0 or CPAL 1.0. Users are responsible for ensuring their own compliance with the citeproc license.

Copyright (C) 2026 Quack Development