{"id":13718956,"url":"https://github.com/loup-brun/hugo-cite","last_synced_at":"2025-04-10T02:56:57.172Z","repository":{"id":39815814,"uuid":"254955331","full_name":"loup-brun/hugo-cite","owner":"loup-brun","description":"📝 Easily manage your bibliography and in-text citations with Hugo, the popular static-site generator.","archived":false,"fork":false,"pushed_at":"2024-05-24T16:46:39.000Z","size":219,"stargazers_count":117,"open_issues_count":37,"forks_count":33,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-24T04:24:10.215Z","etag":null,"topics":["bibliography","citations","csl-json","hugo","shortcode","static-site-generator"],"latest_commit_sha":null,"homepage":"https://labs.loupbrun.ca/hugo-cite/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"wtfpl","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loup-brun.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}},"created_at":"2020-04-11T21:05:03.000Z","updated_at":"2025-03-17T11:51:00.000Z","dependencies_parsed_at":"2023-01-29T19:46:09.821Z","dependency_job_id":null,"html_url":"https://github.com/loup-brun/hugo-cite","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loup-brun%2Fhugo-cite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loup-brun%2Fhugo-cite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loup-brun%2Fhugo-cite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loup-brun%2Fhugo-cite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loup-brun","download_url":"https://codeload.github.com/loup-brun/hugo-cite/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248147732,"owners_count":21055545,"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","citations","csl-json","hugo","shortcode","static-site-generator"],"created_at":"2024-08-03T01:00:39.977Z","updated_at":"2025-04-10T02:56:57.137Z","avatar_url":"https://github.com/loup-brun.png","language":"HTML","funding_links":[],"categories":["HTML","Theme Components"],"sub_categories":["Non-Official"],"readme":"# Hugo Cite\n\n📝 Easily manage your bibliography and in-text citations with [Hugo](https://gohugo.io), the popular static-site generator.\n\n[**Documentation site + demo \u0026rarr;**](https://labs.loupbrun.ca/hugo-cite/)\n\n---\n\n⚠️ **Important note: APA is the only citation style currently available, and you must be aware that it does not match the entire APA spec.**  \nMore styles may be added eventually (contributions welcome!), but given that they are extremely verbose to implement, this is unlikely to happen in a near future.\n\n---\n\n## Install\n\n### 1. Download\n\nDownload Hugo Cite in the `themes/hugo-cite` directory, either by [cloning with Git](https://github.com/loup-brun/hugo-cite) (the preferred method) or by [downloading as a ZIP file](https://github.com/alex-shpak/hugo-book/archive/master.zip).\n\nThe Git way:\n\n```bash\ngit submodule add https://github.com/loup-brun/hugo-cite.git themes/hugo-cite\n```\n\nYour project directory should then look like this:\n\n```bash\n# Your Hugo project directory\n├── config.yml\n└── themes\n    └── hugo-cite\n```\n\n### 2. Configure\n\nEdit the `theme` parameter in your Hugo config file and add `hugo-cite` after your theme.\n\n```yaml\n# config.yml\ntheme:\n- \u003cyour-theme\u003e\n- hugo-cite\n```\n\n### 3. Add CSS\n\nReference the CSS somewhere in your HTML templates:\n\n```html\n\u003clink rel=\"stylesheet\" type=\"text/css\" href=\"{{ \"/hugo-cite.css\" | relURL }}\" /\u003e\n```\n\n## Usage\n\nYou must first provide a **[CSL-JSON](https://citeproc-js.readthedocs.io/en/latest/csl-json/markup.html) bibliography file**.\n(Other formats, such as BiBTeX, are _not_ supported.)\nIn Zotero for instance, this can be accomplished by selecting the CSL-JSON format when exporting a collection.\nJust include `bib` in the filename (such as `bibliography.json`,`oh-my-bib.json`, or simply `bib.json`) and save it inside your Hugo project directory.\n\nHere is an example:\n\n```bash\n# Your Hugo project directory\n├── content\n│   ├── article1\n│   │   ├── bib.json\n│   │   └── index.md\n│   ├── article2\n│   │   ├── image.jpg\n│   │   ├── index.md\n│   │   └── mr-bib.json\n│   └── article3\n│       ├── index.md\n│       └── oh-my-bib.json\n└── path\n    └── to\n        └── bib.json\n```\n\n### Shortcodes\n\nThere are two shortcodes you can use in your content:\n\n- **`{{\u003c bibliography \u003e}}`**: display a list of works.\n- **`{{\u003c cite \u003e}}`**: render an in-text citation.\n\n### Display a bibliography\n\n#### Basic Example\n\nBy default, the `{{\u003c bibliography \u003e}}` shortcode will render all entries from a `bib.json` included in a [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles) (see directory example above).\n\n```markdown\n\u003c!-- Markdown --\u003e\n\n{{\u003c bibliography \u003e}}\n```\n\n#### Cited Works\n\nYou can restrict the list only to works cited on the page (with the use of in-text citations, see below):\n\n```markdown\n\u003c!-- Markdown --\u003e\n\n{{\u003c bibliography cited \u003e}}\n```\n\n#### File Defined in Front Matter\n\nYou can specify the path to a JSON file located *inside* the Hugo project directory in the content page’s **front matter** using the `bibFile` parameter.\nThis is especially useful when working with `cited` entries:\n\n```markdown\n---\ntitle: My Article\nbibFile: path/to/bib.json # path relative to project root\n---\n\n## Bibliography\n\n\u003c!-- The bibliography will display works from path/to/bib.json --\u003e\n{{\u003c bibliography \u003e}}\n```\n\n#### File Defined in Shortcode\n\nAlternatively, you can specify the path to the CSL-JSON file at the shortcode level:\n\n```markdown\n\u003c!-- Markdown --\u003e\n\n{{\u003c bibliography \"path/to/bib.json\" \u003e}}\n```\n\n#### Combine Options\n\nYou can also **combine both options** (the path to the JSON file must come first):\n\n```markdown\n\u003c!-- Markdown --\u003e\n\n{{\u003c bibliography \"path/to/bib.json\" cited \u003e}}\n```\n\n**Note**: if you are working with a `cited` bibliography, you’ll have to specify the path to the JSON file in the front matter for in-text citations to access the same file.\n\n#### Named Params\n\nYou can chose to use **named params** for clarity (the order does not matter here):\n\n```markdown\n\u003c!-- Markdown --\u003e\n\n{{\u003c bibliography src=\"path/to/bib.json\" cited=\"true\" \u003e}}\n```\n\n#### File From a URL\n\nThanks to Hugo’s [`getJSON`](https://gohugo.io/templates/data-templates/#data-driven-content) function, the path can also be a **URL**.  \n*Note however that this method may have some drawbacks if you are [reloading often](https://gohugo.io/templates/data-templates/#livereload-with-data-files), see the Hugo docs regarding potential issues.*\n\n```markdown\n\u003c!-- Markdown --\u003e\n\n{{\u003c bibliography \"http://example.com/my/bib.json\" \u003e}}\n```\n\n### Render in-text citations\n\nUse the `{{\u003c cite \u003e}}` shortcode to render rich in-text citations.\n\nExample:\n\n```markdown\n\u003c!-- Markdown --\u003e\n\n{{\u003c cite \"Lessig 2002\" \u003e}}\n```\n\nThe citation key (in the above example, `Lessig 2002`) must match the `id` field of a reference in your CSL-JSON file.\nYou can make it look like an author-date format, or anything else.\n\nHere’s an excerpt of a CSL-JSON file:\n\n```json\n[\n    {\n        \"id\": \"Lessig 2002\",\n        \"author\": [\n            {\n                \"family\": \"Lessig\",\n                \"given\": \"Lawrence\"\n            }\n        ]\n    }\n]\n```\n\nUsing the citation key defined in the CSL-JSON, you can reference your entry in content files:\n\n```markdown\n\u003c!-- Markdown --\u003e\n\nOur generation has a philosopher.\nHe is not an artist, or a professional writer.\nHe is a programmer. {{\u003c cite \"Lessig 2002\" \u003e}}\n```\n\n#### Suppress Author\n\nFor an abbreviated in-text citation form, you can add a **dash** (`-`) at the beginning of your citation key:\n\n```markdown\n\u003c!-- Markdown --\u003e\n\n{{\u003c cite \"-Lessig 2002\" \u003e}}\n```\n\nThe above would render `(2002)` rather than `(Lessig, 2002)`.\n\n#### Cite a Page\n\nYou can also provide a **page** as the second positional parameter:\n\n```markdown\n\u003c!-- Markdown --\u003e\n\n{{\u003c cite \"Lessig 2002\" 5 \u003e}}\n```\n\nThe example above will render `(Lessig, 2002, p. 5)` (note the `p.` was added by hugo-cite; you need not to add it).\n\n#### Cite a Page Range\n\nYou can instead specify a **range of pages** using a **dash** `-`, which will output `pp.` before the page range (ensure there is no space between the page numbers):\n\n```markdown\n\u003c!-- Markdown --\u003e\n\n{{\u003c cite \"Lessig 2002\" 5-6 \u003e}}\n```\n\nThe example above will render `(Lessig, 2002, pp. 5-6)`.\n\n\n#### Combine Multiple Citations\n\nYou can combine **multiple citations** in a single block, using the **semi-colon** (`;`) separator (no spaces around the semi-colon):\n\n```markdown\n\u003c!-- Markdown --\u003e\n\n{{\u003c cite \"Lessig2002;Nussbaum2011;Dewey1938\" \u003e}}\n```\n\nThe above would render `(Lessig, 2002; Nussbaum, 2011; Dewey, 1938)`.\n\nWorks with pagination too, **in the matching order** of the citation keys:\n\n```markdown\n\u003c!-- Markdown --\u003e\n\n{{\u003c cite \"Lessig2002;Nussbaum2011;Dewey1938\" \"5-6;;25\" \u003e}}\n```\n\nThe above would render `(Lessig, 2002, pp. 5-6; Nussbaum, 2011; Dewey, 1938, p. 25)`.\n\n## Cited Works\n\n```markdown\n\u003c!-- Include the list of cited works on the page --\u003e\n{{\u003c bibliography cited \u003e}}\n```\n\n## Demo\n\nCheck out a working [online demo \u0026rarr;](https://labs.loupbrun.ca/hugo-cite/demo/)\n\n[![Screenshot featuring Hugo Cite](https://user-images.githubusercontent.com/9596476/79130193-88061600-7d74-11ea-9654-0dc8b3d5bd2d.png)](https://labs.loupbrun.ca/hugo-cite/demo/)\n\n## License\n\n[WTFPL](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floup-brun%2Fhugo-cite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floup-brun%2Fhugo-cite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floup-brun%2Fhugo-cite/lists"}