{"id":31796894,"url":"https://github.com/bcdavasconcelos/citetools","last_synced_at":"2025-10-10T20:53:43.317Z","repository":{"id":147935009,"uuid":"615619811","full_name":"bcdavasconcelos/citetools","owner":"bcdavasconcelos","description":"📚 This extension introduces advanced bibliography features to Pandoc and Quarto's Citeproc environment. It bundles several Lua filters to address complex bibliography demands while keeping the output consistent across all formats (`LaTeX`, `DOCX`, `HTML`, and so on).","archived":false,"fork":false,"pushed_at":"2023-12-21T21:51:00.000Z","size":15738,"stargazers_count":14,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2023-12-21T22:35:41.061Z","etag":null,"topics":["bibliography","bibtex","citeproc","csl-json","pandoc-filters","quarto-filter"],"latest_commit_sha":null,"homepage":"https://bcdavasconcelos.github.io/citetools/docs_qmd/03-cite-field.html","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bcdavasconcelos.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-03-18T07:06:35.000Z","updated_at":"2023-11-18T09:25:50.000Z","dependencies_parsed_at":"2023-12-21T22:33:57.816Z","dependency_job_id":"3ec1ef11-5403-4972-bceb-e6f1ac84f526","html_url":"https://github.com/bcdavasconcelos/citetools","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"purl":"pkg:github/bcdavasconcelos/citetools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcdavasconcelos%2Fcitetools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcdavasconcelos%2Fcitetools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcdavasconcelos%2Fcitetools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcdavasconcelos%2Fcitetools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bcdavasconcelos","download_url":"https://codeload.github.com/bcdavasconcelos/citetools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcdavasconcelos%2Fcitetools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005255,"owners_count":26083864,"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","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","citeproc","csl-json","pandoc-filters","quarto-filter"],"created_at":"2025-10-10T20:53:06.674Z","updated_at":"2025-10-10T20:53:43.309Z","avatar_url":"https://github.com/bcdavasconcelos.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📚 Cite Tools for Pandoc and Quarto\n\n\n\u003c!-- TODO: BUG. Conversion fails upon citing field of reference absent from the bibliography --\u003e\n\n\n\u003cdiv id=\"top\"\u003e\u003c/div\u003e\n\n[![Render and Publish](https://github.com/bcdavasconcelos/citetools/actions/workflows/quarto-publish.yml/badge.svg)](https://github.com/bcdavasconcelos/citetools/actions/workflows/quarto-publish.yml)\n\n\u003c!-- [![GitHub build status][CI badge]][CI workflow] --\u003e\n\nThis extension introduces advanced bibliography features to Pandoc and Quarto's Citeproc environment. It bundles several Lua filters ([*vide infra*](#license)) to address complex bibliography demands while keeping the output consistent across all formats (`LaTeX`, `DOCX`, `HTML`, and so on).\n\n## Features\n\n\nMore specifically, this bunddle seeks to address in the simplest of ways possible the following demands:\n\n**1. Multiple bibliographies**\n\nThe need for multiple bibliographies (or bibliographies with multiple sections, such as `primary sources` and `secondary sources`).\n\n![](img/2023-03-18-22-02-26.png)\n\n**2. Cite fields**\n\nThe need to evoke arbitrary information from the references, such as `author`, `editor`, or `translator` names and `title` / `original-title` of works.\n\n![](img/2023-03-18-22-24-10.png)\n\n\u003cdetails\u003e\n  \u003csummary\u003e`@AristOp` in `csljson`\u003c/summary\u003e\n\n```json\n{\n    \"author\": [\n      {\n        \"family\": \"Aristotle\"\n      }\n    ],\n    \"editor\": [\n      {\n        \"family\": \"Bekker\",\n        \"given\": \"Immanuel\"\n      }\n    ],\n    \"id\": \"AristOp\",\n    \"issued\": {\n      \"date-parts\": [\n        [\n          1831\n        ]\n      ]\n    },\n    \"number-of-volumes\": \"4\",\n    \"publisher\": \"Reimer\",\n    \"publisher-place\": \"Berlim\",\n    \"title\": \"Aristotelis opera\",\n    \"type\": \"book\"\n  }\n```\n\n\u003c/details\u003e\n\n**3. Citation backlinks**\n\nThe need to turn the bibliography into a linked index of cited references, with links from the entries back to each of its multiple occurences in the body of the text (*e.g.* in `PDF`/`DOCX`: `[p. 1, p. 4, p. 10]`, in `HTML`: `[1, 2, 3]`) (and with the ability to turn these off globally or in an *ad hoc* fashion).\n\n![](img/2023-03-18-22-32-06.png)\n\n- *Optionally*, the need to split the bibliography into sections, printing the bibliography for each chapter/section/part. (For this, you must uncomment the apropriate line in the `_extension.yaml` file.)\n\n## Install\n\nUsers of Quarto can install this extension with the following command\n\n```bash\nquarto install extension bcdavasconcelos/citetools\n```\n\nand use it by adding `citetools` to the `filters` entry in their YAML header.\n\n``` yaml\n---\nfilters:\n  - citetools\n---\n```\n\n## Configuration\n\n### Multiple bibliographies\n\nAdd bibliography files to the `refs` folder. Then, add the following metadata to the YAML header of your document in this way:\n\n```yaml\n---\nbibliography_primary: refs/primary.json\nbibliography_secondary: refs/secondary.json\n---\n```\n\nThen, place the bibliographies placeholders in the document where you want the bibliographies to appear.\n\n``` markdown\n# Primary Sources\n\n::: {#refs_primary}\n:::\n\n# Secondary Sources\n\n::: {#refs_secondary}\n:::\n```\n\nThese divs are filled with citations from the respective bib-file. Each refs-*x* div should have a matching entry *x* in the metadata.\n\n**Make sure the bibliography name and the placeholder div id match.**\n\nThat is, if you have a bibliography named `bibliography_primary`, the placeholder div should be `refs-primary` or `refs_primary`.\n\n### Cite fields and citation backlinks global options\n\n- `link-fields` (boolean): Link inlines printed by `citefield` to their corresponding entry in the bibliography. Default: `true`.\n- `link-citations` (boolean): Link citations to their respective reference in the bibliography. Default: `true`. Note: if `link-citations` is set to `false`, `link-fields` is also set to `false`.\n\n---\n\nSee sample document `sample.qmd` for a working example with explanations.\n\n\n\u003cimg width=\"665\" alt=\"image\" src=\"https://user-images.githubusercontent.com/35749099/226091195-7b27f8a7-c802-4cbb-bac9-81265b7aed45.png\"\u003e\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcdavasconcelos%2Fcitetools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbcdavasconcelos%2Fcitetools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcdavasconcelos%2Fcitetools/lists"}