1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
--post-date: 2022-11-06
--type: blog
--updated-at: 2024-03-02
--tags: tech
<article>
<h1>My Markdown → HTML Setup</h1>
<p>A common way I see a lot of people blog, especially micro-blog, is in
<a rel="external noopener noreferrer"
target="_blank"
href="https://daringfireball.net/projects/markdown/">markdown</a>.</p>
<figure>
<blockquote>
<p>Markdown is a lightweight markup language for creating formatted
text using a plain-text editor.</p>
<cite>— <a rel="external noopener noreferrer"
target="_blank"
href="https://en.wikipedia.org/wiki/Markdown">Wikipedia |
Markdown</a></cite>
</blockquote>
</figure>
<p>It built itself on-top of common syntax prevalent on the web and was
designed to be converted into simple HTML output. Since it leveraged
preexisting syntax it was easy for new users to pick up, and is now found
all over the web and applications.</p>
<p>Since I started this website, I had been writing each page by hand
using a few tools to facilitate that - and for a while I had been looking
for a good way to try out using markdown to generate some lighter pages
and these blogposts.</p>
<h2>Writing HTML by hand</h2>
<p>When it comes to blogging a lot of platforms offer WYSIWYG editor –
allowing users to write in rich-text that then gets converted into HTML
in the style of the platform. But for my case, since I self host this
website, I decided to stick to my roots and write PURE HTML instead.</p>
<p>HTML is fairly simple and easy once you get use to the basic structure
of the system. And since I’ve been working in HTML almost two decades
now, at the time it felt like the best solution to make a clean
website.</p>
<p>I briefly touched on my design process in <a href=
"/blog/2019-01-21/">2019-01-21 - First! A New Years Resolution</a>
outlining that I wanted to make a very lightweight and simple website.
And at the time I believed the best way to achieve this goal was to
carefully structure and craft my website’s HTML by hand.</p>
<p>This article is making the process sound far more difficult than it is
– it’s mostly just tedious.</p>
<pre><code>
<article>
<h2> Title </h2>
<p>
Some paragraph....
</p>
<h2>
<p> some subsection </p>
</h2>
<p> more text </p>
... etc
</article>
</code></pre>
<p>Is essentially what the website looks like - you can view the source
of this page to see – it’s very simple HTML.</p>
<p>The benefit I found doing this, mostly leveraging <a href=
"www.html-tidy.org/">tidy</a>, allowed a very easy to edit codebase. And
by leveraging the existing tags and their properties I also attempted to
keep the styling to an absolute minimum. Using existing tags to enforce
the styling I desired.</p>
<p>Only for certain areas (tables, code, quotes) where readability is an
issue do I setup custom CSS.</p>
<p>Most of this process is actually what will continue to happen but the
actual writing process will be unobstructed by the tedium of writing
HTML.</p>
<h2>Micro-blogging in general</h2>
<p>At the time of writing this, I have no ported over any of my <a rel=
"external noopener noreferrer"
target="_blank"
href="https://gemini.circumlunar.space/">Gemini</a> micro-blogs. This
warrants a longer post, since I wrote consistently in gemini from
March 2021 through May 2021 – having only stopped due to a long move
leading to a lot of server downtime breaking the habit. My gemini
updated multiple days a week - mostly due to the extremely lightweight
and limited nature of the platform.</p>
<h3>Gemtext</h3>
<p><a rel="external noopener noreferrer"
target="_blank"
href="https://gemini.circumlunar.space/docs/gemtext.gmi">Gemtext</a>
was the gemini protocol’s standard MIME type. It was a basic markup
language that relied on line based syntax. It was purposefully as lean
as necessary because this was what was ACTUALLY being served to
clients – unlike Markdown which first needed to be converted to HTML,
gemtext was the actual text served and rendered on the viewers client.
You could customize the style of your client - but you could not, as
an author, dictate how your content would be viewed. This meant the
only aspects of your blog you had control over was the actual content
and it’s structure – which for a blog is really all you should care
about.</p>
<p>It’s syntax contained most of what I was actually using here already
from HTML:</p>
<ol>
<li>headings</li>
<li>paragraphs that were wrapped based on page-width</li>
<li>links</li>
<li>lists</li>
<li>quotes</li>
<li>preformatted-text / codeblocks</li>
</ol>
<p>Besides links - it also leveraged the same common syntaxes that
markdown did.</p>
<h3>Gemtext links</h3>
<p>From my brief time in the IRC and in geminispace in general - a lot of
the “recommendations” came from new users about providing in-line links.
The philosophy was that by forcing links to exist on their own line -
clients could configure how they wanted these to be seen and not have to
worry about links interfering with the text.</p>
<figure>
<blockquote>
<p>Like Gopher (and unlike Markdown or HTML), Gemtext only lets you
put links to other documents on a line of their own. You can’t make a
single word in the middle of a sentence into a link. This takes a
little getting used to, but it means that links are extremely easy to
find, and clients can style them differently (e.g. to make it clear
which protocol they use, or to display the domain name to help users
decide whether they want to follow them or not) without interfering
with the readability of your actual textual content.</p>
<cite>
—
<a rel="external noopener noreferrer"
target="_blank" href="https://gemini.circumlunar.space/docs/gemtext.gmi">
gemini.circumlunar.space
– A quick introduction to “gemtext” markup | Links
</a>
</cite>
</blockquote>
</figure>
<p>I felt that this provided a lot of useful limitations that removed a
huge barrier for me to actually write down ideas without feeling over
burdened. I also lurked in the IRC - as well as <a rel=
"external noopener noreferrer"
target="_blank"
href="https://github.com/s3nd3r5/java-gemini-server">implemented my
own gemini server</a>.</p>
<p>As a quick aside – the java server was a lot of fun! The protocol was
very simple to work with for basic gemtext. I felt the ultimate downside
was trying to build something for basic gemini capsule hosting (like I
was using for a decent chunk of my time with gemini) - and something for
developers to use as a base application server. At the time in 2021 a lot
of talk was happening on IRC of users starting to look to provide more
complex experiences via the protocol and I wanted a way for those
interactions to be built out in Java - since most were in Go or Python at
the time. This decision lead to me burning out due to difficulties
splitting those responsiblities easily - where you could host along side
your application - since I lacked the experience with more complex Gemini
capsule applications.</p>
<p>But it was a good experience and I got hands on experience with Certs,
Netty, and SNI - which actually came in handy at my job!</p>
<h2>Wasn’t this about Markdown?</h2>
<p>A lot of what I liked about Gemini I found missing when I returned to
the World Wide Web. Writing a new post was tedious and I actually had a
few drafts sitting unposted. They’re probably checked into my git at this
moment! So I thought - why not just use markdown and convert to HTML?
That’s what it’s built for - and I already designed my site to work with
minimal customization of raw HTML tags!</p>
<h2>How I use Markdown</h2>
<p>Firstly, this blogpost was written in Markdown (with minimal HTML
sprinkled in). Then I render the markdown into HTML using <a rel=
"external noopener noreferrer"
target="_blank"
href=
"https://www.pell.portland.or.us/~orc/Code/discount/">Discount</a>.
Frankly, I don’t know how I stumbled across this markdown parser - I
think it came pre-installed on my KDE Arch system because another KDE
program used it. But I liked it, and it seemed extensible enough for
my needs.</p>
<p>This would produce the “body” of my articles - and I could then
prepend and append the template-head and foot to my html output to form a
blog post/web page.</p>
<h3>Customizations</h3>
<p>After I generated the output file, I replaced some placeholders in the
templates via <code>sed</code> and then <code>tidy</code>’d the HTML. The
only other major issue was Discount had no way of appending any link
attributes – so for external links I had <code>sed</code> append the
<code>rel</code> and <code>target</code> attributes - which work off the
assumption they’re not there. A lot of my home-server scripts rely on
assumptions…</p>
<p>This is all bundled up in a simple script file so I can just supply a
few arguments and the full page is re-rendered on command.</p>
<h2>Two Sources of Truth</h2>
<p>In the sytem I devised the markdown files are really the “source of
truth” but you could argue that the HTML files hold equal weigh - as
they’re what you’re reading right now. The markdown is only useful if I
render it as HTML. There exist nginx extensions to serve markdown as HTML
so I store everything as markdown. I could also provide some heading
information to the markdowns to remove the command arguments and have on
boot it generate the .html files in place before launching the site… But
these are all nice ideas for a later date.</p>
<p>Ultimately, this is something I contribute to ocassionally - I don’t
need something too complicated. I just need to output some HTML a few
times a year. So if I manually publish the HTML each time - that’s likely
far more efficent then re-rendering.</p>
<h2>Learnings</h2>
<p>This is the first post that uses this - though I’ve converted a page
over to this already. But once I worked out the kinks and built a flow
that works for me - this made the writing process a LOT easier. Another
issue was that once I <code>tidy</code>’d the HTML file - it became
frustrating to edit, and I didn’t always re-tidy it. Because the output
is always <code>tidy</code>’d by the script - I can edit the raw markdown
as needed. And the script generally will always output the same file
(with whatever changes I made of course). This makes the editing and git
history a lot clearer.</p>
<p>I would recommend writing in markdown - or even trying out gemini -
you can host your gemini capsule on the web even! (Most gemini webpages
are gemini capsules converted). I am sure other “blog focused markups”
also exist too.</p>
</article>
|