Hello, essay-hub

A short working example that exercises every feature: a citation, glossary tooltips, an interactive chart, and an interactive map with a PDF fallback.

Download: HTML · PDF

This essay exists to prove the pipeline works. It cites a source, defines terms, expands one point in a note, embeds images singly and in a gallery, draws a chart and a timeline from data files, and puts markers on a map. If you can hover, zoom, and click your way through it, every feature of this repository is working.

Citations

Orwell argued that vague language is not a cosmetic problem but a thinking problem: “if thought corrupts language, language can also corrupt thought” (Orwell 1946). The citation you just passed came from one BibTeX entry in _shared/references.bib; hover it in the HTML version and the full reference appears. The reference list at the end builds itself.

Definitions and notes

A term marked in the source as [tooltip]{.def} becomes a tooltip — rest your pointer on it, or tap it on a touch screen. Definitions live in plain YAML glossary files: shared glossaries in _shared/glossaries/, linked from the essay’s front matter (glossaries: [publishing]), and essay-specific terms next to the essay. In the PDF, marked terms appear in small caps instead, and every term used is listed in a Glossary section before the references.

A definition says what a word means. When a passage needs expanding rather than defining, use a note¹Like this one. A note carries an aside, a qualification, or a pointer to further reading — anything that earns its place on the page but would clog the sentence. Write it inline as ^[the note text]. — hover or tap the marker in HTML, or find it at the foot of the page in the PDF.

Charts

Charts are code blocks that run at build time and read from the essay’s own data/ folder. Figure 1 is interactive in HTML — hover for values, drag to zoom — and exports as a static image in the PDF.

Figure 1: Words written per month while building this repository (sample data).

Timelines

A timeline is a horizontal line with a node at each event. Figure 2 marks five periods of Orwell’s working life (Taylor 2003) from data/timeline.csv — each node sits at the period’s start, labels alternate above and below the line, and hovering a node shows the span and the note. Because it is an ordinary Plotly figure, the PDF gets a static image with no extra work.

Figure 2: Five periods of Orwell’s working life. Hover a node for the span and what it produced.

Images

An image alone on its own line becomes a block figure: the text splits above and below it, nothing wraps beside it, and it carries a caption and alt text. Figure 3 is a single image.

Figure 3: Four layered waves in blue — a sample image generated for this essay.

Several related images do not need a wall of pictures: a div marked {.gallery} puts them in one frame that readers click through with the arrows — or swipe, on a touch screen. Each image’s bracket text travels with it as caption and alt text, and the counter shows where you are.

Plate one: the same waves in orange. 1 / 3

Plate two: the same waves in green. 2 / 3

Plate three: the same waves in violet. 3 / 3

In the PDF, where nothing can be clicked, the gallery unrolls: each image appears in order with its caption.

Maps

Figure 4 plots four places where Orwell lived and wrote (Taylor 2003), from data/sites.csv. Every substantive data point in an essay is sourced: a citation in the prose, and an entry in the essay’s data/sources.yml naming where each data file comes from. A figure whose data file has no entry is flagged in place with an “unsourced data” badge. In HTML it is a live Leaflet map: pan, zoom, and hover a marker for the note. The background is a tile layer from OpenStreetMap. PDF cannot embed a live map, so the PDF version switches in a static image from assets/.

Make this Notebook Trusted to load map: File -> Trust Notebook

Figure 4: Places where Orwell lived and wrote. Hover a marker for the note.

What this proves

One plain-text file produced everything above: the hoverable citation, the tooltips, the note, the images, the chart, the timeline, the map, and — from the same source — a PDF. Copy this essay’s folder to start your own.

Glossary

alt text

The written description of an image that a screen reader speaks aloud, and that a browser shows when the image cannot load. Good alt text says what the image shows, briefly, for a reader who cannot see it.

BibTeX

A plain-text format for bibliographies. Each source is one block with a citation key, and documents cite by that key rather than repeating the reference.

tile layer

The grid of small square images that forms the background of an interactive map. The map loads only the tiles for the area and zoom level in view.

tooltip

A small box of explanatory text that appears when the pointer rests on a word or element, and disappears when it moves away.

References

Orwell, George. 1946. “Politics and the English Language.” Horizon 13 (76): 252–65.

Taylor, D. J. 2003. Orwell: The Life. Chatto & Windus.