/celine, /libertine

@celine/bibhtml

Max Bo

@celine/bibhtml is a Web Components-based referencing system for HTML documents. It aims to provide a similar user experience to referencing in LaTeX/BibTeX[#?]. It's a thin wrapper around Citation.js[#?] and gracefully degrades when citations and references are malformed or JavaScript is disabled.

@celine/bibhtml takes significant inspiration from @citation-js/replacer, References Web Component[#?], Nota's citations[#?], and Meyer's Blinded By the Light DOM[#?].

GitHub MaxwellBo/celine + /issues License MIT
JSR jsr.io/@celine/bibhtml + /docs Version 1.7.0,

Installation

Add the following script to your HTML file's <head> element:

API

@celine/bibhtml is structured around 3 custom elements:

  1. <bh-cite>(a)
  2. <bh-reference>
  3. <bh-bibliography> 


<bh-cite><a href="#willighagen2019">[#?]</a></bh-cite>
...
<bh-reference id="willighagen2019">
  @article{willighagen2019,
  title = {Citation.js: a format-independent, modular bibliography tool for the browser and command line},
  author = {Willighagen, Lars G.},
  year = 2019,
  month = aug,
  keywords = {Bibliography, Javascript},
  volume = 5,
  pages = {e214},
  journal = {PeerJ Computer Science},
  issn = {2376-5992},
  url = {https://doi.org/10.7717/peerj-cs.214},
  doi = {10.7717/peerj-cs.214}
  }
</bh-reference>
...
<bh-bibliography format="apa">
</bh-bibliography>

<bh-cite>

To cite Citation.js[#?] as a reference, we can use the <bh-cite> element:

The <bh-cite> element:

  1. Unhides the <bh-reference> targeted by the first inner <a> element, and adds a backlink to itself
  2. Replaces the first #?(b) contained within the first inner <a> element with the reference number

This permits us to change the formatting of the inline citation, perhaps to use parentheses: (#?)

We may choose to forgo numbered citations entirely: Mokhov et al. 2018

The ref attribute assigns an explicit reference ID, and prevents the <bh-cite> element from performing reference ID inference (extracting the reference ID from href attribute of the first inner <a> element). This allows the inner <a> element to href directly to the the referenced material: Build Systems à la Carte

The deref attribute, achieves a similar goal by dereferencing a citation, setting the href attribute of the inner <a> element to the URL associated with the reference as determined by Citation.js. Thus, Build Systems à la Carte is dereferenced to link to https://doi.org/10.1145/3236774.

If we cite a missing reference[#?] that is not in the HTML document, the inner text of the element is displayed unchanged.

The inner text of a <bh-cite> element is displayed unchanged when:

In summary:

Pattern Citation navigates to:
<bh-cite><a href="#refId">... "#refId"
<bh-cite ref="refId"><a href="example.com">... "example.com"
<bh-cite deref><a href="#refId">... URL yielded by Citation.js

<bh-reference>

Each <bh-reference> must be tagged with an id attribute, and contain reference information in 4 supported formats:

BibTeX

This expands to reference [#?], and is backed by @citation-js/plugin-bibtex.

Unstructured text

A <bh-reference> can contain unstructured text. This format is useful when:

Observe that the reference [#?] is unchanged.

DOI

This expands to reference [#?], and is backed by @citation-js/plugin-doi.

Wikidata

This expands to reference [#?], and is backed by @citation-js/plugin-wikidata.

<bh-bibliography>

The <bh-bibliography> finds <bh-reference>s and renders them in a formatted list (like at the bottom of the page).

</bh-bibliography> has very simple calling semantics. Just: 


<bh-bibliography format="apa">
</bh-bibliography>

Do not put <bh-reference> elements inside the <bh-bibliography> element. Everything will break.

The format attribute sets the citation style. Currently only 1 is supported, "apa".

References are rendered in the order they are cited by <bh-cite> elements, not the order they are declared in the HTML document.

Extras

<bh-cite> has an appropriate implementation of disconnectedCallback to remove the citation from the bibliography when the <bh-cite> element is removed from the DOM.

References

@article{willighagen2019, title = {Citation.js: a format-independent, modular bibliography tool for the browser and command line}, author = {Willighagen, Lars G.}, year = 2019, month = aug, keywords = {Bibliography, Javascript}, volume = 5, pages = {e214}, journal = {PeerJ Computer Science}, issn = {2376-5992}, url = {https://doi.org/10.7717/peerj-cs.214}, doi = {10.7717/peerj-cs.214} } @misc{avellar2021, author = {Matheus Avellar}, title = {References Web Component}, howpublished = {\url{https://lab.avl.la/references-webcomponent/}}, note = {GitHub: \url{https://github.com/MatheusAvellar/references-webcomponent}}, year = {2021}, month = aug, } @inproceedings{crichton2021nota, title={A New Medium for Communicating Research on Programming Languages}, author={Crichton, Will}, booktitle={Proceedings of the 1st Workshop on Human Aspects of Types and Reasoning Assistants}, year={2021} } Brian Dunbar (2017-08-03). The Sun | NASA. National Aeronautics and Space Administration. Accessed on 2021-08-30. 10.1145/3236774 Q8029 @misc{griesemer2020featherweight, title={Featherweight Go}, author={Robert Griesemer and Raymond Hu and Wen Kokke and Julien Lange and Ian Lance Taylor and Bernardo Toninho and Philip Wadler and Nobuko Yoshida}, year={2020}, eprint={2005.11710}, archivePrefix={arXiv}, primaryClass={cs.PL}, url={https://arxiv.org/abs/2005.11710}, } @article{meyer2023lightdom, author = {Meyer, Eric A.}, title = {Blinded By the Light {DOM}}, year = {2023}, month = nov, day = {1}, url = {https://meyerweb.com/eric/thoughts/2023/11/01/blinded-by-the-light-dom/}, journal = {Eric's Archived Thoughts}, keywords = {web components, Light DOM, JavaScript, DOM}, note = {Blog post discussing the advantages of using Light DOM over Shadow DOM in web components} }

Footnotes

  1. ^ The bh- prefix was chosen to make the use of <bh-cite> relatively short..
  2. ^ I considered replacing just ?, rather than the somewhat uglier #?, but I worried that this would cause replacement of ?s appended to the end of uncertain dates, like 2017?.

How to cite

If you use this software, please cite it as below:

@software{Bo_bibhtml_2024,
  author = {Bo, Maxwell},
  license = {MIT},
  title = {{@celine/bibhtml}},
  url = {https://maxbo.me/celine/bibhtml},
  year = {2024}
}