https://inkcairn.so1ve.dev/ Notes on programming languages, small tools, and thoughtful software. https://inkcairn.so1ve.dev/posts/markdown-showcase.html https://inkcairn.so1ve.dev/posts/markdown-showcase.html Thu, 10 Sep 2026 17:59:16 +0800 <h2 id="heading-2"><a class="anchor" href="#heading-2" aria-hidden="true">#</a>Heading 2</h2> <h3 id="heading-3"><a class="anchor" href="#heading-3" aria-hidden="true">#</a>Heading 3</h3> <h4 id="heading-4"><a class="anchor" href="#heading-4" aria-hidden="true">#</a>Heading 4</h4> <h5 id="heading-5"><a class="anchor" href="#heading-5" aria-hidden="true">#</a>Heading 5</h5> <h6 id="heading-6"><a class="anchor" href="#heading-6" aria-hidden="true">#</a>Heading 6</h6> <h2 id="text"><a class="anchor" href="#text" aria-hidden="true">#</a>Text</h2> <p>A paragraph can include <strong>strong emphasis</strong>, <em>gentle emphasis</em>, <em><strong>both at once</strong></em>, or a <del>thought that did not survive editing</del>. Names such as <code>inkcairn.md</code> belong comfortably inline, while an <a href="https://commonmark.org/">ordinary link</a> and an automatic link such as <a href="https://www.rust-lang.org/">https://www.rust-lang.org/</a> remain easy to spot in the source.</p> <hr /> <h2 id="lists-and-small-plans"><a class="anchor" href="#lists-and-small-plans" aria-hidden="true">#</a>Lists and small plans</h2> <p>An unordered list works well for a collection whose order does not matter:</p> <ul> <li>Plain text files</li> <li>A predictable directory layout</li> <li>A build that leaves the source untouched <ul> <li>Posts stay under <code>posts/</code></li> <li>Images stay under <code>assets/</code></li> </ul> </li> </ul> <p>Use an ordered list when sequence does matter:</p> <ol> <li>Write the first draft.</li> <li>Read it away from the editor.</li> <li>Publish only when it says what you meant.</li> </ol> <p>A task list can hold the last few details:</p> <ul class="contains-task-list"> <li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" checked="" disabled="" /> Choose a title</li> <li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" checked="" disabled="" /> Add a useful example</li> <li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="" /> Stop polishing and publish</li> </ul> <h2 id="quotations-and-callouts"><a class="anchor" href="#quotations-and-callouts" aria-hidden="true">#</a>Quotations and callouts</h2> <blockquote> <p>Good tools leave more room for the work itself.</p> <p>A blockquote can hold more than one paragraph, but it should still earn the interruption.</p> </blockquote> <div class="markdown-alert markdown-alert-tip"> <p class="markdown-alert-title">Tip</p> <p>Keep the source simple enough to understand in any text editor. The rendered page can take care of the presentation.</p> </div> <h2 id="tables"><a class="anchor" href="#tables" aria-hidden="true">#</a>Tables</h2> <p>Tables are handy for compact comparisons rather than long prose:</p> <table> <thead> <tr> <th align="left">Source</th> <th align="center">Result</th> <th align="right">Kept in Git</th> </tr> </thead> <tbody> <tr> <td align="left">Markdown</td> <td align="center">Article</td> <td align="right">Yes</td> </tr> <tr> <td align="left">Image</td> <td align="center">Static asset</td> <td align="right">Yes</td> </tr> <tr> <td align="left">Generated HTML</td> <td align="center">Published site</td> <td align="right">No</td> </tr> </tbody> </table> <h2 id="code-and-diffs"><a class="anchor" href="#code-and-diffs" aria-hidden="true">#</a>Code and diffs</h2> <p>Fenced blocks keep code readable and add syntax highlighting to the page:</p> <pre data-language="typescript"><button class="copy-code" type="button" aria-label="Copy code" title="Copy code"><svg class="copy-icon" viewBox="0 0 16 16" aria-hidden="true"><g transform="translate(1 1)"><rect x="5" y="5" width="8" height="8" rx="1"></rect><path d="M3 11H2a1 1 0 0 1-1-1V2a1 1 0 0 1 1-1h8a1 1 0 0 1 1 1v1"></path></g></svg><svg class="copy-success" viewBox="0 0 16 16" aria-hidden="true"><path d="m2.5 8 3 3 8-8"></path></svg></button><code><span class="code-line"><span style="color:light-dark(#cf222e,#ff7b72);">type</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#953800,#ffa657);">Post</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#cf222e,#ff7b72);">=</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#1f2328,#e6edf3);">{</span></span><span class="code-line"><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#953800,#ffa657);">title</span><span style="color:light-dark(#cf222e,#ff7b72);">:</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#0550ae,#79c0ff);">string</span><span style="color:light-dark(#1f2328,#e6edf3);">;</span></span><span class="code-line"><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#953800,#ffa657);">published</span><span style="color:light-dark(#cf222e,#ff7b72);">:</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#953800,#ffa657);">Date</span><span style="color:light-dark(#1f2328,#e6edf3);">;</span></span><span class="code-line"><span style="color:light-dark(#1f2328,#e6edf3);">}</span><span style="color:light-dark(#1f2328,#e6edf3);">;</span></span><span class="code-line"></span><span class="code-line"><span style="color:light-dark(#cf222e,#ff7b72);">const</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#8250df,#d2a8ff);">describe</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#cf222e,#ff7b72);">=</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#1f2328,#e6edf3);">(</span><span style="color:light-dark(#953800,#ffa657);">post</span><span style="color:light-dark(#cf222e,#ff7b72);">:</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#953800,#ffa657);">Post</span><span style="color:light-dark(#1f2328,#e6edf3);">)</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#cf222e,#ff7b72);">=&gt;</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#0a3069,#a5d6ff);">`</span><span style="color:light-dark(#0a3069,#a5d6ff);">${</span><span style="color:light-dark(#1f2328,#e6edf3);">post</span><span style="color:light-dark(#0a3069,#a5d6ff);">.</span><span style="color:light-dark(#1f2328,#e6edf3);">title</span><span style="color:light-dark(#0a3069,#a5d6ff);">}</span><span style="color:light-dark(#0a3069,#a5d6ff);"> · </span><span style="color:light-dark(#0a3069,#a5d6ff);">${</span><span style="color:light-dark(#1f2328,#e6edf3);">post</span><span style="color:light-dark(#0a3069,#a5d6ff);">.</span><span style="color:light-dark(#1f2328,#e6edf3);">published</span><span style="color:light-dark(#0a3069,#a5d6ff);">.</span><span style="color:light-dark(#8250df,#d2a8ff);">getFullYear</span><span style="color:light-dark(#0a3069,#a5d6ff);">()</span><span style="color:light-dark(#0a3069,#a5d6ff);">}</span><span style="color:light-dark(#0a3069,#a5d6ff);">`</span><span style="color:light-dark(#1f2328,#e6edf3);">;</span></span></code></pre> <p>When the change matters more than the surrounding file, a diff says it directly:</p> <pre data-language="ts"><button class="copy-code" type="button" aria-label="Copy code" title="Copy code"><svg class="copy-icon" viewBox="0 0 16 16" aria-hidden="true"><g transform="translate(1 1)"><rect x="5" y="5" width="8" height="8" rx="1"></rect><path d="M3 11H2a1 1 0 0 1-1-1V2a1 1 0 0 1 1-1h8a1 1 0 0 1 1 1v1"></path></g></svg><svg class="copy-success" viewBox="0 0 16 16" aria-hidden="true"><path d="m2.5 8 3 3 8-8"></path></svg></button><code><span class="code-line diff diff-del"><span style="color:light-dark(#cf222e,#ff7b72);">const</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#0550ae,#79c0ff);">status</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#cf222e,#ff7b72);">=</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#0a3069,#a5d6ff);">&quot;</span><span style="color:light-dark(#0a3069,#a5d6ff);">draft</span><span style="color:light-dark(#0a3069,#a5d6ff);">&quot;</span><span style="color:light-dark(#1f2328,#e6edf3);">;</span></span><span class="code-line diff diff-add"><span style="color:light-dark(#cf222e,#ff7b72);">const</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#0550ae,#79c0ff);">status</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#cf222e,#ff7b72);">=</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#0a3069,#a5d6ff);">&quot;</span><span style="color:light-dark(#0a3069,#a5d6ff);">published</span><span style="color:light-dark(#0a3069,#a5d6ff);">&quot;</span><span style="color:light-dark(#1f2328,#e6edf3);">;</span></span></code></pre> <h2 id="images-and-hidden-details"><a class="anchor" href="#images-and-hidden-details" aria-hidden="true">#</a>Images and hidden details</h2> <p>Images use the same familiar syntax as links:</p> <p><img src="/assets/inkcairn.svg" alt="The Inkcairn mark" /></p> <details> <summary>Some details can wait until they are wanted.</summary> <p>This small HTML element is useful for an aside that would otherwise interrupt the article.</p> </details> <h2 id="footnotes"><a class="anchor" href="#footnotes" aria-hidden="true">#</a>Footnotes</h2> <p>A footnote keeps a useful aside nearby without forcing it into the sentence.<sup class="footnote-ref"><a href="#fn-1" id="fnref-1" data-footnote-ref>1</a></sup> The reader can follow it and return to exactly the same place.</p> <section class="footnotes" data-footnotes> <ol> <li id="fn-1"> <p>Footnotes can contain links, emphasis, and other ordinary Markdown. <a href="#fnref-1" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a></p> </li> </ol> </section> https://inkcairn.so1ve.dev/posts/Programming%20Languages/Rust/borrowing-notes.html https://inkcairn.so1ve.dev/posts/Programming%20Languages/Rust/borrowing-notes.html Thu, 10 Sep 2026 17:59:16 +0800 Borrowing is easiest to understand as a statement about relationships rather than punctuation. A reference says that some value remains owned elsewhere and that the current code may use it under a particular set of rules. <h2 id="ownership"><a class="anchor" href="#ownership" aria-hidden="true">#</a>Ownership</h2> <p>Ownership makes resource lifetimes explicit without requiring a garbage collector. More importantly, it gives APIs a vocabulary for saying who may keep a value, who may change it, and when cleanup happens.</p> <h2 id="a-useful-question"><a class="anchor" href="#a-useful-question" aria-hidden="true">#</a>A useful question</h2> <p>When a lifetime annotation feels difficult, ask what relationship the returned value actually has to the inputs. The compiler is often pointing at an unclear contract rather than demanding more syntax.</p> https://inkcairn.so1ve.dev/posts/Programming%20Languages/Rust/error-messages-as-interface.html https://inkcairn.so1ve.dev/posts/Programming%20Languages/Rust/error-messages-as-interface.html Thu, 10 Sep 2026 17:59:16 +0800 An error variant may be designed for a program, but its final message is read by a person who needs to decide what to do next. That makes wording and context part of the interface rather than decoration added at the end. <h2 id="name-the-failed-operation"><a class="anchor" href="#name-the-failed-operation" aria-hidden="true">#</a>Name the failed operation</h2> <p>“Invalid input” says almost nothing. “Cannot read <code>notes/index.md</code>” identifies both the attempted operation and its target. The underlying operating-system error can then explain why it failed.</p> <h2 id="context-should-earn-its-place"><a class="anchor" href="#context-should-earn-its-place" aria-hidden="true">#</a>Context should earn its place</h2> <p>Repeatedly wrapping the same error makes a message longer without making it more useful. Add context at the boundary that knows the concrete operation; let clear errors pass through intermediate layers unchanged.</p> <pre data-language="rust"><button class="copy-code" type="button" aria-label="Copy code" title="Copy code"><svg class="copy-icon" viewBox="0 0 16 16" aria-hidden="true"><g transform="translate(1 1)"><rect x="5" y="5" width="8" height="8" rx="1"></rect><path d="M3 11H2a1 1 0 0 1-1-1V2a1 1 0 0 1 1-1h8a1 1 0 0 1 1 1v1"></path></g></svg><svg class="copy-success" viewBox="0 0 16 16" aria-hidden="true"><path d="m2.5 8 3 3 8-8"></path></svg></button><code><span class="code-line"><span style="color:light-dark(#cf222e,#ff7b72);">let</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#1f2328,#e6edf3);">source</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#cf222e,#ff7b72);">=</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#953800,#ffa657);">fs</span><span style="color:light-dark(#cf222e,#ff7b72);">::</span><span style="color:light-dark(#8250df,#d2a8ff);">read_to_string</span><span style="color:light-dark(#1f2328,#e6edf3);">(</span><span style="color:light-dark(#1f2328,#e6edf3);">path</span><span style="color:light-dark(#1f2328,#e6edf3);">)</span></span><span class="code-line"><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#cf222e,#ff7b72);">.</span><span style="color:light-dark(#8250df,#d2a8ff);">with_context</span><span style="color:light-dark(#1f2328,#e6edf3);">(</span><span style="color:light-dark(#cf222e,#ff7b72);">||</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#8250df,#d2a8ff);">format!</span><span style="color:light-dark(#1f2328,#e6edf3);">(</span><span style="color:light-dark(#0a3069,#a5d6ff);">&quot;</span><span style="color:light-dark(#0a3069,#a5d6ff);">cannot read </span><span style="color:light-dark(#0a3069,#a5d6ff);">{}</span><span style="color:light-dark(#0a3069,#a5d6ff);">&quot;</span><span style="color:light-dark(#1f2328,#e6edf3);">,</span><span style="color:light-dark(#1f2328,#e6edf3);"> </span><span style="color:light-dark(#1f2328,#e6edf3);">path</span><span style="color:light-dark(#cf222e,#ff7b72);">.</span><span style="color:light-dark(#8250df,#d2a8ff);">display</span><span style="color:light-dark(#1f2328,#e6edf3);">()</span><span style="color:light-dark(#1f2328,#e6edf3);">)</span><span style="color:light-dark(#1f2328,#e6edf3);">)</span><span style="color:light-dark(#cf222e,#ff7b72);">?</span><span style="color:light-dark(#1f2328,#e6edf3);">;</span></span></code></pre> https://inkcairn.so1ve.dev/posts/Programming%20Languages/types-and-text.html https://inkcairn.so1ve.dev/posts/Programming%20Languages/types-and-text.html Thu, 10 Sep 2026 17:59:16 +0800 Text is rarely “just a string.” The moment a program needs to compare, display, slice, normalize, or persist it, an implicit model of text becomes part of the design. <h2 id="a-small-observation"><a class="anchor" href="#a-small-observation" aria-hidden="true">#</a>A small observation</h2> <p>Good representations make the common operation obvious. A path is not merely text, a user-facing label is not an identifier, and bytes received from the outside world do not become valid Unicode because a convenient API expects a <code>String</code>.</p> <p>Types are most valuable here when they preserve a distinction the program would otherwise have to remember everywhere.</p> https://inkcairn.so1ve.dev/posts/Programming%20Languages/what-a-type-name-promises.html https://inkcairn.so1ve.dev/posts/Programming%20Languages/what-a-type-name-promises.html Thu, 10 Sep 2026 17:59:16 +0800 A type name is a small promise about the values a program may contain. When the name and the representation disagree, every caller must quietly repair that promise in its own head. <h2 id="prefer-the-domain-word"><a class="anchor" href="#prefer-the-domain-word" aria-hidden="true">#</a>Prefer the domain word</h2> <p><code>String</code> describes storage. <code>Slug</code>, <code>RepositoryUrl</code>, and <code>PublishedDate</code> describe roles. A newtype is worthwhile when the role carries an invariant or prevents two identical representations from being confused.</p> <p>It is less useful when it only moves getters and constructors around without removing decisions from callers.</p> <h2 id="read-the-signatures-together"><a class="anchor" href="#read-the-signatures-together" aria-hidden="true">#</a>Read the signatures together</h2> <p>One function signature can look reasonable in isolation. A module's full set of signatures reveals whether its vocabulary is coherent or whether the same idea appears under several names.</p> https://inkcairn.so1ve.dev/posts/defaults-are-part-of-the-interface.html https://inkcairn.so1ve.dev/posts/defaults-are-part-of-the-interface.html Thu, 10 Sep 2026 17:59:16 +0800 A default is a decision made on behalf of every person who does not stop to configure the software. That makes it more important than most advanced options, even when it occupies only one line of code. <h2 id="the-common-path"><a class="anchor" href="#the-common-path" aria-hidden="true">#</a>The common path</h2> <p>Good defaults make the common path obvious and safe. They should express what the program believes most people mean, while leaving an honest route to the less common cases.</p> <p>The difficult part is resisting defaults that merely hide uncertainty. If the program cannot infer an important choice, asking once is kinder than guessing forever.</p> <h2 id="configuration-has-a-cost"><a class="anchor" href="#configuration-has-a-cost" aria-hidden="true">#</a>Configuration has a cost</h2> <p>Every option adds documentation, combinations, and states that future changes must preserve. Before adding one, it is worth asking whether the underlying behavior is actually stable enough to deserve a permanent switch.</p> https://inkcairn.so1ve.dev/posts/reading-old-code.html https://inkcairn.so1ve.dev/posts/reading-old-code.html Thu, 10 Sep 2026 17:59:16 +0800 Old code is easiest to misunderstand when approached as a cleanup exercise. Before changing it, I try to learn which constraints shaped it and which of those constraints still exist. <h2 id="begin-at-the-boundary"><a class="anchor" href="#begin-at-the-boundary" aria-hidden="true">#</a>Begin at the boundary</h2> <p>The public entry point usually tells a clearer story than the helpers beneath it. Follow one ordinary input through the program before collecting suspicious functions or unusual branches.</p> <h2 id="keep-an-evidence-list"><a class="anchor" href="#keep-an-evidence-list" aria-hidden="true">#</a>Keep an evidence list</h2> <p>I write down three kinds of observations:</p> <ul> <li>behavior that callers visibly depend on;</li> <li>complexity caused by a requirement that still exists;</li> <li>complexity whose original requirement can no longer be found.</li> </ul> <p>The third list is where simplification begins, but only after the first two are understood.</p> https://inkcairn.so1ve.dev/posts/reposted-essay.html https://inkcairn.so1ve.dev/posts/reposted-essay.html Thu, 10 Sep 2026 17:59:16 +0800 Reposted from An essay from somewhere else by Alex Example, published 2024-06-15: https://example.com/original-essay. This fictional repost demonstrates how Inkcairn credits an original author and points readers back to the source without hiding the local copy. <aside class="repost-notice" aria-label="Original source"> Reposted from <a href="https://example.com/original-essay" rel="external">An essay from somewhere else</a> by Alex Example, published <time datetime="2024-06-15T00:00:00Z">2024-06-15</time>. </aside><h2 id="keep-the-source-visible"><a class="anchor" href="#keep-the-source-visible" aria-hidden="true">#</a>Keep the source visible</h2> <p>A repost should make its origin obvious before the reader reaches the article body. Attribution is part of the content, not a footnote added as an afterthought.</p> <p>The local page can remain useful for reading and searching while its canonical URL identifies the original publication.</p> <h2 id="preserve-the-reading-experience"><a class="anchor" href="#preserve-the-reading-experience" aria-hidden="true">#</a>Preserve the reading experience</h2> <p>Good syndication keeps the article readable, carries its source into feeds, and avoids presenting someone else's work as original writing.</p> https://inkcairn.so1ve.dev/posts/tools-that-disappear.html https://inkcairn.so1ve.dev/posts/tools-that-disappear.html Thu, 10 Sep 2026 17:59:16 +0800 The small tools I trust most become almost invisible during use. They preserve the shape of the task, respond quickly, and leave behind results that do not depend on the tool remaining installed forever. <h2 id="quiet-by-design"><a class="anchor" href="#quiet-by-design" aria-hidden="true">#</a>Quiet by design</h2> <p>A quiet tool does not need to be featureless. It can have strong opinions while keeping those opinions close to the problem it solves.</p> <p>The difference is visible in the output: ordinary files, familiar protocols, and names that still make sense when inspected by hand.</p> <h2 id="a-useful-test"><a class="anchor" href="#a-useful-test" aria-hidden="true">#</a>A useful test</h2> <p>If removing the tool would also make its output difficult to understand, the tool may have captured too much of the work.</p> https://inkcairn.so1ve.dev/posts/software-that-keeps-working.html https://inkcairn.so1ve.dev/posts/software-that-keeps-working.html Thu, 14 Sep 2023 00:00:00 +0000 Longevity rarely comes from predicting every future requirement. It comes from choosing inputs and outputs that remain understandable when the implementation between them has to change. <h2 id="durable-edges"><a class="anchor" href="#durable-edges" aria-hidden="true">#</a>Durable edges</h2> <p>Plain text, documented URLs, and standard formats are not exciting choices, but they give future software something stable to meet. The internals can then be rewritten without turning every old document into a migration project.</p> <h2 id="fewer-hidden-obligations"><a class="anchor" href="#fewer-hidden-obligations" aria-hidden="true">#</a>Fewer hidden obligations</h2> <p>Persistence creates promises. A cache can be deleted; an authored document cannot. Treating those two kinds of data differently keeps defensive machinery focused where losing information would actually matter.</p>