{"id":13646401,"url":"https://github.com/andras-simonyi/citeproc-org","last_synced_at":"2025-04-21T18:30:55.220Z","repository":{"id":110990140,"uuid":"114968722","full_name":"andras-simonyi/citeproc-org","owner":"andras-simonyi","description":"Renders Org-mode citations in CSL styles using citeproc-el.","archived":false,"fork":false,"pushed_at":"2022-07-17T10:20:17.000Z","size":86,"stargazers_count":68,"open_issues_count":3,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-09T19:41:40.704Z","etag":null,"topics":["bibliographies","bibtex","citation","citation-style-language","csl-style","emacs","org-ref","orgmode"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andras-simonyi.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-21T06:02:01.000Z","updated_at":"2024-05-30T19:58:54.000Z","dependencies_parsed_at":"2023-03-13T13:44:44.924Z","dependency_job_id":null,"html_url":"https://github.com/andras-simonyi/citeproc-org","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andras-simonyi%2Fciteproc-org","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andras-simonyi%2Fciteproc-org/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andras-simonyi%2Fciteproc-org/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andras-simonyi%2Fciteproc-org/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andras-simonyi","download_url":"https://codeload.github.com/andras-simonyi/citeproc-org/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250110812,"owners_count":21376540,"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":["bibliographies","bibtex","citation","citation-style-language","csl-style","emacs","org-ref","orgmode"],"created_at":"2024-08-02T01:02:54.700Z","updated_at":"2025-04-21T18:30:54.977Z","avatar_url":"https://github.com/andras-simonyi.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"readme":"# citeproc-org\n[![MELPA](http://melpa.org/packages/citeproc-org-badge.svg)](http://melpa.org/#/citeproc-org)\n[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\nRenders [Org mode](https://orgmode.org/) citations and bibliographies during\nexport in [Citation Style Language (CSL)](https://citationstyles.org/) styles\nusing the [citeproc-el](https://github.com/andras-simonyi/citeproc-el) library.\n\n\u003e :warning: **!! Important note, read this first (last updated on 2022-07-17) !!**\n\u003e As native support for citations including CSL-based export is now part of Org\n\u003e (see [the announcement](https://orgmode.org/list/87o8bcnfk9.fsf@nicolasgoaziou.fr/) and\n\u003e the relevant [manual section](https://orgmode.org/manual/Citation-handling.html)), and the most recent\n\u003e org-ref version also supports CSL-formatting (see [this\n\u003e video](https://www.youtube.com/watch?v=Xs59PGTfDC0)), citeproc-org is obsolete\n\u003e and will be in maintenance mode (reported bugs will be fixed). \n\u003e The recommended way of getting CSL-rendering of Org citations\n\u003e is therefore using native Org cites with the CSL export processor or using\n\u003e [org-ref 3](https://github.com/jkitchin/org-ref).\n\n**Key features**\n\n- pure Emacs Lisp solution, no external dependencies;\n- extensive support for citation styles described in [CSL (Citation Style\n  Language)](https://citationstyles.org/), an open format used, among others, by [Zotero](https://www.zotero.org/) and [Pandoc](https://pandoc.org/);\n- support for both [org-ref](https://github.com/jkitchin/org-ref) cite links and the (experimental/WIP) Org citation\n  syntax;\n- only BibTeX bibliography files are supported at the moment, but other formats,\n  especially CSL and BibTeX-based ones such as Org-BibTeX and CSL-JSON are easy\n  to add;\n- acts as a simple preprocessor for the Org exporter. In principle, this makes\n  citeproc-org compatible with any Org export backend (e.g., it works with the built-in\n  HTML and ODT backends, and org-to-blog exporters like [ox-hugo](https://ox-hugo.scripter.co/)), it can even be configured to replace BibTeX/biblatex\n  during LaTeX export.\n\n**Table of Contents**\n\n- [Requirements and dependencies](#requirements-and-dependencies)\n- [Installation](#installation)\n- [Setup](#setup)\n- [Usage](#usage)\n    - [Setting the CSL style](#setting-the-csl-style)\n    - [CSL locales](#csl-locales)\n\t- [Org-ref citations](#org-ref-citations)\n        - [Locators and pre/post texts in cite links](#locators-and-prepost-texts-in-cite-links)\n        - [Suppressing affixes and author names in citations](#suppressing-affixes-and-author-names-in-citations)\n    - [Org-mode citations and bibliography using the “wip-cite” syntax](#org-mode-citations-and-bibliography-using-the-wip-cite-syntax)\n\t    - [Bibliography file and placement](#bibliography-file-and-placement)\n \t\t- [Citations](#citations)\n        - [Locators](#locators)\n    - [Output format configuration](#output-format-configuration)\n        - [Ignored export backends](#ignored-export-backends)\n        - [Mapping export backends to citeproc-el formatters](#mapping-export-backends-to-citeproc-el-formatters)\n        - [Bibliography formatting](#bibliography-formatting)\n- [Credits](#credits)\n- [License](#license)\n\n## Requirements and dependencies\n\nciteproc-org requires Emacs 25.1 or later compiled with libxml2 support and \nOrg-mode 9.0 or later. Rendering [org-ref](https://github.com/jkitchin/org-ref) citation\nlinks requires org-ref, while rendering cites in the Org citation syntax\nrequires an Org version that supports the syntax implemented by the `wip-cite`\norg-mode development branch.\n\n## Installation\n\nciteproc-org is available in the [MELPA package repository](https://melpa.org)\nand can be installed using Emacs’s built-in package manager, `package.el`.\n\n## Setup\n\nUsing citeproc-org currently requires adding its main rendering function\n(`citeproc-org-render-references`) to org-mode’s\n`org-export-before-parsing-hook`. This makes it incompatible with [org-ref’s own\nciteproc](https://github.com/jkitchin/org-ref/tree/master/citeproc), which also\nuses this hook. Org-ref’s citeproc is not activated by default, but if you have\nadded its renderer function, `orcp-citeproc`, to your\n`org-export-before-parsing-hook` then it has to be removed before setting up\nciteproc-org.\n\nciteproc-org provides the Emacs command `citeproc-org-setup` to add its\nrenderer to `org-export-before-parsing-hook`, which can be used interactively by\ninvoking\n\n    M-x citeproc-org-setup\n\nduring an Emacs session. After the command’s execution citeproc-org will\nremain active until the end of the session. If you want to use it on a permanent\nbasis then add the following line to your `.emacs` or `init.el` file:\n\n```el\n(citeproc-org-setup)\n```\n\n## Usage\n\nciteproc-org supports two different Org citation syntaxes:\n[org-ref](https://github.com/jkitchin/org-ref) citation links and,\nexperimentally, the citation syntax used by the `wip-cite` development branch of\norg-mode. During the export process citeproc-org detects which type of citations\nare present in the document and automatically uses the corresponding citation\nparser. The two citation styles cannot be mixed.\n\nIn its basic use, citeproc-org overtakes citation rendering for non-LaTeX\nOrg-mode export backends and exported org-mode citations are rendered in the\ndefault Chicago author-date CSL style during export. The handling of citations\nfor LaTeX-based export backends does not change (but see [Ignored export\nbackends](#ignored-export-backends) for ways of changing this behaviour).\n\n### Setting the CSL style\n\nThe CSL style used for rendering references can be set by adding a\n\n    #+CSL_STYLE: /path/to/csl_style_file\n\t\nline to the Org-mode document. (CSL styles can be downloaded, for instance, from\nthe [Zotero Style Repository](https://www.zotero.org/styles).) Dependent styles\n(which are not “unique” styles in the terminology of the Zotero Style\nRepository) are not supported.\n\n### CSL locales\n\nBy default, the `en-US` CSL locale file shipped with citeproc-org is used for\nrendering localized dates and terms in the references, independently of the\nlanguage settings of Org documents. Additional CSL locales can be made available\nby setting the value of the `citeproc-org-locales-dir` variable to a\ndirectory containing the locale files in question (locales can be found at\nhttps://github.com/citation-style-language/locales). The directory must contain\nat least the `en-US` CSL locale.\n\nIf `citeproc-org-locales-dir` is set and an org-mode document contains a\nlanguage setting corresponding to a locale which is available in the directory\nthen citeproc-org will automatically try to use that locale for rendering the\ndocument’s references during export (the used locale will also depend on the\nused CSL style’s locale information).\n\n### Org-ref citations\n\nThe syntax and usage of org-ref citation and bibliography links is described in\ndetail in the [org-ref\nmanual](https://github.com/jkitchin/org-ref/blob/master/org-ref.org).\nciteproc-org relies on a few extensions of the basic syntax and semantics to\nsupport using locators, cite-specific pre/post texts, and suppressing affixes\nand authors in citations.\n\n#### Locators and pre/post texts in cite links\n\norg-ref supports adding pre and post texts to references in the description\nfield of cite links using the `pre_text::post_text` syntax. citeproc-org also\nutilizes cite link descriptions for storing additional citation information but\nchanges the syntax to be compatible with how CSL represents citations.\n\nThe basic syntax, inspired by [pandoc’s citation\nsyntax](https://pandoc.org/MANUAL.html#citations), is `pre_text locator,\npost_text`. For example, the cite link \n\n    [[cite:Tarski-1965][see chapter 1, for an example]] \n\t\nwill be rendered as\n\n    (see Tarski 1965, chap. 1 for an example)\n\nin the default CSL style. \n\nThe start of the locator part has to be indicated by a locator term, while the\nend is either the last comma if it is not followed by digits or, in the absence\nof such a comma, the end of the full description. The following locator terms\nare recognized: `bk.`, `bks.`, `book`, `chap.`, `chaps.`, `chapter`, `col.`,\n`cols.`, `column`, `figure`, `fig.`, `figs.`, `folio`, `fol.`, `fols.`,\n`number`, `no.`, `nos.`, `line`, `l.`, `ll.`, `note`, `n.`, `nn.`, `opus`,\n`op.`, `opp.`, `page`, `p.`, `pp.`, `paragraph`, `para.`, `paras.`, `¶`, `¶¶`,\n`§`, `§§`, `part`, `pt.`, `pts.`, `section`, `sec.`, `secs.`, `sub verbo`,\n`s.v.`, `s.vv.`, `verse`, `v.`, `vv.`, `volume`, `vol.`, `vols.`. Similarly to\npandoc, if no locator term is used but a number is present then “page” is\nassumed.\n\nIf there are more than one cites in a cite link then their associated locators\nand pre/post texts can be specified by using semicolons as separators. For\ninstance, the link\n\n    [[cite:Tarski-1965,Gödel-1931][p. 45;see also p. 53]]\n\t\nrenders as\n\n    (Tarski 1965, 45; see also Gödel 1931, 53)\n\t\nwith the default style.\n\nWhen an Org-mode document is exported to a LaTeX-based format that should not be\nrendered by citeproc-org the cite link descriptions (if present) are\nrewritten to a form suitable for org-ref’s LaTeX export. The concrete form\ndepends on the value of the `citeproc-org-bibtex-export-use-affixes`\nvariable. If the value is `nil` (the default) then the rewritten content will be\nsimply the concatenation of the pre text, the locator and the post text (of the\nfirst block, if there are more). If the value is non-nil then the rewritten\ncontent will be `pre_text::locator post_text`.\n\nIn our experience, setting `citeproc-org-bibtex-export-use-affixes` to\nnon-nil works well with Natbib styles but causes errors when using the built-in\nLaTeX bibliography styles because their `\\cite` command doesn’t accept a\nseparate argument for post text.\n\n#### Suppressing affixes and author names in citations\n\nIn certain contexts it might be desirable to suppress the affixes (typically\nbrackets) around citations and/or the name(s) of the author(s). With org-ref and\nciteproc-org these effects can be achieved by using a suitable cite link type.\n\nThe variables `citeproc-org-suppress-affixes-cite-link-types` (defaults to\n`(\"citealt\")`) and `citeproc-org-suppress-author-cite-link-types` (defaults\nto `(\"citeyear\")`) contain the lists of link types that suppress citation\naffixes and/or author names.\n\n### Org-mode citations and bibliography using the “wip-cite” syntax\n\nCurrently only the the `wip-cite` development branch of Org supports this\ncitaton syntax.\n\n#### Bibliography file and placement\n\nThe path of the BibTeX file to be used has to be specified by a\n\n\t#+BIBLIOGRAPHY: /path/to/bibtex_file\n\nline, while the location where the rendered bibliography should be placed can be\nindicated by a\n\n\t#+BIBLIOGRAPHY: here\n\t\nline in the document. If the document does not contain a `#+BIBLIOGRAPHY: here`\nline then the bibliography is omitted.\n\n#### Citations\n\nciteproc-org supports all citation forms implemented by the `wip-cite`\ndevelopment branch of Org. Short form citations contain only a single item id\nprefixed with an `@` character with or without square brackets to indicate\nparentheses, e.g.,\n\n    In his magnum opus [@doe2018], Doe contradicts the earlier @doe2010.\n\nwhich would be rendered as\n\n\tIn his magnum opus (Doe 2018), Doe contradicts the earlier Doe 2010.\n\nin the default style.\n\nLong form citations, in contrast, have a far more elaborate syntax, which\nsupports multiple cites and pre/post texts:\n\n\t[cite:common_pre_text;pre_text1 @itemid1 post_text1;...;pre_text_n @itemid_n post_text_n;common_post_text]\n\t\n(using pre/post texts and multiple cites is, of course, optional). There is a\nparenthetical variant as well:\n\t\n\t[(cite):common_pre_text;pre_text1 @itemid1 post_text1;...;pre_text_n @itemid_n post_text_n;common_post_text]\n\t\n#### Locators\n\t\nSimilarly to org-ref cites, citeproc-org uses post-texts to represent cite\nlocators. More concretely, the post-text field of cites can have the form\n`locator, suffix`, where the locator starts with a recognized locator term\nsuch as “p.” and \"chap.” (see section [Locators and pre/post texts in cite\nlinks](#locators-and-prepost-texts-in-cite-links), above, for the full list),\nand ends before the first comma or at the end of the whole post-text field if\nthere is no comma. For example, the citation\n\n\t[(cite):see @Doe2018 p. 123, for further references]\n\t\nwould be rendered as\n\n\t(see Doe 2018, 123 for further references)\n\t\nin the default style.\n\n### Output format configuration\n\n#### Ignored export backends\n\nciteproc-org does not render cite links for export backends that are on the list\n`citeproc-org-ignore-backends` (the default value is `(latex beamer)`). Citation\nrendering for these backends is handed over to the active default rendering\nmechanism (org-ref, for instance, uses BibTeX/biblatex for the `latex` and\n`beamer` backends).\n\nBy changing the value of `citeproc-org-ignore-backends` citeproc-org can\nbe instructed to ignore or take over the rendering for certain backends. Most\nnotably, setting its value to `nil` has the effect that references will always\nbe rendered with citeproc-el even for LaTeX output, and BibTeX/biblatex will not\nbe used at all.\n\n#### Mapping export backends to citeproc-el formatters\n\nciteproc-org uses the `org`, `html` and (optionally) `latex` citeproc-el output\nformatters to render citations and bibliographies when exporting an Org\ndocument. Since the `org` formatter has some limitations (stemming from the\nlimitations of the Org-mode markup) it is recommended to use the `html` and the\n`latex` formatters for HTML and LaTeX-based export backends that can handle\ndirect HTML or LaTeX output.\n\nThe mapping between export backends and output formatters can be configured by\ncustomizing the `citeproc-org-html-backends` and\n`citeproc-org-latex-backends` variables—if a backend is in neither of these\nlists then the `org` citeproc-el formatter is used for export.\n\n#### Bibliography formatting\n\nMost of the bibliography formatting parameters (heading, indentation etc.) can\nbe configured—see the `Citeproc Org` customization group for details.\n\n## Credits\n\nThanks to John Kitchin and his co-developers for creating the excellent org-ref\npackage. citeproc-org was inspired by and borrows some implementation ideas\nfrom John Kitchin’s [org-ref citation processor](https://github.com/jkitchin/org-ref/tree/master/citeproc).\n\n## License\n\nCopyright (C) 2018 András Simonyi\n\nAuthors: András Simonyi\n\nThis program is free software; you can redistribute it and/or modify it under\nthe terms of the GNU General Public License as published by the Free Software\nFoundation, either version 3 of the License, or (at your option) any later\nversion.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY\nWARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\nPARTICULAR PURPOSE. See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with\nthis program. If not, see https://www.gnu.org/licenses/.\n\n---\n\nThe “Chicago Manual of Style 17th edition (author-date)” CSL style and the\n“en-US” CSL locale distributed with citeproc-org are both licensed under the\n[Creative Commons Attribution-ShareAlike 3.0 Unported\nlicense](https://creativecommons.org/licenses/by-sa/3.0/) and were developed\nwithin the Citation Style Language project (see https://citationstyles.org). The\n“Chicago Manual of Style 17th edition (author-date)” CSL style was written by\nJulian Onions with contributions from Sebastian Karcher, Richard Karnesky and\nAndrew Dunning.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandras-simonyi%2Fciteproc-org","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandras-simonyi%2Fciteproc-org","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandras-simonyi%2Fciteproc-org/lists"}