Skip to content

Commit

Permalink
1.0.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@MaxwellBo
MaxwellBo committed Dec 8, 2024
1 parent cf55f4c commit ee5d100
Show file tree
Hide file tree
Showing 3 changed files with 40 additions and 40 deletions.
2 changes: 1 addition & 1 deletion bibhtml/deno.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@celine/bibhtml",
"version": "0.16.0",
"version": "1.0.0",
"license": "MIT",
"exports": "./mod.ts"
}
75 changes: 37 additions & 38 deletions bibhtml/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,14 +68,15 @@ <h1>@celine/bibhtml</h1>
<cite>@celine/bibhtml</cite> is a <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_components">Web
Components</a>-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 <a
href="https://citation.js.org/">Citation.js</a><sup><bh-cite>willighagen2019</bh-cite></sup> and
href="https://citation.js.org/">Citation.js</a><sup><bh-cite><a href="#willighagen2019">[#?]</a></bh-cite></sup> and
gracefully degrades when citations and references are malformed or JavaScript is disabled.
</p>
<p>
<cite>@celine/bibhtml</cite> takes significant inspiration from <a href="https://github.com/citation-js/replacer">@citation-js/replacer</a>, <a
href="https://lab.avl.la/references-webcomponent/">References Web Component</a><sup><bh-cite>avellar2021</bh-cite></sup> and <a
href="https://lab.avl.la/references-webcomponent/">References Web Component</a><sup><bh-cite><a href="#avellar2021">[#?]</a></bh-cite></sup> and <a
href="https://nota-lang.org/reference.html#def-section-2.4">Nota's
citations</a><sup><bh-cite>crichton2021nota</bh-cite></sup>.
citations</a><sup><bh-cite><a href="#crichton2021nota">[#?]</a></bh-cite></sup>.
</p>
</section>

<table>
Expand Down Expand Up @@ -121,7 +122,7 @@ <h2>Installation</h2>
Add the following script to your HTML file's <code>&lt;head&gt;</code> element:
</p>

<div id="installation"><script type="module" src="https://esm.sh/jsr/@celine/bibhtml@0.13.0"></script></div>
<div id="installation"><script type="module" src="https://esm.sh/jsr/@celine/bibhtml@0.16.0"></script></div>

<script id="installation-cell" type="module">
celine.cell("installation", () => {
Expand Down Expand Up @@ -178,7 +179,7 @@ <h3><code>&lt;bh-cite&gt;</code></h3>

<p>
To cite
<u id="inner-text-container">Citation.js<sup><bh-cite>willighagen2019</bh-cite></sup></u> as a reference,
<span id="inner-text-container">Citation.js<sup><bh-cite><a href="#willighagen2019">[#?]</a></bh-cite></sup></span> as a reference,
we can use the <code>&lt;bh-cite&gt;</code> element:
</p>

Expand All @@ -191,8 +192,17 @@ <h3><code>&lt;bh-cite&gt;</code></h3>
</script>

<p>
If we <u id="missing-container">cite a missing reference<sup><bh-cite>freud2012</bh-cite></sup></u> that is
not in the HTML document, the inner text of the element is displayed as a fallback:
The <code>&lt;bh-cite&gt;</code> element:
<ol>
<li>Replaces the first <code>#?</code> contained within an <code>&lt;a&gt;</code> with the reference number</li>
<li>Unhides the reference</li>
<li>Adds a <a href="https://en.wikipedia.org/wiki/Backlink">backlink</a> from the corresponding reference to the citation</li>
</ol>
</p>

<p>
If we cite a <span id="missing-container">missing reference<sup><bh-cite><a href="#freud2012">[#?]</a></bh-cite></sup></span> that is
not in the HTML document, the inner text of the element is displayed unchanged.
</p>

<script id="missing-cell" type="module">
Expand All @@ -214,43 +224,32 @@ <h3><code>&lt;bh-cite&gt;</code></h3>
</p>

<p>
The <code>&lt;bh-cite&gt;</code>'s <code>ref</code> attribute allows us to provide a more graceful fallback, by parsing the
reference ID from the <code>ref</code> attribute rather than the inner text. We'll <u id="ref-container">cite Citation.js<sup><bh-cite ref="willighagen2019"><a
href="#willighagen2019">willighagen2019</a></bh-cite></sup> again</u>, but with an inner <code>&lt;a href="#willighagen2019"&gt;</code> to the <code>&lt;bh-reference&gt;</code> element.
</p>

<script id="ref-cell" type="module">
celine.cell("ref-cell", () => {
const cloned = document.getElementById('ref-container').cloneNode(true);
This permits us to cite references with flexible inline citation formatting <span id="flex-1-container">like <sup><bh-cite><a href="#birolEtAl2013">(#?)</a></bh-cite></sup></span>
</p>

<script id="flex-1-cell" type="module">
celine.cell("flex-1-cell", () => {
const cloned = document.getElementById('flex-1-container').cloneNode(true);
cloned.querySelector('bh-cite').removeAttribute('id');
return htl.html`<pre class='echo'>${cloned.innerHTML}</pre>`
})
</script>
</p>

<p>
We can use <code>&lt;bh-cite&gt;</code>'s <code>href</code> attribute with a reference ID to force the inner text to always be displayed.
</p>

<p>
This permits us to cite references with flexible inline citation formatting, <u id="href-container">like (<bh-cite href="birolEtAl2013">Birol et al.</bh-cite>, <a href="#birolEtAl2013">2013</a>) or <bh-cite href="birolEtAl2013">Birol et al.</bh-cite> [<a href="#birolEtAl2013">2013</a>]</u>.
</p>
<span id="flex-2-container">or (<bh-cite><a href="#birolEtAl2013">Birol et al.</a></bh-cite>, <a href="#birolEtAl2013">2013</a>)</span>

<script id="href-cell" type="module">
celine.cell("href-cell", () => {
const cloned = document.getElementById('href-container').cloneNode(true);
<script id="flex-2-cell" type="module">
celine.cell("flex-2-cell", () => {
const cloned = document.getElementById('flex-2-container').cloneNode(true);
cloned.querySelector('bh-cite').removeAttribute('id');
return htl.html`<pre class='echo'>${cloned.innerHTML}</pre>`
})
</script>

<p>
We can still use an inner fallback link with the <code>href</code> attribute: <u id="href-inner-container">[<bh-cite href="birolEtAl2013"><a href="#birolEtAl2013">Birol et al. 2013</a></bh-cite>]</u>.
</p>
<span id="flex-3-container">or <bh-cite><a href="#birolEtAl2013">Birol et al.</a></bh-cite> [<a href="#birolEtAl2013">2013</a>]</span>.

<script id="href-inner-cell" type="module">
celine.cell("href-inner-cell", () => {
const cloned = document.getElementById('href-inner-container').cloneNode(true);
<script id="flex-3-cell" type="module">
celine.cell("flex-3-cell", () => {
const cloned = document.getElementById('flex-3-container').cloneNode(true);
cloned.querySelector('bh-cite').removeAttribute('id');
return htl.html`<pre class='echo'>${cloned.innerHTML}</pre>`
})
Expand All @@ -272,7 +271,7 @@ <h4>BibTeX</h4>
</script>

<p>
This expands to reference <bh-cite ref="crichton2021nota"></bh-cite>, and is backed by <a href="https://www.npmjs.com/package/@citation-js/plugin-bibtex">@citation-js/plugin-bibtex</a>.
This expands to reference <bh-cite><a href="crichton2021nota">[#?]</a></bh-cite>, and is backed by <a href="https://www.npmjs.com/package/@citation-js/plugin-bibtex">@citation-js/plugin-bibtex</a>.
</p>

<h3>Unstructured text</h3>
Expand All @@ -294,7 +293,7 @@ <h3>Unstructured text</h3>
</script>

<p>
Observe that the reference <bh-cite>dunbar2017</bh-cite> is unchanged.
Observe that the reference <bh-cite><a href="#dunbar2017">[#?]</a></bh-cite> is unchanged.
</p>

<h4>DOI</h4>
Expand All @@ -307,7 +306,7 @@ <h4>DOI</h4>
</script>

<p>
This expands to reference <bh-cite ref="slivaLambert2015"></bh-cite>, and is backed by <a href="https://www.npmjs.com/package/@citation-js/plugin-doi">@citation-js/plugin-doi</a>.
This expands to reference <bh-cite><a href="#slivaLambert2015">[#?]</a></bh-cite>, and is backed by <a href="https://www.npmjs.com/package/@citation-js/plugin-doi">@citation-js/plugin-doi</a>.
</p>

<h4>Wikidata</h4>
Expand All @@ -320,7 +319,7 @@ <h4>Wikidata</h4>
</script>

<p>
This expands to reference <bh-cite ref="birolEtAl2013"></bh-cite>, and is backed by <a href="https://www.npmjs.com/package/@citation-js/plugin-wikidata">@citation-js/plugin-wikidata</a>.
This expands to reference <bh-cite><a href="#birolEtAl2013">[#?]</a></bh-cite>, and is backed by <a href="https://www.npmjs.com/package/@citation-js/plugin-wikidata">@citation-js/plugin-wikidata</a>.
</p>

<h3><code>&lt;bh-bibliography&gt;</code></h3>
Expand All @@ -347,7 +346,7 @@ <h3><code>&lt;bh-bibliography&gt;</code></h3>
<h2>Extras</h2>

<p>
<cite>&lt;bh-cite&gt;</cite> has an appropriate implementation of <code>disconnectedCallback</code> to remove the citation from the bibliography when the <code>&lt;bh-cite&gt;</code> element is removed from the DOM.
<code>&lt;bh-cite&gt;</code> has an appropriate implementation of <code>disconnectedCallback</code> to remove the citation from the bibliography when the <code>&lt;bh-cite&gt;</code> element is removed from the DOM.
</p>

<script id="viewof toggle-citation" type="module">
Expand All @@ -362,7 +361,7 @@ <h2>Extras</h2>
<script id="dynamic-citation" type="module" contenteditable="true">
celine.cell('dynamic-citation', ['toggle-citation'], (toggleCitation) => {
return toggleCitation
? htl.html`<bh-cite>griesemer2020featherweight</bh-cite>`
? htl.html`<bh-cite><a href="#griesemer2020featherweight">[#?]</bh-cite>`
: htl.html`<i>CITATION GONE</i>`;
});
</script>
Expand Down
3 changes: 2 additions & 1 deletion bibhtml/mod.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ export class BibhtmlCite extends HTMLElement {
// get the cloned first link
const clonedA = this.shadowRoot!.querySelector('a');
// swap ? for the reference index
clonedA!.innerText = clonedA!.innerText.replace('?', (this._referenceIndex + 1).toString());
clonedA!.innerText = clonedA!.innerText.replace('#?', (this._referenceIndex + 1).toString());
}
}

Expand Down Expand Up @@ -173,6 +173,7 @@ export class BibhtmlReference extends HTMLElement {
if (this._citationCount == 0) {
// clear the shadow root
this.shadowRoot!.replaceChildren();
return;
}

// gracefully degrade
Expand Down

0 comments on commit ee5d100

Please sign in to comment.