{"id":13504912,"url":"https://github.com/mivanit/dendron-citations","last_synced_at":"2026-01-17T09:58:59.481Z","repository":{"id":40823457,"uuid":"465031063","full_name":"mivanit/dendron-citations","owner":"mivanit","description":"tool for making dendron work well with citing things using bibtex or Zotero","archived":false,"fork":false,"pushed_at":"2022-03-26T20:45:03.000Z","size":179,"stargazers_count":19,"open_issues_count":0,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-11-01T02:34:57.297Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/mivanit.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":"2022-03-01T19:35:34.000Z","updated_at":"2023-08-25T04:46:34.000Z","dependencies_parsed_at":"2022-09-19T06:01:58.448Z","dependency_job_id":null,"html_url":"https://github.com/mivanit/dendron-citations","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mivanit%2Fdendron-citations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mivanit%2Fdendron-citations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mivanit%2Fdendron-citations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mivanit%2Fdendron-citations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mivanit","download_url":"https://codeload.github.com/mivanit/dendron-citations/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246254077,"owners_count":20747946,"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":[],"created_at":"2024-08-01T00:00:53.368Z","updated_at":"2026-01-17T09:58:59.474Z","avatar_url":"https://github.com/mivanit.png","language":"Python","funding_links":[],"categories":["Dendron Enhancers"],"sub_categories":["Other"],"readme":"# dendron-citations\n\ntool for making [Dendron](https://www.dendron.so) work well with citing things using bibtex or Zotero\n\nWORK IN PROGRESS. please use with care, since this will overwrite files in your dendron vault\n\nThe main script is [`dendron_gen_refs.py`](scripts/dendron_gen_refs.py), which generates a vault of dendron notes corresponding to entries from a bibtex file\n\nthis allows the user to reference the dendron notes instead of raw bibtex item (such as when using [PandocCiter](https://github.com/notZaki/PandocCiter)), which lets us use backlink features from dendron to see where we have cited a paper\n\n\u003e Note: I personally put all my references in a separate vault from my main vault, to avoid clutter. I highly recommend this, since this *might* also prevent you from accidentally overwriting things in your main vault.\n\n\n# Contents:\n- [Usage](#usage)\n- [Installation](#installation)\n- [Extras](#extras)\n- [Roadmap](#roadmap)\n\n\n\n# Usage: \n\nto generate reference notes, run from anywhere:\n\n```bash\ndendron_gen_refs.py [cfg_path] [--\u003ckwarg\u003e=\u003cval\u003e]\n```\n\n## Help and configuration\n\n- `--help` : print help message and exit:\n```bash\ndendron_gen_refs.py --help\n```\n\n- `--print_cfg` : print to console an example config in either json or yaml (json by default):\n\n```bash\ndendron_gen_refs.py --print_cfg [--fmt=\u003cformat\u003e]\n```\n\n## Generation:\n\nwhen running\n```bash\ndendron_gen_refs.py [cfg_path] [**kwargs]\n```\n\n`cfg_path` should be the location of a yaml or json config file\nany of those items can be overwritten as keyword arguments using \n`--\u003ckeyword\u003e=\u003cvalue\u003e`\n\nthe expected config elements, types, and default values are:\n```python\n\tbib_filename : str = 'refs.bib'\n\tvault_loc : str = 'vault/'\n\tnote_prefix : str = 'refs.'\n\tmake_tag_notes : bool = True\n\tverbose : bool = False\n\tkebab_case_tag_names : bool = False\n\ttemplate_path : Optional[str] = None\n```\n\n## Examples:\n\n```bash\ndendron_gen_refs.py gen --bib_filename=\u003cbibtex_file\u003e --vault_loc=\u003coutput_dir\u003e\n```\n\nOr, we could create a config file such as [`examples/custom_cfg.json`](examples/custom_cfg.json) and pass it in as\n```bash\ndendron_gen_refs.py gen \u003cpath_to_config_file\u003e\n```\n\n\u003e **Note:** if you pass a config file, the script will change its directory to that of the config file, to allow paths to be specified relative to that file.\n\n\n\n# Installation:\n\nNot yet on [PyPi](https://pypi.org/), due to instability. you can install with\n```bash\npip install -e git+https://github.com/mivanit/dendron-citations.git#egg=dendron_citations\n```\n\nNote that this will place an executable `dendron_gen_refs.py` in your python `Scripts` folder (and thus hopefully in your path).\n\n## Dependencies:\n\n- https://github.com/t-wissmann/biblib\n\t- not on pypi, installed from git repo\n\t- note: forked from https://github.com/aclements/biblib, which no longer works\n- [`pyyaml`](https://github.com/yaml/pyyaml/)\n- [`chevron`](https://github.com/noahmorrison/chevron)\n\t- python implementation of the [mustache](https://mustache.github.io) templating language\n- [`pypandoc`](https://github.com/NicklasTegner/pypandoc) (optional)\n\t- for converting notes to markdown\n\n\n\n\n\n\n\n# Extras\n\n## tag notes\n\nNot only can we use dendron backlinks to view where we have cited a certain paper, but we can additionally use the backlinks to see all papers by a given author, or all papers with a given keyword!\n\nThe argument `--make_tag_notes`, `True` by default, will enable the generation of notes for each tag, as long as the tag does not yet exists. Keywords will be processed into tags by removing spaces and other extra characters. Author tags will be of the format `\u003cfirst_char_of_first_name\u003e-\u003clast_name\u003e`, with all characters converted to ascii. The actual notes for author tags will contain the full author names.\n\n## templates\n\nFor now, you need to manually modify the template string `DEFAULT_TEMPLATE` in the file `refs_vault_gen.py` to suit your needs. The template is in [Mustache](https://mustache.github.io) format, with some extensions:\n\n- Add the prefix `_bln_` to the name of any iterable variable to get access to a boolean value that is true if the variable is not empty\n- Lists of non-dict items are turned into lists of dicts, where each dict has a single key `elt` with the value of the item\n\nFor example, if `keywords` is a list of strings `['a', 'b']`, we can use the template\n```mustache\n{{#_bln_keywords}}# Keywords\n{{/_bln_keywords}}\n{{#keywords}}\n - #{{elt}}\n{{/keywords}}\n```\n\nto print\n```markdown\n# Keywords\n - a\n - b\n```\n\nor to return an empty string (with newlines) if `keywords` is empty.\n\n## vscode task\n\nin order to have a vscode shortcut to running the `dendron_gen_refs.py` script, we can take advantage of [VSCode Tasks](https://code.visualstudio.com/docs/editor/tasks) and add the following task to `.vscode/tasks.json`:\n\n```json\n{\n\t\"label\": \"dendron-citations\",\n\t\"type\": \"shell\",\n\t\"command\": \"dendron_gen_refs.py {{your_config_file}}\",\n}\n```\n\nwhere `{{your_config_file}}` is the path to your config file relative to the root of the workspace -- for example, `examples/custom_cfg.json`\n\n\n\n## cross-vault links snippet\n\nto allow simpler references to papers in a separate vault, without having to type `[[dendron://refs-vault/\u003cbibtex key\u003e]]`, the user may create a vscode snippet in `\u003e Preferences \u003e Configure User Snippets \u003e markdown.json`\n\n```json\n\"dendron-cite\": {\n\t\"prefix\": \"@\",\n\t\"body\": [\n\t\t\"[[dendron://refs-vault/refs.$1]]\"\n\t],\n\t\"description\": \"dendron reference citation\"\n},\n```\n\n\n\n\n# Roadmap:\n\n## general\n- [x] implement a configuration system\n- [x] set up as an installable package\n- [ ] turn this into a real vscode plugin\n\t- will probably use [`vscode-ext`](https://github.com/CodeWithSwastik/vscode-ext)\n\n## bibtex integration\n\n- [x] given a bibtex file, generate a vault of dendron notes bibtex keys as filenames\n- [x] add tags and other things from bibtex to metadata\n- [x] optional generation of tag files\n- [ ] \"beneath\" each note for the bibtex, add another note for the citation itself.\n\t- note that this will all break if the bibtex keys change!\n- [ ] automatically convert [PandocCiter](https://github.com/notZaki/PandocCiter) style \n\t- this will allow for better searching for papers\n- [ ] make citations work properly when compiling with [Pandoc](https://pandoc.org/)\n\t- probably best to do this as part of [dendron-pandoc](https://github.com/mivanit/dendron-pandoc)\n\n## zotero integration\n\ndo everything as for bibtex integration, but also:\n\n- [ ] add links/copies in zotero to the dendron notes (when they exist)\n- [ ] have zotero item materials inside dendron file\n\t- zotero notes, plaintext attachments inline\n\t- links to all other attachments\n\t- exclude the dendron file to avoid recursion, haha\n\n\n# Developing:\n\nAfter cloning, run\n```bash\nmake help\n```\nto see some utilities for developing (setting up a virtual environment, running type and style checkers, etc.)\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmivanit%2Fdendron-citations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmivanit%2Fdendron-citations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmivanit%2Fdendron-citations/lists"}