Expounder is a very small JS/CSS library that lets article writers hide text behind a link, and allows readers to click that link to expand the text. It is born out of some frustration I had when reading tutorials and other books. I would frequently be familiar with one part of the source material, but have no way to skip it and only read the parts I was unfamiliar with. I thought that HTML was too powerful for this to not be a thing, so I spent a few minutes writing up a simple prototype implementation.
Expounder is for authors of mainly educational articles/texts who want to save readers time and preserve their attention by letting the latter select what they want the article to elaborate on. Usually, tutorials go into great detail without giving you an option. Expounder allows authors to only expose a high-level view of the topic to their audience, and enable the latter to select what they need to read more about. This is done in a very natural way that preserves cohesion with the rest of the text.
The best way to explain what Expounder does is with a demo. Here is a sample that uses Expounder (click the dashed-underlined links to read more on a topic):
Quantum mechanics (QM; also known as quantum physics or quantum theory) including quantum field theory (a theoretical framework for constructing quantum mechanical models of subatomic particles in particle physics and quasiparticles in condensed matter physics), is a fundamental branch of physics concerned with processes involving, for example, atoms and photons. An atom is the smallest constituent unit of ordinary matter that has the properties of a chemical element. Every solid, liquid, gas, and plasma is composed of neutral or ionized atoms. A photon is an elementary particle, the quantum of all forms of electromagnetic radiation, including light. It is the force carrier for the electromagnetic force, even when static via virtual photons. In such processes, said to be quantized, the action has been observed to be only in integer multiples of the Planck constant, a physical quantity that is exceedingly, indeed perhaps ultimately, small. This is utterly inexplicable in classical physics, which refers to theories of physics that predate modern, more complete, or more widely applicable theories.
The wave function provides information about the probability amplitude of position, momentum, and other physical properties of a particle.
Clone the repo and add the files to your project, or just add these two lines to your HTML:
Then write your HTML like this:
And you're done! You aren't limited to spans, you can set any element you want as either the expounder or expounded element.
If you want either the expounder or expounded elements to be styled
differently, you can use the *[data-expounder] and
*[data-expounded] selectors.
For example, the following CSS will style an expounded span
to always be italics:
To make it easier for you to use Expounder and your readers to have the best experience, here are some guidelines you should keep in mind when writing:
The link should be a specific term or sentence fragment, so users have a good idea of what they'll see when they click. The explanation should be concrete and clear. Keep the two types of users in mind (users familiar and unfamiliar with the term), and write the explanatory text as if you're talking directly to someone who doesn't know what the linked term means.
Avoid adding information to the explanation that isn't about the link, and only about the link. Otherwise, you risk forcing the user to expand every link just to find where you've hidden useful information.
The explanation should fit as well as possible in the rest of the text. Ideally, the text should read equally well with the explanatory sentences hidden as well as visible, flowing normally for both users who are familiar and unfamiliar with the linked term.
This was the first post I wrote that used Expounder, and I think it's a good example (try farther down, the first few usages are just an introduction).
If you've used Expounder somewhere, please let me know and I'll link to your thing here, if I think it illustrates its usage well!
If you have any feedback or problems, please feel free to open an issue on the project page. I'm pretty opinionated, so I might not end up accommodating you, but well-reasoned arguments help!
You can also get me on Twitter, if you prefer.
Enjoy!
Made with ♥️ in Greece.