blog-static/index.md at 3e97fdcfea6d7a3ed48ce61a194eab97106e58dd

Danila Fedorin 4fd6dd5606 Make minor edits to article and update theme

Signed-off-by: Danila Fedorin <danila.fedorin@gmail.com>

2024-06-24 19:59:51 -07:00

24 KiB

Raw Blame History

title

date

Sidenotes

Gwern is, in my view, the king of sidenotes. Gwern's writing makes very heavy use of them (at least based on the articles that I've read). This is where I originally got inspiration for [my own implementation in Hugo]({{< relref "sidenotes" >}}). Check out the page on hydrocephalus for an example; Here's what a piece of that page looks like on my end at the time of writing:

{{< figure src="gwern-sidenotes.png" class="fullwide" caption="A screenshot of Gwern's page on hydrocephalus" alt="A screenshot of Gwern's page on hydrocephalus. The main article text is accompanied by notes in both the left and right margin." >}}

Sidenotes are nice because they allow for diversions without interrupting the main article's flow. You can provide additional details for the curious reader, or --- as Gwern does --- use the sidenotes for citing studies or sources. In either case, the reading experience is significantly more pleasant that footnotes, for which you typically have to go to the bottom of the page, and then return to the top.

Another reason I called Gwern the "king of sidenotes" is this page on sidenotes. There, Gwern documents numerous approaches to this feature, mostly inspired by Tufte CSS. The page is very thorough --- it even includes a link to my own work, as unknown as it may be! I would recommend checking it out if you are interested in enhancing your site with sidenotes.

Tables of Contents

Not all personal sites include tables of contents (TOCs), but they are nice. They serve two purposes:

Seeing at a glance what the post will be about, in the form of headings.
Being able to navigate to an interesting part of the page without having to scroll.

Static site generators (I myself use Hugo) are typically able to generate TOCs automatically, since they are already generating the HTML and know what headings they are inserting into the page. For instance, Hugo has TableOfContents. I suspect the same is true for other existing website technologies.

Despite this, I actually had to look relatively long to find sites I frequent that have TOCs to show off as examples here. The first one I came across --- after Gwern's, whose site will be mentioned plenty in this post anyway --- is Faster than Lime. Take this post on Rust's Futures; this is what the top of it looks like at the time of writing:

{{< figure src="fasterthanlime-toc.png" class="small" caption="A screenshot of the table of contents on Faster than Lime" alt="A screenshot of the table of contents on Faster than Lime. A box with the word "Contents" contains links to several sections on the page bellow (off screen)" >}}

The quality and value of TOCs certainly depends on the sections within the page itself --- and whether or not the page has sections at all! --- but in my opinion, the benefits to navigation become apparent even for relatively simple pages.

As an honorable mention, I'd like to show Lars Hupel's site. The pages on the site don't --- as far as I can tell --- have internal tables of contents. However, pages that are part of a series --- such as the introduction to CRDTs --- have tables of contents that span the entire series.

{{< figure src="lars-toc.png" class="small" caption="A screenshot of the table of contents on Lars Hupel's site" alt="A screenshot of the table of contents on Lars Hupel's site. A box with the words "Series Navigation" contains links to several other pages in the series." >}}

I also find this very nice, though it does miss out on headings within a page.

Bonus: Showing Page Progress

I've mentioned that tables of contents can communicate the structure of the page. However, they do so from the outset, before you've started reading. In their "base form", the reader stops benefiting from tables of contents {{< sidenote "right" "jump-top-note" "once they've started reading." >}} That is, of course, unless they jump back to the top of the post and find the table of contents again. {{< /sidenote >}}

If you want to show progress while the reader is somewhere in the middle of a page, you could use a page progress bar. I've noticed one while reading Quanta Magazine; it looks like this (recording my scrolling through the most recent article at the time of writing).

{{< figure src="quanta-scroll.gif" class="fullwide" caption="The progress bar on a Quanta Magazine article" alt="The progress bar on a Quanta Magazine article. As the page scrolls, an orange bar at the top gradually fills up from left to right." >}}

One immediate thought is that this is completely superseded by the regular browser scroll bar that's ever-present at the side of the page. However, the scroll bar could be deceiving. If your page has a comments section, the comments could make the page look dauntingly long. Similarly, references to other pages and general "footer material" count towards the scroll bar, but would not count towards the progress bar.

Combining the two, you could imagine an always-visible table of contents that highlights the current section you're in. With such a feature, you can always see where you are (including a rough estimate of how far into the page you've scrolled), and at the same time see how the current section integrates into the broader structure. I've seen this done before, but could not find a site off the top of my head that implements the feature; as a fallback, here's the CSS tricks tutorial that shows how to implement a dynamic table of contents, and a recording of me scrolling through it:

{{< figure src="csstricks-toc.gif" class="fullwide" caption="The table of contents from a CSS Tricks demo" alt="The table of contents from a CSS Tricks demo. As the page scrolls, the current section in the table of contents becomes bold." >}}

Easily Linkable Headings

How can you link a particular section of a page to your friend? There's a well-defined mechanism to do this in HTML: you can use the ID of a particular HTML element, and add it as #some-id to the end of a link to the page. The link then takes the user to that particular HTML element. I can do this, for instance, to link to the sidenotes section above.

How does one discover the ID of the part of the page that they want to link to? The ID is not a "visual" property; it's not displayed to the user, and is rather a detail of HTML itself. Thus, on any given page, even if every element has a unique, linkable ID, I can't make use of it without going into Inspect Element and trying to find the ID in the HTML tree.

The simple solution is to make the elements that you want to be easily "linkable" into links to themselves! Then, the user can right-click the element in question (probably the heading) and click Copy Link. Much easier! To demonstrate a similar idea, here is a link to this paragraph itself. You can now use the context menu to Copy Link, put it in your browser, and voilà --- you're right back here! {#linked-paragraph}

As with tables of contents, many website technologies provide most of the tooling to add support for this feature. Relatively often I come across pages that have unique IDs for each header, but no clickable links! I end up having to use inspect element to find the anchor points.

A variation on this idea --- if you don't want to make the entire heading or title a link --- is to include alongside it (before or after) a clickable element that is a link to that title. You can click that element to retrieve link information, instead (and the icon additionally tells you that this is possible). Hugo's documentation does this: here's a screenshot of an arbitrary page.

{{< figure src="hugo-titlelink.png" class="small" caption="A title and paragraph from the Hugo documentation" alt="A title and paragraph from the Hugo documentation. Next to the title there is a blue link symbol." >}}

Grouping Series of Posts

Some authors like to write at length on a particular topic; to get the content out to readers faster (and to make the resulting pages less daunting), it makes sense to break a single topic up into a series. The easiest way to do this is to just... publish several articles, possibly with related names, and link them to each other. Done!

With a little more effort, though, the series-reading and series-writing experience could be nicer. Instead of manually inserting links, you could configure your website to automatically add a "next" and "previous" button to pages in a given series. You could also give an overview of a particular series and create a "navigation hub" for it.

As an example, the Chapel language blog has navigation buttons. Here's a screenshot from a post in the Advent of Code series:

{{< figure src="chapel-seriesnav.png" class="fullwide" caption="Series navigation buttons on a Chapel blog post" alt="Series navigation buttons on a Chapel blog post. There are two buttons; one links to a previous page in the series, another links to the next." >}}

I've mentioned this in the section on tables of contents, but Lars Hupel's site has tables of contents that link between series. I'm not sure if it's automatically generated or hand-written, but it's definitely nice.

Dialogues

I first came across dialogues on Xe Iaso's site, but I think I see them used most often in posts on Faster than Lime. As an example, here's a little dialogue on a post about Rust's futures. At the time of writing, it looks like this:

{{< figure src="fasterthanlime-dialogue.png" class="medium" caption="A dialogue with "cool bear" on Faster than Lime" alt="A dialogue with "cool bear" on Faster than Lime. The page contains chat bubbles that alternate between a bear character and the author." >}}

Using dialogues --- even for technical writing --- is not a particularly novel idea. I know I've seen it in a textbook before; probably this part of Operating Systems: Three Easy Pieces. It can help ask questions from a less-experienced point of view, and therefore possibly voice concerns that a reader might themselves be having. And of course --- as with "cool bear" and Xe Iaso's many characters --- it can change the tone and make the page a bit more fun.

Code Blocks with Origin

This one was recommended to me by a reader, and so I'll be talking about my page specifically!

When I was [writing about making a compiler]({{< relref "series/compiling-a-functional-language-using-c++" >}}), a reader emailed me and pointed out that they were getting lost in the various code blocks. My page displayed the code that I was writing about, but the project had grown beyond a single file. As a result, I'd be making changes midway through one file at one moment, and another file the next. This prompted me to add decorators to my code blocks that look something like this:

The decorator says what file the code is from, as well as what lines are being presented. If you click the file name, the decorator links to my Gitea instance, allowing you to read the code in context.

Though it's not quite the same (in particular, it's unfortunately missing links), the Crafting Interpreters online book does something similar. It describes changes to the code in words next to the changed code itself, like "added after MyStruct". Here's a screenshot of the page on local variables at the time of writing.

{{< figure src="craftinginterpreters-codenotes.png" class="fullwide" caption="Location notes on code in Crafting Interpreters" alt="Location notes on code in Crafting Interpreters. On the right of code blocks, a margin note describes the file and nature of the change." >}}

I think it looks quite elegant, and in some ways --- specifically in the verbal descriptions of what each change does --- might be superior to my approach.

It's not quite the same thing, but GitHub Gists can help approximate this feature. A Gist could contain multiple files, and each file can be individually embedded into your page. Hugo in particular has built-in support for Gists (and I've snagged that link using the docs' easily linkable headings); I suspect that other website engines have some form of support as well. At the time of writing, an embedded Gist looks something like this:

{{< figure src="hugo-gist.png" class="small" caption="Code embedded in Hugo documentation using a GitHub Gist" alt="Code embedded in Hugo documentation using a GitHub Gist." >}}

Clicking list.html takes you to the source code of the file.

Bonus: Code Blocks with Clickable Links

If we're going for fancy code blocks, another fancy feature is provided by the Agda programming language. Agda can generate HTML code blocks in which every symbol (like a variable, record name, function name) are linked to where they are defined. So if you're reading the code, and wonder "what the heck is x?", you can just click it to see how it's defined.

It's not simple to integrate Agda's plain HTML output into an existing webpage, but some projects do that. I took a stab at it in my [post about integrating it with Hugo]({{< relref "agda_hugo" >}}). I wager this would be even harder for other languages. However, it leads to nice results; my go-to is Programming Languages Foundations in Agda. The online book introduces various concepts from Programming Language Theory, and each code block that it shows is fully linked. This makes it possible to jump around the page like so:

{{< figure src="plfa-goto.gif" class="fullwide" caption="Navigating code blocks on a page from PLFA" alt="Navigating code blocks on a page from PLFA. I hover over then click a plus sign to see how addition is defined. I then do the same to see how natural numbers are defined." >}}

Markers for External Links

Some sites I've seen mark links that go to a different domain with a little icon. If you've read this far, you've likely noticed that my site does the same. Another good example of this --- even though the CSS is little rough at the time of writing --- is James' Coffee Blog ☕. I've taken the (small) liberty to adjust the color of the icon, which I suspect is buggy in my browser.

{{< figure src="jamesg-external.png" class="fullwide" caption="An external link on James' blog" alt="An external link on James' blog. The link is displayed as normal, and an additional diagonal arrow aiming up and to the right and surrounded by a square is displayed to the right of the link text." >}}

Some websites (~~this one included~~) also make such links open in a new tab automatically. That way, you tend to not lose the original article by clicking through one of its references.

Bonus: Different Markers for Different Destinations

Gwern's website takes this idea further, by changing the icon for external links depending on the destination. For instance, links to Wikipedia articles are stylized with a little "W", links to Haskell.org are stylized using a lambda ((\lambda)), and links to .zip files have a little archive icon. There are more; ~~I've found the link processing code on GitHub, and even the list of websites that get their own icons.~~ I could not find a verbal description, though.

Edit: Gwern has pointed out that the links I provided go to obsolete code. The link processing functionality is documented in comments here and the link icon rules are here. A non-code list of icons exists too.

Now for some pictures. Here are a ton of links from the "About" page!

{{< figure src="gwern-linkicons-wiki.png" class="fullwide" caption="Links to Wikipedia on Gwern's site" alt="Links to Wikipedia on Gwern's blog. Each link is followed by a superscript "W"." >}} {{< figure src="gwern-linkicons-haskell.png" class="fullwide" caption="A link to Haskell.org on Gwern's site" alt="A link to Haskell.org on Gwern's blog. The link is followed by a superscript lambda." >}} {{< figure src="gwern-linkicons-zip.png" class="fullwide" caption="Links zip files on Gwern's site" alt="Links zip files on Gwern's site. Each link is followed by an archive icon." >}}

Bonus: Link Preview

Gwern's website has no shortage of cool ideas. Among them showing link previews on hover. When hovering over a link, the site displays a popup window that contains a view into that page. I suspect that this view is also archived somehow, so that it retains a view into the page that matches it at the time of writing.

To be perfectly honest, I found this feature a little jarring at first. As I would try to click links, I would get surprised by an additional overlay. However, as I spent more time browsing the site, I grew quite accustomed to the previews. I would hover over a link to see the first paragraph and thus get a short synopsis. This worked really well in tandem with per-destination marker icons; I could tell at a glance whether a link was worth hovering over.

Here's what it looks like:

{{< figure src="gwern-hover.gif" class="medium" caption="Hovering over a link on Gwern's site" alt="Hovering over a link on Gwern's site. After the link is hovered over, a rectangular popup displays a section of the Wikipedia page the link goes to. I scroll through the section to the table of contents." >}}

RSS Feeds

RSS is a feed standard that allows sites to publish updates. Blogs in particular can make use of RSS to notify readers of updates. RSS feeds are processed by a feed reader, which is a program that polls a website's index.xml file (or other similar files) and reads it to detect new content. If you opt in to full-text RSS feeds, users can read the entire post entirely from their reader.

RSS makes it easier to keep up with your site. Rather than having to check in on every author whose content I enjoy on the internet, I can add their feed URL to my list, and have my feed reader automatically aggregate all updates for me to read. It's kind of like a social media or news feed, except that I control what's shown to me, and authors of the blogs I follow don't need to create accounts and explicitly share their work on social media!

I don't have any particular website to show off in this section; instead I'll show you a list of websites that I'm following in my feed reader of choice. You might notice that a lot of these websites are listed here as inspiration for other microfeatures.

{{< figure src="feedbin.png" class="small" caption="A screenshot of my Feedbin list" alt="A screenshot of my Feedbin list. Some sites include Hillel Wayne's, Faster than Lime, Drew DeVault, and the Chapel Language Blog" >}}

Links to Other Sites

This feature I first noticed on Drew DeVault's blog. Every page on Drew's blog, at the bottom, has a section titled "Articles from blogs I read". For instance, on a sample post, at the time of writing, I'm seeing the following footer:

{{< figure src="drew-openring.png" class="fullwide" caption="Links to other blogs from Drew DeVault's blog" alt="Links to other blogs from Drew DeVault's blog. The links consist of three side-by-side boxes, each with a title and brief excerpt." >}}

As indicated in the image, Drew's site in particular uses a program called openring, which is based on RSS feeds (another microfeature I love). However, how the site finds such articles (statically like openring, or on page load using some JavaScript) isn't hugely important to me. What's important is that you're promoting other content creators whose work you enjoy, which is the ethos of my favorite slice of the internet.

Conclusion + Anything Else?

Those are all the microfeatures that I could think of in a single sitting. I hope that you have been inspired to integrate features like these into your own site, or at the very least that you think doing so would be a good idea.

This list isn't exhaustive. I've probably missed some good microfeatures! If you can think of such a feature, let me know; my email address is linked in the footer of this article.

Thank you for reading, and cheers!

24 KiB Raw Blame History