/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[?], and Nota's citations[?].

GitHub MaxwellBo/celine + /issues License MIT
JSR jsr.io/@celine/bibhtml + /docs Version 3.16.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>
  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>

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 ? contained within the first inner <a> element with the reference number

Thus, to cite Citation.js[?] as a reference:

We can change the formatting of the inline citation, say, to use parentheses: (?)

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

We can forgo numbered citations entirely by omitting a ? from the inner text of the first inner <a> element: Mokhov et al. 2018

The ref attribute accepts an explicit reference ID (where a reference ID is always prefixed by a #), permitting the inner <a> element to href directly to the the referenced material. Thus, Build Systems à la Carte is explicitly linked to https://doi.org/10.1145/3236774. The ref attribute facilitates adding a bibliography to a HTML document full of existing hyperlinks that should remain unchanged.

The deref flag dereferences 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.

The replace attribute (which defaults to "number") determines what happens to the inner text of a <bh-cite> element.

When replace="number", the first ? in the inner text of the first inner <a> element is replaced with the reference number.

When replace="none", no replacement is made. You will need to set replace="none" if the title of a work contains a ? in it: Who wins when the House and the Senate are controlled by different parties?

In summary:

Pattern Citation navigates to:
<bh-cite><a href="#refId">... <bh-reference> with id="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 one of 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, and will display it unchanged. This format is useful when the reference is not in a machine readable format supported by @celine/bibhtml or Citation.js. When reference information in a structured format is malformed, @celine/bibhtml will treat it as unstructured text and display it unchanged.

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 simple calling semantics: 


<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} } 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} } Jacobs, J., Mervosh, S., & Stevens, M. (2018, November 7). When the House and the Senate are controlled by different parties, who wins? The New York Times. Retrieved from https://www.nytimes.com/2018/11/07/us/politics/house-senate-difference-control.html

How to cite

If you use this library, 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}
}