DRAFT: Style guide

Updated January 2026

INTRODUCTION a

i make this style guide so i can link people to explanations for design decisions, and also as a playground to test new CSS rules. doubles as a colophon, and triples as an insight to my writing and development process.

let's start with ___.

BASIC RULES a

text only! so i can focus on writing and design fundamentals (layout, whitespace, information hierarchy)

inspiration:

stubbornly maintaining a flawed, naive style. not always the most usable, but definitely minimal.

no images or inline media; only text. even the decorations -- only ascii, no 1px borders.

interactive pages and web experiments and media-focused pages get bespoke styles and belong elsewhere on my site, not /posts. example - /notebook-love, /whiteboard.

all static, aim for zero interaction. means no buttons, no javascript. but perhaps break the rules once in a while on special occasions.

no favicon

no footer. again, what truly matters on a webpage / on my personal site? some navigation, sure. but a footer? nothing important to put there imo. could put some nav links. should probably put a "to top" link. also a nice gesture to save someone from the frantic scroll to the top. also related links and useful data in footer like dorian taylor would be cool. but meh,for now i don't feel an urge to include a footer.

let me showcase some elements now.

SOME HTML ELEMENTS a

a handful of <h2>s on a page, and maybe a few <h3>s. not entirely settled on h3 stylel, but here's how they look for now:

HERE IS AN H3

never used an h4, and i never plan to! weak writing i think, to be so deeply nested.

i learned early on to manually uppercase my h2s and h3s, because css uppercase silently strips things. certain punctuation and spacing iirc? TODO: confirm.

little anchor tag for subheading link inspired by some old 1990s-2000s barebones html academic website. a lonely a, just floating on the right side of the page. i wish i had an example link. if you come across such a site with those little right-aligned a tags for subheadings, let me know. i'd be eternally grateful. it's one of my biggest bugbears that i'm missing a reference to that piece of inspiration.

no <img>, <audio> or <video> tags. if want to show any media, i just link it like img.jpg, audio.mp3, or video.mp4. this is bad for screen readers iirc. sorry! locked in to a poor design decision. i try to compensate for these evils by making all my other sites super-accessible.

sometimes a flourish? flueron? dinkus? to segue between shifting ideas, or to let a heavy idea breathe, while remaining in the same <h2>.

a blockquote

i put paragraphs in blockquotes. contents should be italicized. there's a border on the side, along with a little padding.


another paragraph here. i don't usually use cite elements. maybe one day.

a block of code

let mut pargs = pico_args::Arguments::from_env();
if pargs.contains(["-h", "--help"]) {
    print!("{}", HELP_MSG);
    std::process::exit(0);
}
if pargs.contains(["-v", "--version"]) {
    print!("{}\n", env!("CARGO_PKG_VERSION"));
    std::process::exit(0);
}

also good for unwordwrapped text and ascii diagrams. like in /posts/chafa-ffmpeg-progress or /posts/monospace-dump:

TODO: find plaintext unformatted snippet
like ffmpeg logs in /posts/chafa-ffmpeg-progress

MORE ELEMENTS a

the header and h1. sometimes i'll stick a demo.mp4 in here, especially if not included in the first paragraph. example: /posts/blindfolded-deployment.

prefixing title and h1 with DRAFT, as a reminder to self, and in case i share with others. sentence case, not title case. looks a bit amateur at times, but title case looks a bit serious, so idk.

date of publication is month yyyy. enough detail to place in the stream of time, and nothing more. i publish a few times a year, but not multiple times a month, so this is fine.

for evergreen posts (tagged #ongoing on the homepage), use date last updated instead of date published. too noisy to include both, and the publication date becomes less important.

the nav?

due to monospace font, prose paragraphs don't look good if too long. ideally broken up often by lists and figures and subheadings. depends on the content tho. like /posts/emoji-animals has lots of emojis, and requires a different spacing to look decent.

i always end up writing a few custom <style> rules in the <head> as a tinker with what looks nice. but this style guide just shows defaults from <style.css>, nothing more.

designed for ~37ch min viewport width, which is ~pixels, which is ~__inches at default zoom on a __dpi device? should still be ok except for some horizontal scrolling on long lines. like this really long line, because it needs to be inline-block in order to scroll, and inline block needs a minimum width or something. i forget. but yeah, always gotta be mindful of long lines, long links, and foresee the calamity and give class="long-line. so yeah, 37ish ch is my danger zone.

COLORS a

you can probably tell by now, no syntax highlighting. only a few colors.

TODO: don't forget dark/light mode.

here is an unvisited link, and here is a visited link. i keep them the same color for the sake of minimalism. sorry. it's a bad thing, and i'm sorry. but i'm too committed now!

an unordered list, usually prefixed with dashes, but sometimes unprefixed. also sometimes given a reverse indent when the first line is link-ish or title-ish.

another stubborn design decision that hurts usability: ...

monospace everything?

bold, italics?

keyboard style looks like a pre: Ctrl + Alt + Delete

EXAMPLE PRE-DRAFT, SORTING FACTS a

using <details> elements as expandable notes and commentary, a la the mcphee method (link). i write about this in nugs ___ - ___. here's what it looks like to have a bunch of exandable notes in the fact-gathering phase:

expand all / collapse all

#ease, access, language (Lanier)

I realized programs could be a lot of things. They could be forms of expression, teaching tools–many things. And I thought that ordinary people should be able to make them, that hackers shouldn’t have the exclusive ability to write programs. People should be able to speak and breathe programs just like they talk now. Making little worlds inside the computer should be as easy as saying hello to your friends in the morning. I really believe we’re going to get to that point, and that it will be a very profound type of communication.

#business, company, ease (Lanier)

How did you go about starting a company? Oh, well, when you get right down to it, it really just happened. I was doing this work on languages, and various people were very supportive of me. I came to a point where I ran out of money and they said, “Let’s invest in it.” And, “ta-da,” there was the company.

#progress, quality, stagnant (Lanier)

Instead of a constantly evolving body of software getting better and better, we have a situation in which evolution just freezes when a certain software reaches a certain adequate level. Everyone’s so glad just to have something that works.

#business, society (Lanier)

our society is organizing itself more and more around things that don’t physically exist. Information, concepts of living, computer memories, the true existence of a corporation, one’s wealth, or power, or status, or one’s job–all these can be defined by information held in a computer. We are in a transition period. Until now, what we have wanted from life had to be got by manipulating physical matter. Now, we are just starting to organize our lives according to information. Eventually, our very experiences will be generated by information instead of the other way around. That will be the true information age.

# retro, hardware (Simonyi)

The Ural II was the size of a very, very large room and the method for input and output was incredibly primitive–primarily through console switches. The console looked like an old-fashioned cash register. There were six full columns of switches and an enter key on the right. Each column had keys numbered from zero to seven. You entered numbers just like you would on a cash register. So to enter 2275, you pushed the keys for two, two, seven, and five. If you made a mistake, you could correct it before pushing the enter key on the right. All this was exhilarating because there was a lot of noise associated with it. Every time I hit the switch, it clicked very firmly. Whenever I cleared it–it was all done mechanically–all the keys released at once with a great “thunk.” ... They always turned the computer off at night and turned it back on in the morning. When you turn tubes off and on, the filaments tend to break when they are cooled and heated. In a machine with two thousand tubes, one will break every time you turn the machine on. So they had to spend the first hour of every workday finding the one that broke.

#algorithms, clever (Simonyi)

One notion that sticks in my mind is how they scanned the source text backwards. It turns out that in some cases, if you do things backwards, problems that previously appeared complex suddenly become very simple. For instance, resolving forward references can be difficult. If you scan backwards, they become backward references, which are easy to resolve. Just by looking at a program in a new way, what formerly might have been rather difficult to solve becomes easy to solve. The Algol compiler was absolutely full of wonderful tricks.

#retro, hardware (Simonyi)

The Russian machine, for example, looked like a science-fiction computer because each flip-flop [the on-off device that stores one bit of information] in the machine had a little orange, old-fashioned gas discharge light. Hundreds of orange lights flickered behind glass doors and cabinets. The whole life of the machine pulsed right in front of your eyes. The Danish computer was a beautiful piece of furniture. It was about the size of an antique wardrobe closet. The front of the computer had three teak doors. I once saw an American executive look at it in disbelief because it was paneled in teak. It even had a Danish-modern console. The whole machine had the intriguing smell of teak. The Berkeley computer was quite large, about 20 feet long, 6 feet high, and 2 feet deep. It was hidden in a concrete vault that was painted completely black. The computer was a little like the monolith in the film 2001 because of the way it was placed inside the vault with spotlights shining on it.

#notation, legibility (Simonyi)

If you were to break up a program, put it into a grinder, and then sort the pieces, you would find that the bulk of the program is in names... So to me it seemed logical that to make an impact or improve things, I would try to improve the greatest bulk–and that was the names. "Hungarian" is a way of almost automatically creating a name from the properties of the named quantity. Very similar to the idea of calling people Taylor if they were tailors and Smyth if they were blacksmiths. ... Some people think if they can read each of the words in a code, then the program is readable. In fact, readability is in that sense unimportant. Nobody takes a listing, goes up to a podium, and reads a program out loud. It’s comprehension that counts. The fact that you can just read the words and pronounce them is useless. When people see a listing in “Hungarian,” they find these words difficult to pronounce, so they might think it isn’t readable. But in fact, it’s easier to comprehend and easier to communicate because of the association between the name and the properties.

#sketching, diagrams (Simonyi)

The first step in programming is imagining. Just making it crystal clear in my mind what is going to happen. In this initial stage, I use paper and pencil. I just doodle, I don’t write code. I might draw a few boxes or a few arrows, but it’s just mostly doodles, because the real picture is in my mind.

#efficiency, management (Simonyi)

If you have more than one programmer working on a program, does it develop more quickly? Not necessarily. The actual amount of code produced per person is smaller, the more people there are writing the program. Consequently, the total code produced is greater for a while, and then it may actually decrease. With two people, you might get 50 percent more code per unit of time. ... the efficiency of the code also decreases with an increase in the number of people working on the program. The most efficient programs are written by a single person.

#progress, tools (Lampson)

the actual programming is a lot easier now than it used to be. The machines have much more memory so you don’t have to squeeze as hard. You can concentrate more on getting the job done and not worry about getting the most out of limited resources. That helps a lot. Also, the programming tools are somewhat better now.

#ease, complexity (Lampson)

Sometimes I think that the goals people are trying to reach are just too much to ask for. Programmers often lose sight of the fact that the problems in building software systems arise because what they are trying to do is just too hard. They believe the computer is a universal engine that can do anything. It’s very easy to be seduced into the proposition that a group of one or five or ten or fifty or a thousand programmers can make the computer do anything. That’s clearly not right.

#engineering (Warnock)

Good systems design is much more of an engineering activity; it’s a set of trade-offs and balances among various systems’ components.

#languages (Warnock)

I prefer the LISP-style languages, because they’re more interactive and ... I like the interpretive environment. But it would have been political suicide to use LISP when I belonged to this group because my work would simply have been ignored.

#business, languages, compatibility (Warnock)

We felt that we could effectively market PostScript to the computer companies because it was device-independent. It avoided dependencies to a specific machine, so the computer companies had the flexibility to take on new technology without having to change software. We believed this would be perceived as a great value and easy to sell, and it has been. Whereas in the screen business you’re competing against everybody else’s screen package and you have operating-systems considerations; this was a nice, clean, separate piece of business without a lot of the hassle.

#progress, ease (Warnock)

The tools are better. The programming environments are better. The languages are more expressive. Computers are much more powerful now than ten or twenty years ago. But there are more options available, which also means more options for many more mistakes.

#NIH, idioms (Warnock)

There will always be some smart guy who will come along and figure out a better algorithm, or figure out an easier way of performing some task. One of the tricks of the trade is to recognize this early, adopt it quickly, and exploit it without having a “not-invented-here” hangup about doing it your way.

#business (Warnock)

Starting the business was interesting. When we first thought about it, we thought about what the world could probably use and we concluded that we ought go into the service business. We could build electronic printers that personal computers could dial up to do the printing. Then we went to Hambrecht and Quist for venture capital, but they said the service business was no good. The service business is something venture capital people won’t talk to you about. It’s very specialized financially, and the only way you make money is through franchising it. That’s really hard unless you’re gifted at franchising, and we weren’t. We decided we needed a more traditional business plan. We came up with creating a work station with document-preparation software, hooking laser printers and typesetters to that, and selling documentation systems. This is the same sort of business plan as ViewTech, Interleaf, XYVision and Texet-the whole list. It’s the same business plan that they’ve all had. After three months of work and after talking with a couple of major computer companies, we decided it was a silly business plan. We would have to build a marketing distribution channel and a light-manufacturing facility. Essentially we would have to build the whole business. And we obviously had no particular expertise in that domain. We did have expertise at building a specialized piece of software in demand by computer companies. So we switched our business plan and became an OEM supplier of software. We wouldn’t have to be in manufacturing, marketing, or distribution. And we could service the generalized computer community. It has turned out very well.

#prototyping, advice (Warnock)

Don’t bind early; don’t ever make decisions earlier than you have to. Stay an order of magnitude more general than you think you need, because you will end up needing it in the long term. Get something working very quickly and then be able to throw it away. Learn from small experiments rather than large ones. Don’t go into a two-year development with nothing coming out in the middle. Have something come out every two months, so you can evaluate, regroup, and restart. Often programmers overdefine their approach from the beginning. They may start out with a central idea and begin coding on day one. Then they find that they have a concentric-ring approach where everything starts to grow because of the dependency on so many other factors. But if you keep the process fairly loose and free and move quickly at the end, you get a much better product in the long term.

#taste, elegance (Kildall)

When a program is clean and neat, nicely structured, and consistent, it can be beautiful. I guess I wouldn’t compare a program with the Mona Lisa, but it does have a simplicity and elegance that’s quite handsome. ... I like the LISP programming language so much because it’s so pleasing. There’s a concise form of LISP called the M expressions. When you write an algorithm using M expressions, it’s so beautiful you almost feel it could be framed and hung on a wall.

#emotion, taste (Kildall)

I also think programming is very much a religious experience for a lot of people. ...if you talk about programming to a group of programmers who use the same language, they can become almost evangelistic about the language. They form a tight-knit community, hold to certain beliefs, and follow certain rules in their programming. It’s like a church with a programming language for a Bible.

#business (Warnock)

What happens when little companies grow up into huge corporations? The trick is to learn from the Hewlett-Packard approach: Keep it as twenty different, small companies. Keep breaking it up and never let it become a huge organization, except at some level that nobody cares about. In terms of working relationships, keep the number of people small and their focus localized, project-oriented, so they can work at their best. That would be my goal.

#taste (Gates)

What do you consider your greatest achievement ever in programming? I’d have to say BASIC for the 8080, because of the effect it’s had, and because of how appropriate it was at the time, and because we managed to get it so small. It was the original program we wrote when we decided to start Microsoft. Three of us knew that original program by heart. We got a chance to completely rewrite it one summer down in Albuquerque, and I thought we could save a few bytes and tighten things up. We just tuned the program very, very carefully, and ended up with a 4K BASIC interpreter. When you know a program that well, you feel that nobody can look at the code and say, “There’s a better way to do this.” That feeling’s really nice, and the fact that the program was used on a lot of machines makes it an exciting program to have written.

#complexity (Gates)

With computers increasing so much in power and memory, are programs becoming more complex, or just sloppier? How is that affecting the way people write programs? We’re no longer in the days where every program is super well crafted. But at the heart of the programs that make it to the top, you’ll find that the key internal code was done by a few people who really knew what they were doing... The worst programs are the ones where the programmers doing the original work don’t lay a solid foundation, and then they’re not involved in the program in the future. Working with those programs gets to the point that I call “experimental programming.” The programmers understand so little about those programs that they can’t understand how changes might affect speed, for instance. They might use code that already exists, or they might not understand what dependencies will break if they change something. So they add new code, and then they run it and they say, “Oh look, it doesn’t work that way.” That’s a very, very inefficient way to deal with a program, but a lot of projects end up exactly like that.

#algorithms, features (Gates)

You can do an amazing number of tricks inside of a product. You build up your feature list at the same time you’re trying to answer the question, “Why will our algorithms be better than anybody else’s?” Features are kind of crummy in a way, because the more features you have, the bigger the manual is. And features are only beneficial if people take the time to use them, whereas speed–if you can print the pages faster, or show it on the screen faster, or recalc it faster–that’s worth an incredible amount. If you can give the users a few simple commands and make the program efficient enough to do what they want with those few commands, then you’re much better off

#business (Gates)

knowledge of the market is important, especially in the applications group, so we have full-time people who just show customers the code, or look at other specifications, and things of that nature.

#learning (Gates)

the best way to prepare is to write programs, and to study great programs that other people have written. In my case, I went to the garbage cans at the Computer Science Center and I fished out listings of their operating system. You’ve got to be willing to read other people’s code, then write your own, then have other people review your code. You’ve got to want to be in this incredible feedback loop where you get the world-class people to tell you what you’re doing wrong.

#progress, hardware, compatiblity (Gates)

In a sense, personal computers have become simpler. Now we have just the two architectures: the PC and the Mac. Back in the good old days we had thirty or forty different machines that were totally incompatible, and there were a whole bunch of languages that people were messing around with. Because we’ve brought millions and millions of people in, we’ve had to make it more homogeneous, more standardized, so that they can get some sense of what’s going on.

#progress, business, society (Gates)

With educational software, we’re competing with newspapers, books, and TV. The software programs we put out today just aren’t competitive. Unless you’re just trying to save your kid from being dumb or something, then there’s no real reason to buy the machine; it doesn’t engage you. It doesn’t engage a non-computer person. ... Television is passive entertainment. We’re betting that people want to interact, choose different paths, and get feedback from the machine about what they’ve really learned. They can look up something specific that they’re interested in. It’s the interactive nature of the device that differentiates CD ROM from just turning on a TV and watching something. ... We hope with CD ROM you’ll be able to look at a map of the United States, point somewhere, click, zoom in and say, “Hey, what hotels are around here?” And the program will tell you. And if you’re in the encyclopedia and you point to one of Beethoven’s symphonies, the computer will play the song. ... If a kid is addicted to a personal computer, I think that’s far better than watching TV, because at least his mind is making choices. I’m not one of these npeople who hates TV, but I don’t think it exercises your mind much. I don’t happen to own one. ... It’s hard, just like any new media. When people were first on TV, they felt they were so much better than people on radio, but they’d just stand there. It took a long time to invent the colorful peacock, all the action, the three-dimensional padding, and the special effects that you see on TV today. Just like TV, CDs will get better as we get more experienced with the media. I can sit here and tell you all the mistakes we won’t make, and five years from now, I could sit here and tell you all the mistakes that we did make. As creative as we are, we won’t be able to exploit the media to its absolute fullest right away.

#business (Page)

In a bigger company, people require leaders who know everything but not so much that the people who work for them feel inadequate and unneeded. Company employees need to feel ownership of what they’re doing and have psychological ownership of the ideas they’re implementing, otherwise they’re not motivated.

#complexity (Page)

Computers are stuck in a rut because nothing new has happened in quite a while. The market has sucked us into overly complicated systems and the fault is mostly IBM’s. All the “new” features being installed are borrowed from minicomputers and mainframes. Each successive generation of the IBM PC is more complicated and harder to use than the last. The PC is fast regressing to being a minicomputer and IBM may even be successful in turning it back into a mainframe. The old complexities are coming back and the elegance is being washed out. Even the poor old Macintosh is being battered because it doesn’t have all the things that managers of management-information systems love.

#complexity, usability (Page)

They want the technology almost for show. It’s a bit like those expensive stereos–the more you pay, the more lights and knobs it has. It’s lunacy if you talk to a real user like the wife of the guy who buys it. You will find those gadgets just confuse the hell out of her. I bet if you could fingerprint the controls to see which ones are actually touched, you’d find that only three of the ninety are ever used. Nobody knows what the others do and no one touches them because the stereo works without them. People are that way about programs, too. They’ll buy a gross, poorly designed word-processing program because they want to write letters or reports. But it’s full of controls nobody ever touches or wants. The trick is to get around that infatuation with technology. ... We build programs with automatic transmissions, which are harder to design than programs with manual transmissions. But it’s what our customer wants.

#business (Page)

periodically, at a quiet point in the day, I go through our owner-registration cards and call people at random. I ask them why they bought our product and what they’re using it for. People are incredibly shocked by the personal attention, but they will usually tell you quite a lot about what they’re doing with the product.

#progress (Bricklin)

Bob Frankston likes to tell a story about the telephone company. Back in the twenties they said that telephones were growing so fast that by 1950 everybody in the country would have to be an operator. By 1950 people said, “Ha, they were wrong.” Well, it turned out they were right, because everybody was an operator; they just had dial telephones. The technology had made it easy enough to be an operator. Well, that’s the same thing with programming. We’re just making the users do more and more of the programming themselves, but they don’t know it. Using different style sheets with Microsoft Word is doing programming; using spreadsheets is doing programming.

#tools, writing

I hashed up all these [books] into a big concordance, something like a thesaurus. I can type along in this word-processor program, and when I want to find out how a particular word has been used in a book or by an author, I just click on it with the mouse, and, blammo, I get a little window that contains half a dozen examples of how great authors have used this word in the various books in the database. Our verbal patterns tend to move in the same channel every time, but now all of a sudden, click, I can see how Tolstoy and other authors used the particular word I just typed. Another program takes text and, using the same database, scribbles down random semi-grammatical English to complete your sentence. If you are typing along and get writer's block, you press a button and the program starts walking on from the last word that you wrote, going off into random directions. Every once in a while you get hit with a little bit of serendipity, and you find a new idea that you might not have found otherwise. (Hawley)

#nojoy, visuallanguage (Kim)

He gave me some good advice when he said to me, "As a programmer you get to a point where you say to yourself, 'Oh no, I gotta write another program." It's like you're barreling down the road with your idea and then you've got to take this big detour, you've got to go back to home. Programming is still an interesting activity, but it's generally not what I actually want to do. That's my feeling. It's taken me a while to realize how much I didn't like programming, be-cause I couldn't imagine it being otherwise, but now I can imagine it, and I am insisting that it be otherwise. (Kim)

#business, marketing, hype

Are you wary of aggressive marketing and hype? Do you think it has caused problems in the industry? It sure has. I saw a full-page color ad in a magazine for an LCD screen for an Apple IIc and so I called the company. They told me, "We expect to have them ready in ten months." A full-page color ad! I think they're wasting their money. (Raskin)

#tools, obsessive, particular

I don't like using any tools or programs I didn't write myself or that I don't have some control over. That way if I don't like some part, I can change it. As a rule, I like to keep programs simple. (Sachs)

#innovation

There is a tendency for people to write programs just to make money and not to solve problems. Instead of being innovative, they look at what already exists and try to copy it thinking, "Gee, I can do a better one of these." A lot of effort and money is being wasted trying to build better spreadsheets, but the world just doesn't need fifty-seven spreadsheets. (Ozzie)

#joy, entry, night

what really got me hooked was a computer system on campus called PLATO... access to the machine as a systems programmer fed my habit. Every night at 10:00 p.m. the machine became available, and a small clique of people like me would work all night until our time was up at 6:00 a.m. We did this for years. It was great fun. (Ozzie)

#collab

I believe that once the team is over five people, communication between individuals begins to break down, and that can cause problems related to product consistency... Unless you have a couple of people who know how each subsystem works and how it fits in with the whole, you will probably end up with a buggy product. (Ozzie)

#responsiblity, sobering, usage

My most amazing experience, though, was a phone call I got right after I started Iris, from a surgeon who was using Symphony for real-time data analysis during open heart surgery. It is sobering to think that someone was lying on an operating table, potentially relying upon my program running properly. It reminds one of the real responsiblity to the end users. (Ozzie)

#craft, science

I think the key to the craft of computer science, and I call it a craft because it certainly is not a science yet, is to find rules... your best programmers are usually aware of those several universal rules. (Carr)

javascript used to expand/collapse these elements, and also to persist their collapsed state in localstorage. no javascript used in final post because no details elements used. only intended for my eyeballs and my machine. you're getting a sneak peek! i include this hunk of html/css/js with every draft, and remove it before publishing:

<p>
  <a
    href="javascript:(document.querySelectorAll('details').forEach(d=>d.open=true))"
  >expand all</a>
  / <a
    href="javascript:(document.querySelectorAll('details').forEach(d=>d.open=false))"
  >collapse all</a>
  <script>
  document.addEventListener('DOMContentLoaded', () => {
    let elements = JSON.parse(localStorage.getItem('expandedDetails') || '[]')
    elements.forEach(id => {
      let el = document.querySelector('#' + id)
      el.open = 'true'
    })
      
    document.addEventListener('toggle', (event) => {
      if (event.target.tagName === 'DETAILS') {
        let isExpanded = event.target.open
        let id = event.target.id
        let alreadyFound = elements.indexOf(id) > -1
        if (isExpanded) {
          if (!alreadyFound) {
            elements.push(id)
          }
        }
        else {
          if (alreadyFound) {
            let idx = elements.indexOf(id)
            elements.splice(idx, 1)
          }
        }
        localStorage.setItem('expandedDetails', JSON.stringify(elements))
      }
    }, true) // bubble up all detail toggle events to parent document
  })
  </script>
  <style>
  details {
    display: inline-block;
  }
  
  details:open {
    width: 100%;
  }
  
  details p {
    padding-top: 1em;
    padding-bottom: 1em;
    padding-left: 2ch;
    padding-right: 2ch;
    border-radius: 3px;
  
    background-color: var(--bg-secondary-color);
    color: var(--text-color-on-secondary);
  }
  summary:before {
    white-space: pre;
    content: "[";
    background: var(--bg-color);
    color: var(--fg-color);
  }
  summary:after {
    white-space: pre;
    content: "]";
    background: var(--bg-color);
    color: var(--fg-color);
  }
  summary {
    list-style: none;
    cursor: pointer;
  }
  
  summary {
    text-decoration: underline;
    text-decoration-color: color-mix(
      in srgb,
      var(--fg-color) 50%,
      transparent
    );
  }
  </style>
</p>

i kludged together a vimscript function to help me create snippets with <leader>d:

" surround a selection with <details> element
" so that it will be an expandable html note.

function! SurroundWithDetails() range " range means multiline iirc
  " find highest existing id
  let l:max_id = 0
  let l:save_cursor = getpos(".")
  normal! gg
  while search('<details id="d\d\+">', 'W')
    let l:line = getline('.')
    let l:match = matchstr(l:line, '<details id="d\zs\d\+\ze">')
    if l:match != ''
      let l:num = str2nr(l:match)
      if l:num > l:max_id
        let l:max_id = l:num
      endif
    endif
  endwhile
  call setpos('.', l:save_cursor)
  
  let l:new_id = l:max_id + 1

  " yank selection, build result
  normal! gv"ay
  let l:content = getreg('a')
  normal! gvd
  let l:result = "<details id=\"d" . l:new_id . "\"><summary>" . l:content . "</summary>\n<p>comments</p></details>"
  call setreg('a', l:result)
  normal! "aP
endfunction
vnoremap <leader>d :call SurroundWithDetails()<CR>

EXAMPLE DRAFT, EDITING PROSE a

and here's what it looks like to have boxed phrases in the draft-editing phase:

(TODO)

OTHER INVISIBLE TOOLING / PROCESS / MISC a

autoformatter?

comments?

spell check? grammar check, any other checks? jsomers word frequency check may be good.

vim find and replace, on big refactors?

publishing process? never shared a draft yet for pre-publish feedback, but i'm not opposed. maybe on riskier posts outside my comfort zone. if you want to volunteer your eyeballs and brain to read one of my upcoming drafts, let me know. that would be fun.

eventually i get tired of editing, and want to publish before the month ends so i dont have to change the publication date. git push, auto-deployed. atom feed auto-updates. manually update my homepage posts section, and give it a link. publish b-roll notes in my nuggets. relax, and enjoy a break from writing.

CONCLUSION a

cliched conclusions and whatnot. i always spend all my good ideas and words earlier in the meat of the page, so don't try to force anything insightful down here. i should pretty much just end it.

final endmark flourish has generous bottom margin so that eyeballs can remain centered on the screen. sometimes i'll use an emoji like /posts/emoji-animals, but only on special occasions.

Let the writing breathe. We're done. Phew.