Hacker News Reader

Yep I recently did exactly this for my personal site as well (including initially writing HTML by hand), but instead of lisp I wrote a ~100 line python script[0] so that I could write future content in Markdown instead of HTML. Yes I'm aware of Jekyll and Hugo and such, but even those were too complex for my personal site. It only took about an hour of my time to write it, and now anytime I push markdown changes to my git repository, GitHub Actions runs the markdown through the python script and generates the site which is hosted on GitHub pages.

[0] For the curious - https://gist.github.com/RPGillespie6/b133854b8ebf5a983cf32c2...

I'll jump on this bandwagon too.

I did it in Rust, because I wanted to learn Rust.

It just takes a directory structure with markdown files, and converts each file to HTML while adding a header and footer. I use it on a few sites now, and honestly I should redo the code but it works conveniently and I have other stuff to do.

Oh, and my stack is nginx on Alpine currently.

Edit:

Code is here: https://git.sr.ht/~evan-hoose/SSSSS

It really is not great code. It even shells out to markdown to do the rendering - bad for all sorts of obvious reasons. (but the right choice for my use case).

If you want to use it, be my guest. Just know that it's bad and ugly and you could write it better yourself in not very long.

Jumping on the bandwagon of the guy that jumped on the bandwagon, because you mentioned potentially re-doing your own code at some point so might be interested: my personal site [0] looks very much like this (and is also written in Rust), but uses the comrak [1] crate to convert blog posts from Markdown to HTML on the fly before formatting with the header/footer theme. Using comrak lets you write in-line HTML (so you're not stuck with only Markdown syntax if you want to do something fancier like code blocks or <math></math>), and the whole site ends up <150 LoC, including route definitions.

It handled the one potential HN hug-of-death event I've had without issues while running on the smallest DO droplet offered, and has basically been issue-free since I got it up and running.

[0] https://github.com/quietlychris/site

[1] https://github.com/kivikakk/comrak

Looks interesting, thanks!

I may very well do something similar at some point, though I've also thought about using it as an excuse to redo whenever I want to learn $LANGUAGE, or writing a markdown (or subset of markdown) interpreter at some point.

Definitely going to read through the code more closely as well - I've been meaning to find some short and well written Rust.

> instead of lisp I wrote a ~100 line python script[0] so that I could write future content in Markdown instead of HTML. Yes I'm aware of Jekyll and Hugo and such, but even those were too complex for my personal site.

Why does this kind of "complex" matter? By all means code if you enjoy it, but it sounds like minutes of coding saved you seconds of installing something that already exists, and got you a setup that is less standard and so harder to maintain.

I have found lots of static site generators more focused on blogs than a more traditional personal website. While they can be used for non-blog sites (I use Hugo for my own site), I can see how they can be daunting when first approaching them and seeing nothing but blogging examples and templates.

> Why does this kind of "complex" matter?

The real "complexity" that matters, as someone who has used most modern static site generators and front-end js frameworks, is in not knowing how or what broke, and how to fix it, when inevitably something breaks. E.g: with jekyll if you develop or modify content on a windows box, test locally, and then push to GH Pages, but Pages builds the site using unix, and some ruby gem or jekyll plugin doesn't work consistently across them, and it takes a good bit of experience and googling around the errors to find a fix or a workaround.

If you essentially made your own static site generator, at least you would know what went wrong and come up with the straightest line to the resolution (even if that's just modifying the build output by hand in an extreme case).

If we compare like with like and assume that in both cases you're developing locally on windows and running on GH Pages, something established like Jekyll has a much better chance of working consistently on those different OSes than a hand-written script, IME.

Yeah, absolutely. But we're talking about optimizing for complexity ("do I understand this?") rather than compatibility/features/functionality/security/community support/any of the other things you get from using established frameworks.

I'm not defending the decision, but I have worked with several folks who have this approach to using their own tools — and at times I lean in this direction too, until I have encountered breakages more often than I care to "understand them" by using my own tools — and hence trying to dissect the motivations behind that choice.

I've also stuck with plain HTML for my personal website, and stayed away from stuff like Markdown. It feels like too often, with Markdown, I'd be figuring out questions like "how do I get Markdown to emit the HTML that I want?"

It's not like Markdown saves me that much typing over HTML in the first place, and the HTML is a lot easier to think about.

And yes... Emacs is my HTML editor of choice, too.

Very much in the spirit of Jeff Huang: https://jeffhuang.com/designed_to_last/

I have to admit that I like the 'bare' feeling of Markdown...it just looks a little bit 'cleaner' to me (quotes here because that is super subjective).

You should be able to write HTML into any Markdown document therefore having the best of both worlds

To be perfectly honest, that sounds terrible. Like, just completely awful. I definitely don't want to do that.

HTML by itself is easy enough to work with. The syntax for HTML is pretty basic. A little verbose sometimes, but since the late 1990s it has not been hard to find a text editor that will do things like autoindent and insert closing tags automatically.

Markdown introduces a ton of weird syntax to save you a little bit of typing. That's a good tradeoff when you are striving to keep people engaged with your site... that's the reason why Markdown is used on places like Stack Overflow, Reddit, a bunch of blogs, etc. Asking people to learn how to use BBCode is a kinda tall order compared to Markdown.

However, the cost-benefit of Markdown is completely different on a my personal blog. I'm using somewhat more complicated stuff on my blog... a few standard elements like boxes that say "note", a couple charts here and there with D3, occasionally something interactive, maybe some math with KaTeX. It's not super-complicated stuff, but it's stuff that's often no fun to try and write in Markdown. Even <table> is nicer in HTML than Markdown.

I would rather deal with one simple syntax (HTML) rather than a weird mix of two syntaxes (HTML + Markdown) where one of them (Markdown) has bunch of weird edge cases. As far as I can tell, the main benefit of Markdown for personal blogs is that it's slightly less typing. Not exactly a killer feature in my eyes. (It's also very frustrating when trying to write technical documentation.)

I don't really get the saving or convenience of Markdown, esp., if you are already used to typing HTM. (HTML for simple things is easy and short enough, and fancy things are beyond Markdown anyways.)

Here's my stack:

Hosted webspace (yes, like it's the 1990s!) Apache/Unix, simple PHP templates for headers and footers, basic navigation, etc w/o JS, for the blog a custom (server-side) script generating virtual article locations, navigation, meta data, basic chrome, and a RRS feed from a simple data-file and reading static HTML for the content from static files. BBEdit for editing. No analytics. (The webspace comes with Webalizer, but this stopped working some 10 years ago. I don't care.)

And yes, there are special pages with full-fledged JS apps, as well, or blog posts featuring complex things, so nothing is chiseled in stone. If there's a purpose to it. However, a visitor should be able to get an idea what a page is about without JS.

https://news.ycombinator.com/item?id=30142327

I use it because I'm just too tempted to play with extra formatting with html+css, that's probably the only reason. Also my main notes app (Obsidian) is markdown.

Having written a heck of a lot of raw HTML, Markdown, LaTeX, [gnt]roff, Docbook, and probably a few other markup formats:

- Markdown is quite close to plain-ASCII writing. (AsciiDoc or reStructured Text might be even better).

- Markdown + pandoc gives a tool for producing numerous output formats or endpoints, including PDF, ePub, and others.

- Markdown avoids fiddly bits like balancing open/close tag pairs.

- Markdown supports features such as footnotes and tables of contents which HTML does not have simple and easy equivalents for.

Yes, there are things which are possible in HTML which Markdown itself doesn't readily provide. Off the top of my head: underlined text, coloured text, and nested superscripts. That said, these are either infrequent needs or are better accomplished through other means (e.g., styles, code-highlighting within code blocks, etc.).

Markdown does allow for about 99.9% of my HTML-tagging needs, with a lot less overhead and cleaner syntax. Which is a win.

If I were to move in any direction, it would probably be LaTeX for more complex source documents.

It's kind of annoying to see links to other comments in the thread.

https://news.ycombinator.com/item?id=30142334

Markdown syntax IMO is pretty fiddly. I find myself messing with spacing, or with line breaks between list, or things like that. On the whole I find Markdown more annoying than HTML... Markdown is just less typing.

"Markdown" doesn't support TOCs or footnotes any more than HTML does... both TOCs and footnotes are non-standard extensions to Markdown that your particular Markdown engine may support, in ways which are frequently incompatible with other Markdown engines. I found it no trouble to put footnotes in my HTML-based static site generator anyway. I don't expect TOCs would be any different, but I don't use TOCs on my site. Superscripts of any kind are a Markdown extension in the first place, and I'm always so unsure where the superscript ends that I have to try different things and reload the preview until it looks right (this is one of those fiddly bits that drove me away from Markdown).

I guess if you want to target PDF + ePub and others, yes, use something like Markdown. I'm putting video content or interactive content in my blog often enough that it's just not something that would work anyway.

Don't get me wrong... I love using Markdown for stuff like READMEs on GitHub. It's just that for something like my blog, where I put a bit more care into things, Markdown really gets in the way.

In the case of superscripts, the issue is that Markdown doesn't have a concept of nested elements.

In HTML superscript and subscript tags may simply be nested:

  10<sup>10<sup>10</sup></sup>

Markdown implementations ... vary, but typically either a ^<text><whitespace> or ^<text>^ block indicates superscript. That .. doesn't permit nesting:

  10^10^10

or:

  10^10^10^^

... either way is ... ambiguous or undefined. HTML's start/end tag syntax wins.

More generally, where simply writing text, the notion of having bounded blocks and pairs can become confusing, especially where <div>, <section>, or <article> tags are used. I'll frequently find myself unbalanced in those. To the extent that Markdown allows me to Just F*cking Write and not worry about markup ... that's a win. Ironically, for all its reputation for fiddlyness, LaTeX's use of a double carriage return as a paragraph delimiter affords a similar simplicity to much straight prose.

Markdown extension of course vary, but my point remains that using Pandoc (my usual approach), I have as first-class ready-at-hand elements tables of contents and footnotes, both of which I use extensively. I don't have a good formula-entry capability, for which I'd turn instead to LaTeX. I'd also argue that basic table entry in Markdown beats HTML, and is moreover very easy to script given structured input, e.g., with a sed or awk one-liner.

The fact that you seem to be focusing on short content rather than longer pieces may explain some of our differences of views. My typical focus is essay-to-book-length text-heavy documents. If I'm kicking out a short HTML fragment, sure, just code it up directly. Where I'm writing a work which is not specifically intended for the Web, but which could include HTML among other formats, Markdown and LaTeX start making far more sense.

I find complaining about hypertext references to streamline discussion and avoid duplicate content a ... curious gripe in the context of hypertext-authoring tools, but power to you.

When I'm writing HTML, there isn't a ton of nesting. It's mostly <h2> <h3> <p> <figure> at top-level. No parent tags. This is standard HTML, the <html> and <body> are implicit. Sections are implicitly delimited by header tags. Open and close tags are generally no more than a few lines apart. I'm strongly in favor of "semantic" tags in general (and so, for example, I do not use <cite> <em> or <i> interchangeably, even though they are all styled the same) but AFAIK the <section> tag does not really serve a useful purpose, semantically, because sections are already delimited by header tags (and screen readers and the like understand this).

Anything like an <article> or <main> or whatever is going to get handled by the template. I only write the contents of each article, and let tooling handle the boilerplate. Just like how you don't write navigation bars or TOCs in markdown, you let the tooling do that for you.

Re: tables, to each their own... I find tables in Markdown to be a bit fragile and easy to screw up when I'm changing them. I don't like having the columns shoved into one line of text. And any time I'm sticking tables in a document I'm likely to want to adjust the styling a little. Tables are easily the thing I hate the most about markdown.

> Markdown extension of course vary, but my point remains that using Pandoc (my usual approach...

Using some particular markdown tooling you get TOC and footnotes... and using some particular HTML tooling I can get the same thing.

For particular pages I often add small snippets of CSS or JavaScript, which I can just stick in <style> tags at the top, or <script> tags at the bottom, because it's just standard HTML.

I hope you are aware that nearly every markdown renderer respects full HTML right? As soon as you open a HTML tag, you can just treat its insides as HTML. That way you can just write prose when you are in content mode. If you want to switch to dev/designer mode you simply have to open a HTML tag.

When you can simply think of markdown as a syntax tooling on HTML that is widely human readable (by non-web developers!) without stopping you from having the full power of HTML whenever and however you like it, how is that not a win?

> I hope you are aware that nearly every markdown renderer respects full HTML right?

Yeah, I'm aware.

> That way you can just write prose when you are in content mode. If you want to switch to dev/designer mode you simply have to open a HTML tag.

When I want to just write prose, I can use a WYSIWYG word processor. When I want to make a post on my web page, I can write it in HTML. I rarely benefit from having a third option... markdown, the "mediocre at all things" format, which is not good enough to replace a word processor from the 1990s and not good enough to use in place of HTML when I'm making my web page.

I do actually use markdown... for small snippets of notes. I have all my Emacs setup to edit markdown quite nicely. If the notes start getting too large and detailed, I copy and paste the notes to a word processor, so I don't have to deal with markdown's awful syntax. If the notes evolve into a blog post, I'll rewrite them in HTML--I always rewrite notes anyway, before posting. It's much more common that I start blog posts in a word processor, rather than markdown, though.

> When you can simply think of markdown as a syntax tooling on HTML that is widely human readable (by non-web developers!) without stopping you from having the full power of HTML whenever and however you like it, how is that not a win?

This argument is taking for granted the idea that people like markdown syntax, when I thought that I had been pretty clear that I don't like markdown syntax. I think it's just kinda mediocre at lots of different things, and in the end, is worse than just using plain HTML... except for a few niches, like READMEs on GitHub and comments on Reddit.

To be clear, markdown is not a win for using in my website because it makes my tooling more complicated, and it delivers no benefits.

I can understand why some people like it... surely you can try to understand that some people don't, and we don't just dislike markdown for no reason.

> As soon as you open a HTML tag, you can just treat its insides as HTML.

That is not entirely true. There are some edge cases to consider and while considering edge cases, we first need to decide which Markdown flavour we want to use. Some of us also need to consider if we are willing to commit to that Markdown flavour for the next 10, 20, 30 years or so because we do not want to "fix" our content again when some content rendering breaks due to edge cases when we switch from one Markdown renderer to another. The multiple flavours of Markdown handle several edge cases in different ways.

Let us pick CommonMark as the Markdown flavour for this comment. Here is an interesting edge case that is relevant to your comment. Consider the following Markdown input:

  <div>
  *foo*
  </div>

The above Markdown input is rendered as the following HTML output:

  <div>
  *foo*
  </div>

Now consider the following Markdown input:

  <div>

  *foo*

  </div>

This is rendered as the following HTML output:

  <div>
  <p><em>foo</em></p>
  </div>

One can use https://spec.commonmark.org/dingus/ to test these examples.

So as soon as we open an HTML tag, we can't just treat everything inside it as plain HTML. The content within the HTML tags may get interpreted as Markdown as shown in the second example above. Now granted, all of this is clearly specified in the CommonMark specification and these edge cases are handled in this manner for good reasons (such as providing a way to use Markdown syntax within HTML tags, in the above example). But one has to understand the specification very well and keep these edge cases in mind while mixing HTML and Markdown.

For many people, these edge cases are not a problem because they write simple Markdown that would probably get rendered the way they expect, without any surprises. I can understand why many people prefer to use Markdown to write their website content. But there are also some of us, who find this extra complexity to be not worth it, especially because editing plain HTML files is nearly as easy, if not more, with a good editor (Emacs, in my case).

I worked with Perl's Template::Toolkit for many years and would still recommend it for static site generation. TT3 is the current version.