Added site search, and more

Implemeation of Site Search

The Site Search feature allows you to search the body text and titles of all articles on this site. Since there weren’t so many articles that it didn’t require any special effort.

Here’s how it works: I’ve prepared en.index.json, which stores the text data for all articles in, and the browser dynamically renders the search results (by constructing the DOM) by loading this file. In other words, the search queries will nerver be sent to the server. In addition to this the method that prioritizes privacy above all else, it’s also the most simple approach since there are almost no server-side considerations to worry about.

By the way, the JSON file is currently about 200 kB in size, which is roughly equivalent to 0.5 PNG images (or 6 WebP images). Isn’t it lighter than regular browsing? I think there will be almost no problem even if the number of articles increases in the future, but I might change it if I feel like trying something new.

Navigation elements at the top of the page

I’ve added links to the “Site Map” and “Site Search” at the top of the page. This isnot only to address the fact that users don’t always scroll all the way down to the navigation at the bottom of the page, but also intended to assist users of screen readers. Since those links are located near the top, screen readers reach it immediately just after starting to read the page, allowing those who need navigation to notice it more quickly.

Metadata using JSON-LD

This improvement is primarily intended for web crawlers rather than human users.

I believe I’ve been describing enough metadata on this site, such as by using appropriate HTML tags and inserting meta tags based on the Open Graph Protocol (OGP). However, since HTML is designed just for marking up structured documents and OGP is designed only for sharing on social media, neither of these approaches could fully capture the potential metadata inherent in real-world web pages [^1].

In that sense, JSON-LD based on the specifications of schema.org is extremely precise and comprehensive, allowing for the description of metadata for a wide variety of entities. I might have included so much metadata on this site that it might even seem excessive — if you’re interested in, please check it out by selecting “View Source” from your browser’s right-click menu.

Semantically re-struction of the articles

The content within the <article> elements in all articles is now re-structured using <section> elements. While this is not necessary in modern browsers, I just decided to give it a try and implemented it.

Specifically, what I’ve done is simply reading through the original HTML document in order of heading level (from lowest to highest) by a script, and whereever the script encounter a heading element (<h2> ~ <h6>), it make the section leading up to the next heading element of the same level a child of the <section> element. I used the Hooks feature in PureBuilder Simply, so it wasn’t particularly difficult.

Exact dates and times

Needless to say, keeping track of exactly what was done at what time and second should be automated. Until now, I had been manually managing articles based solely only on the date published, while date and time of updates were left the system. This meant that even minor changes would cause the update date to fluctuate constantly, which was a source of frustration. While this might seem trivial to humans, when it comes to feed readers subscribed to this site’s Atom feed, it becomes a problem. This is because almost all the feed readers sort entries by update date and time, so frequent updates to the same article can cause direct stress for subscribers.

However, managing “exact dates and times” in and of itself wasn’t that difficult; the real problem was that, I, as the administrator of this website, needed to be able to “manipulate time as I wish” This is because the files published on this site had various individual circumstances—ranging from “files created through multiple copies where the original creation date is unknown” to “files that were updated but I wanted to treat as if they hadn’t been updated” or “files for which I wanted to set the publication date to a time before the website was even launched”—making it impossible to handle them uniformly.

In the end, I resolved this by a brute-force solution: automatically appending two pieces of information—the “date and time the HTML was first generated” and the “date and time of the last update” — to the frontmatter section at the beginning of the original file (Markdown) that I wrote. Since this is written in text format within the same file as the main content, editing is intuitive, and it’s also easy to set a flag within the same metadata to “do not append the update date and time.” For past dates where the time is unknown, I’ve followed the common practice of assigning 00:00:00.

Optimization the sidebar

Until now, this site had been displaying the same sidebar (author information and contact details) on both the English and Japanese pages, but since this seemed to cause confusion, I’ve decided to display separate sidebars for each language. For pages that do not have the English/Japanese switch link at the top of the page — or for users who may not have noticed it — I’ve kept the navigation at the bottom of the page the same.

Discontinuing the display of code block captions via CSS

Until now, code block captions were displayed by setting an attribute such as data-caption="text" to the <div class="sourceCode"> element and using the CSS ::before selector; however, this made it impossible to select the text, which caused some inconvenience. I have completely discontinued this approach and switched to using <span class="caption">text</span>.

Semantically separated command prompts from code blocks to improve the imitation of terminal window

When imitating a terminal window on a web page, it’s common to use a code block. While including a command prompt (such as $) at the beginning of each lines makes it easier to understand, there’s a problem: if you include the command prompt in the code itself, it causes syntax highlighting to behave incorrectly.

I’ve addressed this by automatically inserting the command prompt into code blocks marked with the .console class.

I know you are feeling what I say does not make sense, so let me show you the difference.

$ sudo pacman -Syu

<div class="sourceCode" id="cb1"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="ex">$</span> sudo pacman <span class="at">-Syu</span></span></code></pre></div>

$ sudo pacman -Syu

<div class="sourceCode" id="cb3"><pre class="sourceCode sh console"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="prompt">$ </span><span class="fu">sudo</span> pacman <span class="at">-Syu</span></span></code></pre></div>