{"id":19957040,"url":"https://github.com/h-tex/eleventy-plugin-citations","last_synced_at":"2025-10-18T04:14:36.462Z","repository":{"id":246901376,"uuid":"824692280","full_name":"h-tex/eleventy-plugin-citations","owner":"h-tex","description":"Citations \u0026 bibliographies for Markdown \u0026 HTML, done well.","archived":false,"fork":false,"pushed_at":"2025-04-23T18:58:43.000Z","size":446,"stargazers_count":7,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-03T00:10:34.344Z","etag":null,"topics":["bibliography","bibtex","citations","citeproc"],"latest_commit_sha":null,"homepage":"https://eleventy-plugin-citations.verou.me/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/h-tex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-07-05T17:47:24.000Z","updated_at":"2025-06-08T06:20:06.000Z","dependencies_parsed_at":"2024-07-19T04:41:22.329Z","dependency_job_id":"3aed4e97-e177-4608-9323-2428ba46c85c","html_url":"https://github.com/h-tex/eleventy-plugin-citations","commit_stats":null,"previous_names":["leaverou/eleventy-plugin-citations","h-tex/eleventy-plugin-citations"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/h-tex/eleventy-plugin-citations","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h-tex%2Feleventy-plugin-citations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h-tex%2Feleventy-plugin-citations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h-tex%2Feleventy-plugin-citations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h-tex%2Feleventy-plugin-citations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/h-tex","download_url":"https://codeload.github.com/h-tex/eleventy-plugin-citations/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h-tex%2Feleventy-plugin-citations/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263366673,"owners_count":23455793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bibliography","bibtex","citations","citeproc"],"created_at":"2024-11-13T01:36:25.023Z","updated_at":"2025-10-18T04:14:36.379Z","avatar_url":"https://github.com/h-tex.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# eleventy-plugin-citations\n\nThis plugin parses Pandoc-style citations (`[@id1; @id2]`) in any input files and replaces them with formatted references.\nIt also stores the references in data that can be used to display a bibliography however and wherever you want.\n\nDemo: [code](https://github.com/LeaVerou/eleventy-plugin-citations/tree/main/demo) • [HTML page](https://eleventy-plugin-citations.verou.me/)\n\n## Contents \u003c!-- omit from toc --\u003e\n\n1. [Why another plugin?](#why-another-plugin)\n\t1. [Feature: Bibliography based on what is actually used in the output file, not how you structure your input files](#feature-bibliography-based-on-what-is-actually-used-in-the-output-file-not-how-you-structure-your-input-files)\n\t2. [Feature: Full templating customization](#feature-full-templating-customization)\n\t3. [Feature: Multiple citation sequences that can be linked up correctly](#feature-multiple-citation-sequences-that-can-be-linked-up-correctly)\n\t4. [Feature: Linkbacks from bibliography reference to citations in the text](#feature-linkbacks-from-bibliography-reference-to-citations-in-the-text)\n2. [Installation](#installation)\n3. [Usage](#usage)\n\t1. [Linking to bibliography files](#linking-to-bibliography-files)\n\t2. [Rendering citations in the text](#rendering-citations-in-the-text)\n\t3. [Rendering the bibliography](#rendering-the-bibliography)\n4. [Citation syntax](#citation-syntax)\n5. [Confuguration Options](#confuguration-options)\n6. [CSL Styles and Locales](#csl-styles-and-locales)\n\t1. [Styles](#styles)\n\t2. [Locales](#locales)\n7. [Limitations \\\u0026 Known issues](#limitations--known-issues)\n\t1. [11ty watch mode](#11ty-watch-mode)\n\t2. [Citation syntax](#citation-syntax-1)\n\t3. [No support for 11ty \\\u003c= 2](#no-support-for-11ty--2)\n\t4. [Relative paths are resolved relative to the project root](#relative-paths-are-resolved-relative-to-the-project-root)\n\t5. [Bibliography cannot come before the last citation](#bibliography-cannot-come-before-the-last-citation)\n\t6. [Low priority things](#low-priority-things)\n\n## Why another plugin?\n\nI developed this plugin over the course of writing my PhD thesis, while being on a pretty tight schedule.\nTrust me, I really did not want to write yet another plugin for this unless I absolutely had to.\nHowever, after carefully reviewing all the other plugins I could find, I decided that none of them were suitable for my needs.\nYour needs may be different, so I suggest you check them out too:\n\n| Package | Repo | Citation parser | Bbliography parser | Reference formatter |\n| ------- | ---- | --------------- | ------------- | ------------- |\n[eleventy-plugin-citations](https://www.npmjs.com/package/eleventy-plugin-citations) (this plugin) | [leaverou/eleventy-plugin-citations](https://github.com/leaverou/eleventy-plugin-citations) | [_(Custom)_](https://github.com/LeaVerou/eleventy-plugin-citations/blob/main/src/citations.js) | [biblatex-csl-converter](https://www.npmjs.com/package/biblatex-csl-converter) | [citeproc](https://www.npmjs.com/package/citeproc) + [Custom](https://github.com/LeaVerou/eleventy-plugin-citations/blob/main/src/Bibliography.js) + Your template! |\n[@arothuis/markdown-it-biblatex](https://www.npmjs.com/package/@arothuis/markdown-it-biblatex)\t| [arothuis/markdown-it-biblatex](https://github.com/arothuis/markdown-it-biblatex)\t\t| [_(Custom)_](https://github.com/arothuis/markdown-it-biblatex/blob/main/src/parser.js) | [biblatex-csl-converter](https://www.npmjs.com/package/biblatex-csl-converter) | [citeproc](https://www.npmjs.com/package/citeproc) |\n[eleventy-plugin-citeproc](https://www.npmjs.com/package/eleventy-plugin-citeproc)\t\t\t\t| [Myllaume/eleventy-plugin-citeproc](https://github.com/Myllaume/eleventy-plugin-citeproc)\t| [@zettlr/citr](https://www.npmjs.com/package/@zettlr/citr) | N/A _(Only supports JSON)_ | [citeproc](https://www.npmjs.com/package/citeproc) |\n[eleventy-plugin-bibtex](https://www.npmjs.com/package/eleventy-plugin-bibtex)\t\t\t\t\t| [Savjee/eleventy-plugin-bibtex](https://github.com/Savjee/eleventy-plugin-bibtex)\t\t| N/A _(No citation support)_ | [citation-js](https://www.npmjs.com/package/citation-js) | [citation-js](https://www.npmjs.com/package/citation-js) |\n[markdown-it-bibliography](https://www.npmjs.com/package/markdown-it-bibliography)\t\t\t\t| [DerDrodt/markdown-it-bibliography](https://github.com/DerDrodt/markdown-it-bibliography)\t| [_(Custom)_](https://github.com/DerDrodt/markdown-it-bibliography/blob/main/src/citation-parser.ts) | [biblatex-csl-converter-ts](https://www.npmjs.com/package/biblatex-csl-converter-ts) | [citeproc](https://www.npmjs.com/package/citeproc) |\n[markdown-it-cite](https://www.npmjs.com/package/markdown-it-cite) \t\t\t\t\t\t\t\t| [studyathome-internationally/markdown-it-plugins](https://github.com/studyathome-internationally/markdown-it-plugins/tree/main/packages/markdown-it-cite) | [_(Custom)_](https://github.com/studyathome-internationally/markdown-it-plugins/blob/main/packages/markdown-it-cite/index.js#L29) | [biblatex-csl-converter](https://www.npmjs.com/package/biblatex-csl-converter) | [_(Custom)_](https://github.com/studyathome-internationally/markdown-it-plugins/blob/main/packages/markdown-it-cite/index.js#L305) |\n\n### Feature: Bibliography based on what is actually used in the output file, not how you structure your input files\n\nI wanted to be able to break content down into multiple pages and templates and still have a single bibliography at the end.\nI.e. a single bibliography for the whole thesis, and a separate, different one for each standalone chapter.\nMost plugins were extending `markdown-it`, and thus were unaware of the broader context they were being used in, so they had to be atomic: all citations had to be in the same Markdown file.\nNow, you could probably do some weird gymnastics to compile a Markdown file with all your content that you then feed back into eleventy\n(thanks [@DmitrySharabin](https://github.com/DmitrySharabin) for the idea!), but that sounded quite contorted.\n\nThe way this plugin works, collected references are keyed by `page.url` so you can have separate bibliographies\nfor separate files, based on what is actually used on each file.\nThis also means you can call it as many times as you want on the same content and it will not distort the output.\n\n### Feature: Full templating customization\n\nMost plugins were generating the HTML for the citations and references in JS, providing varying levels of customization.\nI wanted to have the references as part of the data cascade and use actual templates for displaying them which provides unparalleled flexibility.\n\n### Feature: Multiple citation sequences that can be linked up correctly\n\nA lot of my content was Markdown converted from LaTeX with [pandoc](https://pandoc.org/).\nI had several citation sequences (e.g. `[@foo; @bar]`), which many plugins did not support or had limited support (e.g. only the first was linked).\n\nThis is due to how [citeproc](https://www.npmjs.com/package/citeproc) works that is at the core of all but one of them:\nit returns a single string with all the citations in it and no metadata about what is what.\nThis plugin does [**a lot of work**](https://github.com/LeaVerou/eleventy-plugin-citations/blob/main/src/Bibliography.js#L111-L128) to reverse engineer citeproc’s output to figure this out.\nYes, even sequence ranges (e.g. `[1, 3–5, 18, 34–60]`) are correctly linked up!\n\n### Feature: Linkbacks from bibliography reference to citations in the text\n\nYou can set up your template so that not only citations link to their bibliography entries, but bibliography entries link back to citations!\n\n## Installation\n\nFirst, install with npm:\n\n```sh\nnpm install eleventy-plugin-citations --save-dev\n```\n\nThen add it to your `.eleventy.js` config file:\n\n```js\nimport citations from 'eleventy-plugin-citations';\n```\n\nThen in your config function:\n\n```js\neleventyConfig.addPlugin(citations);\n```\n\nYou can also provide options (described below) to customize the plugin behavior, e.g.:\n\n```js\neleventyConfig.addPlugin(citations, {\n\tcitationTemplate: \"_includes/partials/_citations.njk\",\n\tbibliography: \"references.bib\",\n\tstyle: \"acm-sigchi.csl\",\n});\n```\n\n## Usage\n\n### Linking to bibliography files\n\nYou either use the `bibliography` plugin config option or `bibliography` as a data key\n(which could be global data, directory data, or even page data, you know the drill).\n\nE.g. you can have a `bibliography.json` global data file like this:\n\n```json\n[\n\t\"references.bib\",\n\t\"references2.bib\"\n]\n```\n\nor you can specify it in your frontmatter like this:\n\n```yaml\nbibliography: [references.bib, references2.bib]\n```\n\nSpecifying values lower down the hierarchy does not override values higher up, the result is merged, i.e. uses *all* specified bib files.\nStrings are also supported, but are not recommended as they override their ancestor values.\nArrays are also compatible with [Pandoc Citer](https://marketplace.visualstudio.com/items?itemName=notZaki.pandocciter)\nthough keep in mind that [relative links are resolved differently](#relative-paths-are-resolved-relative-to-the-project-root).\n\n### Rendering citations in the text\n\nThe plugin adds the following:\n- A `citations` filter\n- A `citations` paired shortcode\n\nYou use whichever of the two is convenient to pick up \u0026 format citations in your content.\nSee below for the [citation syntax](#citation-syntax).\n\nThese do double duty: they pick up references for bibliography, and they format the citations in the text.\n**this means that only text that has gone through one of the two will be collected for the bibliography.**\nFor the filter, you need to also add `| safe` after it so that the HTML it returns can be rendered.\n\n```njk\n{{ \"See [@doe99; @smith2000]\" | citations | safe }}\n```\n\nYou can provide your own template for rendering the citation via the `citationTemplate` option,\nor a function that takes the citation info and returns the text of the formatted citation via the `citationRender` option.\n\nBy default, the plugin will use [its internal citation template](_includes/_citations.njk) for this, which looks like this:\n\n```njk\n\u003cspan class=\"citations\" id=\"citation-{{ uuid }}\"\u003e\n\t{%- for part in parts -%}\n\t\t{%- if part.citation -%}\n\t\t\t\u003ca href=\"#bib-{{ part.citation.id }}\" class=\"reference\" id=\"ref-bib-{{ part.citation.id }}-{{ uuid }}\"\u003e{{ part.text }}\u003c/a\u003e\n\t\t{%- else -%}\n\t\t\t{{ part | safe }}\n\t\t{%- endif -%}\n\t{%- endfor -%}\n\u003c/span\u003e\n```\n\n### Rendering the bibliography\n\nThe plugin adds the following:\n- A `references` computed data property that resolves to the page’s own references\n- A `referencesByPage` global data object that contains references for all pages. You can get another page’s references by using `referencesByPage.get(otherPage)` or `referencesByPage.get(otherPageURL)`.\n- A `bibliography_citation` filter that takes an id as input and returns a formatted citation for use in the bibliography.\n- A `bibliography_entry` filter that takes an id as input and returns a formatted reference for use in the bibliography.\nIt can optionally take an options parameter.\nCurrently the only option is `doi_link` which will linkify any DOI links\n(use value `\"id\"` for the link text to be the id, `\"url\"` to just linkify the URL, or provide your own template).\n\nYou can use these however you want to generate the bibliography or just use the demo [`_references.njk`](demo/_includes/_references.njk) if you’re looking for something quick.\n\nThis is an example of a very bare-bones bibliography,\nsimilar to what LaTeX would generate:\n\n```njk\n\u003ch2\u003eBibliography\u003c/h2\u003e\n\n\u003cdl class=\"references\"\u003e\n\t{% for reference in references %}\n\t\t\u003cdt\u003e\u003ca href=\"#bib-{{ reference.id }}\" class=\"reference\" id=\"bib-{{ reference.id }}\"\u003e{{ reference | bibliography_citation }}\u003c/a\u003e\u003c/dt\u003e\n\t\t\u003cdd\u003e{{ reference | bibliography_entry | safe }}\u003c/dd\u003e\n\t{% endfor %}\n\u003c/dl\u003e\n```\n\nYou can check out the [demo reference template](demo/_includes/_references.njk) (and [its CSS](demo/assets/css/bib.css)) for a more complex example\nincluding backlinks, highlighting of missing entries, nicer DOI links, and more.\n\n## Citation syntax\n\nThe citation syntax supported is a subset of the [Pandoc citation syntax](https://pandoc.org/chunkedhtml-demo/8.20-citation-syntax.html).\nBasically ids only, without any locator information.\nWe also parse the same citation flags from [`markdown-it-biblatex`](https://github.com/arothuis/markdown-it-biblatex#different-citation-modes) but don’t yet do anything with them.\n\n| Example | Description | Parsed? | Supported? |\n| ------- | ----------- | ------- | ---------- |\n| `[@doe99]` | Single citation | ✅ | ✅ |\n| `[@doe99; @smith2000]` | Multiple citations separated by semicolons | ✅ | ✅ |\n| `[-@doe99]` | Suppress author | ✅ | 🚫 |\n| `[!@doe99]` | Author-only | ✅ | 🚫 |\n| `[~@doe99]` | Inline | ✅ | 🚫 |\n| `@doe99` | Citation without brackets | 🚫 | 🚫 |\n| `[@{https://example.com/bib?name=foobar\u0026date=2000}, p.  33]` | URLs as keys | 🚫 | 🚫 |\n| `[see @doe99]` | Prefix | 🚫 | 🚫 |\n| `[@doe99, and *passim*]` | Suffix | 🚫 | 🚫 |\n\n## Confuguration Options\n\n| Name | Type | Default | Description |\n| ---- | ---- | ------- | ----------- |\n| `citationTemplate` | `string` | - | The path to the Nunjucks template that will be used to format the citations. |\n| `citationRender` | `function` | _(See prose)_ | A function that takes info about a citation sequence and returns an HTML string |\n| `style` | `string` or `object` | [`style-vancouver`](https://www.npmjs.com/package/style-vancouver) | The CSL style to use for formatting the references, either as an object or a path to a CSL XML file. |\n| `locale` | `string` or `object` | [`locale-en-us`](https://www.npmjs.com/package/locale-en-us) | The locale to use for formatting the references, either as an object or a path to a locale CSL XML file. |\n| `bibliography` | `string` or `string[]` | - | One or more global BiBTeX files. In case of duplicate keys, later wins. These will be merged with any BiBTeX files provided via the data cascade and will have lower priority. |\n\n## CSL Styles and Locales\n\n[CSL](https://citationstyles.org/) is an XML-based standard to describe citation styles.\nSeveral popular locales and styles are available as NPM packages.\n\n### Styles\n\nThis plugin has been tested and verified to work with the most popular styles, and a few others.\n\n| Style | Tested? | Text citation | Bibliography citation |\n| ----- | ------- | ------------- | --------------------- |\n| [Vancouver](https://www.npmjs.com/package/style-vancouver) | ✅ (default) | (1) | 1. |\n| [Nature](https://www.npmjs.com/package/style-nature) | ✅ | \u003csup\u003e1\u003c/sup\u003e | [1] |\n| [APA](https://www.npmjs.com/package/style-apa) | ✅ | (Doe et al., 1999) | [doe99] |\n| [Chicago](https://www.npmjs.com/package/style-chicago) | ✅ | (Doe et al., 1999) | [doe99] |\n| [MLA](https://www.npmjs.com/package/style-mla) | ✅ | (Doe et al., 1999) | [doe99] |\n| [RSC](https://www.npmjs.com/package/style-rsc) | ✅ | \u003csup\u003e1\u003c/sup\u003e | 1 |\n\nNote: Nature, APA, and Chicago use the same overall citation style and appear to only differ in terms of how they format bibliography entries.\n\n### Locales\n\n| Locale | Tested? |\n| ------ | ------- |\n| [en-US](https://www.npmjs.com/package/locale-en-us) | ✅ (default) |\n| [en-GB](https://www.npmjs.com/package/locale-en-gb) | 🚫 |\n| [fr-FR](https://www.npmjs.com/package/locale-fr-fr) | 🚫 |\n| [de-DE](https://www.npmjs.com/package/locale-de-de) | 🚫 |\n| [es-ES](https://www.npmjs.com/package/locale-es-es) | 🚫 |\n\n## Limitations \u0026 Known issues\n\n### 11ty watch mode\n\nEditing bibliography files will not trigger a rebuild.\n\n### Citation syntax\n\nWhile you provide CSL files for the style, the plugin had to make certain assumptions to afford the templating flexibility it provides,\nsince citeproc provides chunks of text or HTML, with no granularity for the different parts of the citation.\n\nLocators are currently not supported in the citation syntax.\nThey are mostly parsed, but not output.\n\n### No support for 11ty \u003c= 2\n\nI _may_ be open in merging PRs to support Eleventy v2 if the changes are minimal,\nbut I’m not interested in making extensive changes to the codebase to cater to the past.\nJust migrate to 11ty 3, it’s the future!\n\n### Relative paths are resolved relative to the project root\n\nYes, it would be _much_ better if bibliography paths specified in a specific Markdown file resolved relative to that file,\nand is what [Pandoc Citer](https://marketplace.visualstudio.com/items?itemName=notZaki.pandocciter) expects too.\nHowever, given how the data cascade works in 11ty, this is not possible, as we don’t know where each entry is coming from so we can resolve it based on the file that defined it, and we definitely don’t want to be resolving global bibliography files relative to each file that uses them!\n\n### Bibliography cannot come before the last citation\n\nThe `citations` filter and `{% citations %}` shortcode do double duty: they format the citations AND collect them so they can print out references.\nThis means that when you print out `page.references`, you are only printing out references that have been collected by then.\n\n### Low priority things\n\nThere are certain things I did not need, and thus are deprioritized (see wrt tight deadline above):\n\n- No support for Liquid templates. The plugin imports Nunjucks directly.\nThat said, as long as your citation template is a Nunjucks template, you should probably be fine.\n- The citation template cannot use any of your other 11ty data or any custom filters etc.\nThis is because it imports Nunjucks directly and does not have access to the 11ty environment.\n\nHappy to merge PRs on these, I just don’t have the time to do them myself.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh-tex%2Feleventy-plugin-citations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fh-tex%2Feleventy-plugin-citations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh-tex%2Feleventy-plugin-citations/lists"}