summaryrefslogtreecommitdiff
path: root/www/blog/2022-11-06
diff options
context:
space:
mode:
authorSteph Enders <steph@senders.io>2024-02-29 09:31:15 -0500
committerSteph Enders <steph@senders.io>2024-02-29 09:31:15 -0500
commit2b39175011422a0d8f96d7f598f46e2a781dd28f (patch)
treedd896a1e35e2ec194bfce829afd61f553652464a /www/blog/2022-11-06
parent350a5058cf383733a7e75f753abdcd1cb7aae2c5 (diff)
Initial rework commit: Build Script POC and CSS done
I've created the main CSS layout and a proof of concept for the build script: this will actually build any "done" _post/ file and generate it as a workable HTML file. However, no index file generate, rss, or gemini is implemented
Diffstat (limited to 'www/blog/2022-11-06')
-rw-r--r--www/blog/2022-11-06/index.html248
1 files changed, 0 insertions, 248 deletions
diff --git a/www/blog/2022-11-06/index.html b/www/blog/2022-11-06/index.html
deleted file mode 100644
index 184f422..0000000
--- a/www/blog/2022-11-06/index.html
+++ /dev/null
@@ -1,248 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
- <meta charset="utf-8">
- <meta name="generator"
- content="HTML Tidy for HTML5 for Linux version 5.7.45">
- <title>senders.io - My Markdown -&gt; HTML Setup</title>
- <link rel='stylesheet'
- type='text/css'
- href='/index.css'>
- <meta name="viewport"
- content="width=device-width, initial-scale=1">
-</head>
-<body>
- <div id='header'>
- <a class='title'
- href='/'>senders.io</a>
- <nav>
- <a href="/blog">blog</a> <a rel="external noopener noreferrer"
- target="_blank"
- href="https://github.com/s3nd3r5">github</a> <a rel=
- "external noopener noreferrer"
- target="_blank"
- href="https://git.senders.io">cgit</a> <a rel=
- "me external noopener noreferrer"
- target="_blank"
- href="https://tech.lgbt/@senders">fedi</a>
- </nav>
- </div>
- <div id="body">
- <article>
- <h2>My Markdown -&gt; HTML Setup</h2>
- <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>
- </blockquote>
- <figcaption>
- <cite>— <a rel="external noopener noreferrer"
- target="_blank"
- href="https://en.wikipedia.org/wiki/Markdown">Wikipedia |
- Markdown</a></cite>
- </figcaption>
- </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>
- <h3>Writing HTML by hand</h3>
- <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;h3&gt;
-&lt;p&gt; some subsection &lt;/p&gt;
-&lt;/h3&gt;
-&lt;p&gt; more text &lt;/p&gt;
-... etc
-</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>
- <h3>Micro-blogging in general</h3>
- <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>
- <h4>Gemtext</h4>
- <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>
- <h4>Gemtext links</h4>
- <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>
- </blockquote>
- <figcaption>
- — <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>
- </figcaption>
- </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>
- <h3>Wasn’t this about Markdown?</h3>
- <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>
- <h3>How I use Markdown</h3>
- <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>
- <h4>Customizations</h4>
- <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>
- <h3>Two Sources of Truth</h3>
- <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>
- <h3>Learnings</h3>
- <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>
- <div id="footer">
- <i>November 06, 2022</i>
- </div>
- <div id='copyright'>
- © 2023 senders dot io - <a rel="license external noopener noreferrer"
- target="_blank"
- href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA
- 4.0</a> unless otherwise noted.
- </div>
- </div>
-</body>
-</html>