summaryrefslogtreecommitdiff
path: root/posts/my-markdown-html-setup.html
blob: 060f9886a60764e17f19a0b2caf2d27cb8fdaf9f (plain)
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>
&lt;article&gt;
  &lt;h2&gt; Title &lt;/h2&gt;
  &lt;p&gt;
    Some paragraph....
  &lt;/p&gt;
  &lt;h2&gt;
  &lt;p&gt; some subsection &lt;/p&gt;
  &lt;/h2&gt;
  &lt;p&gt; more text &lt;/p&gt;
... etc
&lt;/article&gt;
</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>