/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 5.1.0,

Usage

via CDN

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

<script type="module" src="https://esm.sh/jsr/@celine/[email protected]"></script>

via local file

Download mod.ts and include it from your project: 

<script type="module" src="./mod.ts"></script>

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 marker in the first inner <a> element with the configured replacement; by default the marker is ? and the replacement is 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.

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

The marker attribute names the character to swap out. It defaults to ?, but can be any other character, e.g. n: [n]

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

The replacement attribute (which defaults to "number") determines what the marker named by marker is swapped for.

When replacement="number", the first occurrence of the specified marker is replaced with the reference number.

<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

changelog.xml RSS feed icon

@celine/bibhtml uses Semantic Versioning 2.0.0.

Showing 10 most recent entries.

Version Date Changes

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}
}