life-itself / life-itself/web3
Markdown Citation Renderer: pandoc style citations => proper references
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 1.9k
- Forks
- 213
- PR merge metrics
- No merged PRs in 30d
Description
Want something like this in markdown:
```
Blah blah [@doe99; @smith2000; @smith2004].
```
To become this:
```
Blah blah (Doe 1999, Smith 2000, 2004).
```
Or, a fuller version like:
```
John Doe, "Frogs," *Journal of Amphibians* 44 (1999);
Susan Smith, "Flies," *Journal of Insects* (2000);
Susan Smith, "Bees," *Journal of Insects* (2004).
```
See pandoc for more: https://pandoc.org/MANUAL.html#extension-citations
🎁 Bonus: generating a reference section at the end of a document ie. list of citations. This could be something that is explicitly inserted by having a special item like `[references]` just like one has `[toc]` or maybe more MDX style ``
## Acceptance
* [ ] Clear description of what we want
* [ ] Documented manual approach to doing this (i.e. manually add references to docs using obsidian)
* [ ] Remark or similar plugin to do what we want
* [ ] Document in editor guide
## Tasks
* [ ] Document our current flow for semi-manual addition of references @smdiehl
* [ ] Analyse what is needed for this to work e.g. do we need a bibtex file exported locally (or can we connect to zotero as part of the build or ...)
* [ ] Create
## Notes
* What is the format of the citations? **✅ Pandoc style i.e. https://pandoc.org/MANUAL.html#extension-citations `Blah blah [@doe99; @smith2000; @smith2004].`**
* What result do we expect in html? Do we need to be customizable via https://citationstyles.org? **✅ something like `Doe (1999)` for short and TODO style for full. Don't need customizability and can just default to one style**
* How does this work? Does it need a bibtex/json file? **🚧 assume it does - see architecture diagram below. But not certain**
* Does a remark plugin already exist for this? **✅ Found 2. First seems more recent and more appropriate on quick scan. However, it just produces syntax tree and does not render the citations. https://github.com/benrbray/remark-cite & https://github.com/Symbitic/remark-plugins/tree/master. May need more research here.**
* What is the obsidian plugin? **✅ https://github.com/hans/obsidian-citation-plugin - uses pandoc style citations**
### Architecture
```mermaid
graph LR
a[Markdown file w/ citation]
b[Bibliography file with citation keys]
b2[Citation Style info]
c[Processor]
d[Output rendered file with proper citation]
a --> c
b --> c
b2 -.optional.-> c
c --> d
```
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Pandoc citations specification and compare the two mentioned remark plugins, remark-cite and the Symbitic remark plugins. Determine the required bibliography format, citation rendering approach, and whether a reference-list item is in scope. Done means the current manual workflow is documented, an implementation path is selected, and the editor guide describes the supported citation flow.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100