Writing Html With Steno
Why and how I do it
2021-09-04
If you use Pandoc or Jekyll to create your web pages, then this probably won't be of any interest to you.
As you may know, I use Tufte CSS for styling my blog/website. I really like it because it's simple, mobile friendly and easy to use. Since the structure of my website is very simple, I just use an Apache server which I host myself. Ever since I started playing with websites (this is the fourth one I've ever had publicly available), I've never really bothered with Pandoc or other tools.
The benefit of tools like these is that you can write your page in mark down (or something simpler than HTML), and have it be converted into a working HTML page. This way, you can focus more on writing content rather than writing HTML and worrying about boilerplate code. For example, every page I write using Tufte CSS starts with the following:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>Writing HTML With Steno</title>
<link rel="stylesheet" href="../../css/tufte.css"/>
<link rel="stylesheet" href="../../css/latex.css"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
</head>
It would make sense that this should be autogenerated. However, I haven't found this very repetitive as I can just copy and paste a template page. In practice, I usually just end up copying a previous page and then changing out the relevant info. This hasn't really gotten in the way of writing content, and I kind of like having all the raw HTML code visible. I like to see what's actually going to be shown online.
For a while, if I needed an image element or margin video, I'd just copy the code from a file that contained all the elements I use. Since Tufte CSS is pretty simple, I don't think it's necessarily bad to just do this. It can be repetitive, but unless you're writing a lot of articles, I wouldn't say it's worth it to learn how to use Pandoc or similar tools for writing articles.Of course, it is also because I'm lazy and stubborn.
With that said, I realised that there was an opportunity for using steno to write articles. Certainly, there's the benefit of writing prose but there's also the benefit of having your own strokes for HTML tags. For example, to write a paragraph tag, I use TA*G/P
.I've thought about adding one stroke entries for simple tags such as these, but I just haven't bothered so far. Two strokes isn't too bad, and I just can't come up with a simple system that's easy to remember for one-stroked entries.
Since you can define strokes to be literally anything, I have strokes for images, margin images, side notes, margin notes, videos, margin videos, et cetera. The possibilities are endless, especially for a language like HTML.
Here are some other strokes I use for Tufte CSS HTML.
"TA*G/*EU": "{^}</i>",
"TA*G/*UL": "{^}</ul>",
"TA*G/A": "<a href=\"",
"TA*G/A*": "{^}</a>",
"TA*G/AE": "<a target=\"_blank\" rel=\"noopener noreferrer\" href=\"{^}",
"TA*G/EU": "<i>{^}",
"TA*G/H*/1": "{^}<h1>{^}{-|}",
"TA*G/H*/1*": "{^}</h1>",
"TA*G/H*/2": "{^}<h2>{^}{-|}",
"TA*G/H*/2*": "{^}</h2>",
"TA*G/H*/3": "{^}<h3>{^}{-|}",
"TA*G/H*/3*": "{^}</h3>",
"TA*G/H/1": "{^}<h1>{^}{-|}",
"TA*G/H/2": "{^}<h2>{^}{-|}",
"TA*G/H/2*": "{^}</h2>",
"TA*G/H/3": "{^}<h3>{^}{-|}",
"TA*G/H/3*": "{^}</h3>",
"TA*G/HR*EU": "{^}</li>",
"TA*G/HREU": "{^}<li>{^}{-|}",
"TA*G/KO*ED": "{^}</code>",
"TA*G/KOED": "<code>{^}",
"TA*G/P": "{^}<p>{^}{-|}",
"TA*G/P*": "{^}</p>",
"TA*G/PR*E": "{^}</pre>{^}",
"TA*G/PRE": "{^}<pre>{^}",
"TA*G/S*EBGS": "{#Shift(tab)}{^}</section>",
"TA*G/SEBGS": "{^}<section>{^}{-|}",
"TA*G/SUBT": "{^}<p class=\"subtitle\">{^}{-|}",
"TA*G/UL": "{^}<ul>{^}{-|}",
Behold, HTML code stored in json.
It's a little messy because of all the additional symbols for spacing and escaping, but it's actually quite easy to use. Now while I said you could have strokes defined for images, and other elements that need <figure>
tags, it gets very messy very quickly because how everything needs to be represented as one line in the dictionary. You can either put a bunch of \n
in the definitions, or just write everything on one line. I've gone with the former.
If you do want to see the definitions I use for Tufte CSS, check out this GitHub gist.
Now, there is one caveat about using steno for multiline HTML elements which is that indenting can be quite tricky. If you use an editor that auto indents, you'll mostly be fine. For most of the definitions I'm using, I'm relying on auto indentation. I do this by only adding spaces in the first line, and then subsequent new lines will be indented by my editor.
"TA*G/PEUFP": "{^}<figure>\n <label for=\"picture-{^}{:time:%s}\" class=\"margin-toggle\">⊕</label>\n<input type=\"checkbox\" id=\"picture-{^}{:time:%s}\" class=\"margin-toggle\"/>\n<span class=\"marginnote\"></span>\n<img src=\"./img/{^}",
This works fine, but just keep in mind that *
might backspace a little less than needed. Stroking PW-FP
or PW*FP
a few times will help deal with the remaining characters.
The pause in the middle of the video is from me trying to think of what I'd name this very video.
I also achieve unindenting in a similar way, except Plover will use shift tab
to do so.
"TA*G/P*EUFP": "{^}\" alt=\"picture\"/>\n</figure>{#Shift(tab)}",
Of course, indentation is not necessary with HTML code so one could easily just remove all of this complexity. Personally, I like to have indentation, and so I'll be keeping it in. Though, I am thinking of learning and switching to vim which may prompt me to come up with something else or stop indenting altogether with HTML.
Another hacky thing that I use is the inclusion of {#Left}
commands in some of the strokes. This is for side notes and margin notes. To write a margin note, you do something like this:
<label for="mn-1630797290" class="margin-toggle"<⊕</label><input type="checkbox" id="mn-1630797290" class="margin-toggle"/><span class="marginnote">Text goes here</span>
For the stroke that I use for sidenotes, I use 7 left arrow key presses in order to get the cursor in the right position for entering the sidenote text (right before the </span>
).
<label for="sn-{^}{:time:%s}{^}" class="margin-toggle sidenote-number"></label><input type="checkbox" id="sn-{^}{:time:%s}" class="margin-toggle"/><span class="sidenote"></span>{#left}{#left}{#left}{#left}{#left}{#left}{#left}{^}{-|}
It actually works surprisingly well. And although pressing the asterisk will not work, all I have to do is go to the end of the sidenote and stroke the asterisk. Undoing the sidenote isn't risky at all.
You may have also noticed that in some of the strokes (such as the sidenote), there's a part that says for="margin-picture-{^}{:time:%s}{^}"
as well as id="margin-picture-{^}{:time:%s}{^}"
. This is because when using these elements, the "id" and "for" values should be the same in each individual element. Having to move the cursor back to the correct place, and then change both the "id" and "for" values is very repetitive.
I couldn't think of an easy way of making sure they match while being unique on every different stroke. I thought about python dictionaries and a plugin, but nothing came up. I wasn't going to spend a day figuring out how, so instead, I'm using the plover-current-time
plugin. This will assign the "for" and "id" to the number of seconds since the UNIX epoch.
Again, this is quite hacky and I'm amused by the fact that all my articles will be riddled with time stamps. But it works, and that's all that matters to me at the moment :) Anything to keep me from switching to markdown!.
Conclusion
I'm not really recommending anyone to do this, but it's certainly one way of writing articles for a blog or website. And while I've only added a lot of different tags recently, I do enjoy writing articles using steno completely. At the moment I'm still copying and pasting the boilerplate code for these HTML pages, but I think in the future I'll try to switch to steno completely for writing these articles.
As for writing articles with HTML, I'm definitely not alone in this. The writer of woodgears.ca, for example, writes all of his articles unaided with HTMLYou can also clearly see he doesn't use indenting (view the page source). His website is very, very old, with hundreds and hundreds of articles. It seems to work for him, so I don't think I'll run into a problem with the way I'm running my website.
The tags I have defined are also not at all finished. Since I've recently been writing articles for this website, I've found more tags I need to add and more entries I can use.For example, it was only until today that I realised that margin figures can go inside a paragraph tag containing text. I'll update my gist as I go along and find out more techniques and methods with Tufte CSS.