What I don't understand is why people store blog entries in Markdown instead of the rendered HTML. If you ever decide to switch to a different Markdown parsers/renderer, there stands a good chance of it not being 100% compatible with the old one.
I finally broke down (after almost 20 years) and now use a markup language (not Markdown) instead of writing HTML by hand for my blog, but still store entries as rendered HTML. That way, I can make changes to how my markup language works (and I have made perhaps half a dozen incompatible changes to the syntax) without having to fix past entries, or fix past entries.
Because I care about the (perfectly readable) source in MD and not the page.
If I need to rerender it with a different engine I can still compare snapshots- I actually did that when porting my page from hugo to my own SSG. Different host language, different markdown parser - was much less work to adjust than recreate the templates in a different template language (esp with trimming line breaks via <%- etc but nothing a few hours could not fix.
I have literally zero fears this will not work next time in another 10 years.
How do you change the design of your blog if the posts are already generated in the styled html?
I don't think I've ever really had an issue with differences between md parsers/renderers, if those differences do exist it's in tertiary features which seems fine.
Having said that, I think for most blogging use cases, markdown is overkill. I like the gemini (gmi) spec where there can only be a single type of node per line. I like it so much I wrote something similar but for lists: https://pico.sh/plain-text-lists
It's a very simple design and covers 90% of the required use cases for writing prose. The main thing you lose is inline formatting options which I find mostly superfluous.
What is "styled HTML"? I use CSS to style the HTML. I use semantic HTML for blog entries.
But if you mean with the class attribute on them, then yes, I do have "styled HTML" but it's largely semantic. For instance, for code fragments, I use <PRE CLASS="language-Lua"> (for example). When I quote Internet headers, I use <DL CLASS="headers">. That works for me. Also, each entry isn't the entirety of an HTML page---it's missing the doctype, <HTML>, <HEAD> and <BODY> tags for instance; it's the template engine that pieces it all together.
As I've never been a fan of syntax highlighting, nothing right now, just slap the code inside a <PRE> block. But my blogging engine does do some processing of the HTML when serving up content (to adjust links), so if I wanted to do some styling of code samples, that would be the place to add it.
In that case, what's the purpose of the language classes? They're not standardised, so there's not much value from a semantics perspective there, right?
Semantic, in that they're labeled as a computer language (before the hyphen), and secondarily, as what language they represent (after the hyphen). At one point, I did have CSS that targeted these blocks to put a colored border (based off Github language colors) but later decided I didn't like them. I still do them because I might decide what to do style-wise with them later. I could also write code to do something with them by parsing the HTML.
If I need to do that, I can change not only the CSS, but also the main template. I mean, all the feed files I support are just alternative templates that are used when I post.
In my experience, there's a minimum subset of markdown that is mostly fairly portable, and that's sufficient for me. Adding a blank line between any two blocks of markup, and preferring raw html over parser-specific features results in a style of writing that I've very rarely had trouble porting between different parsers. (Obviously the equation changes if your markup language is more ecosystem-specific or unique - markdown's ubiquity also helps a lot here.)
Meanwhile, I'm quite likely to change an existing markdown file and want to see the finished HTML result: while writing the post, it's nice to see the text in context; I can draft a post, commit it, move to another computer and continue editing; I might send a rendered draft to friends and ask them to review it; I might add corrections or updates later; I sometimes add new features to my blog that require HTML changes; etc.
The result is that it is a lot easier for me to store markdown as source files than to work in markdown (or similar), render to html, commit HTML, and then later either need to rerender from a source file in a separate location, or edit the HTML directly. As in, that's also a perfectly fine way of working, but for me would be marginally more work for basically no gain.
The other thing is that I don't have so many posts that if I did decide to change something, I couldn't go back and fix everything later. I am tied to the minimum subset of markdown that I use (I need to be and to insert raw HTML blocks, for example, or to use the nonstandard but very common footnote syntax), but I could probably use something like pandoc to switch to a different markup language and manually correct any pages where that didn't work. Or I could just render all the existing files to HTML then, and write new posts in the new language.
No, it looks more like this, and I wouldn't recommend it for anyone else, since it's geared more for how I blog. It's a cursed mixture of Markdown, TeX and ORG mode.
I've made something similar, also SSG in one C file, that works in situ - you write pages in html and it just replace header and footer with your current design (also creates index files, rss, all that stuff).
I like the design of the author's SSG, in particular, the idea to just copy over all files, except for some files. In the author's case, HTML files. In my case, the exempted files are mako templates (= files with a .mako template), which allows for lightweight interleaving of python and content. I think this approach of copying over everything, and special casing some files, is good for making small and intuitive SSGs.
I was a bit surprised to read the annoyance with parsing markdown. It's not misplaced, and from a dependency minimization point of view it makes sense. But depending on a markdown parser (or a markdown toolkit like Pandoc is pretty acceptable generally IMHO. But I can see the appeal of only depending on a C compiler, too.
In my case I'm depending on pandoc for inferfacing with Markdown. While it's been easy and pleasant to use, it has made my SSG compilation step slow, about 20 seconds. This is not so nice when I'm changing my site and I need a few tries to get it right... The temptation to build a build system is so strong 😄
e12e | a month ago
To each their own - but if wanting to write html, I'd probably use meta tags for metadata?
https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta
And as for templating - seems very similar to Server Side Includes?
spc476 | a month ago
What I don't understand is why people store blog entries in Markdown instead of the rendered HTML. If you ever decide to switch to a different Markdown parsers/renderer, there stands a good chance of it not being 100% compatible with the old one.
I finally broke down (after almost 20 years) and now use a markup language (not Markdown) instead of writing HTML by hand for my blog, but still store entries as rendered HTML. That way, I can make changes to how my markup language works (and I have made perhaps half a dozen incompatible changes to the syntax) without having to fix past entries, or fix past entries.
wink | a month ago
Because I care about the (perfectly readable) source in MD and not the page.
If I need to rerender it with a different engine I can still compare snapshots- I actually did that when porting my page from hugo to my own SSG. Different host language, different markdown parser - was much less work to adjust than recreate the templates in a different template language (esp with trimming line breaks via
<%-etc but nothing a few hours could not fix.I have literally zero fears this will not work next time in another 10 years.
erock | a month ago
How do you change the design of your blog if the posts are already generated in the styled html?
I don't think I've ever really had an issue with differences between md parsers/renderers, if those differences do exist it's in tertiary features which seems fine.
Having said that, I think for most blogging use cases, markdown is overkill. I like the gemini (gmi) spec where there can only be a single type of node per line. I like it so much I wrote something similar but for lists: https://pico.sh/plain-text-lists
It's a very simple design and covers 90% of the required use cases for writing prose. The main thing you lose is inline formatting options which I find mostly superfluous.
spc476 | a month ago
What is "styled HTML"? I use CSS to style the HTML. I use semantic HTML for blog entries.
But if you mean with the class attribute on them, then yes, I do have "styled HTML" but it's largely semantic. For instance, for code fragments, I use
<PRE CLASS="language-Lua">(for example). When I quote Internet headers, I use<DL CLASS="headers">. That works for me. Also, each entry isn't the entirety of an HTML page---it's missing the doctype,<HTML>,<HEAD>and<BODY>tags for instance; it's the template engine that pieces it all together.I'm not a fan of
text/geminias it's hard to convert to from HTML (which I do for my Gemini mirror of my blog; I found it way easier to support my Gopher mirror of my blog than it was to Gemini, but I've been blogging since December of 1999.Johz | a month ago
How do you do code formatting via CSS alone?
spc476 | a month ago
As I've never been a fan of syntax highlighting, nothing right now, just slap the code inside a
<PRE>block. But my blogging engine does do some processing of the HTML when serving up content (to adjust links), so if I wanted to do some styling of code samples, that would be the place to add it.Johz | a month ago
In that case, what's the purpose of the language classes? They're not standardised, so there's not much value from a semantics perspective there, right?
spc476 | a month ago
Semantic, in that they're labeled as a computer language (before the hyphen), and secondarily, as what language they represent (after the hyphen). At one point, I did have CSS that targeted these blocks to put a colored border (based off Github language colors) but later decided I didn't like them. I still do them because I might decide what to do style-wise with them later. I could also write code to do something with them by parsing the HTML.
e12e | a month ago
I mean, the obvious answer would be:
https://csszengarden.com/
(Keep the html, change the css).
erock | a month ago
That seems more limiting than storing the content in md. Sometimes you need to change the structure of the post page.
e12e | a month ago
There's always xlst, like:
https://docs.diazo.org/en/latest/
spc476 | a month ago
If I need to do that, I can change not only the CSS, but also the main template. I mean, all the feed files I support are just alternative templates that are used when I post.
Johz | a month ago
In my experience, there's a minimum subset of markdown that is mostly fairly portable, and that's sufficient for me. Adding a blank line between any two blocks of markup, and preferring raw html over parser-specific features results in a style of writing that I've very rarely had trouble porting between different parsers. (Obviously the equation changes if your markup language is more ecosystem-specific or unique - markdown's ubiquity also helps a lot here.)
Meanwhile, I'm quite likely to change an existing markdown file and want to see the finished HTML result: while writing the post, it's nice to see the text in context; I can draft a post, commit it, move to another computer and continue editing; I might send a rendered draft to friends and ask them to review it; I might add corrections or updates later; I sometimes add new features to my blog that require HTML changes; etc.
The result is that it is a lot easier for me to store markdown as source files than to work in markdown (or similar), render to html, commit HTML, and then later either need to rerender from a source file in a separate location, or edit the HTML directly. As in, that's also a perfectly fine way of working, but for me would be marginally more work for basically no gain.
The other thing is that I don't have so many posts that if I did decide to change something, I couldn't go back and fix everything later. I am tied to the minimum subset of markdown that I use (I need to be and to insert raw HTML blocks, for example, or to use the nonstandard but very common footnote syntax), but I could probably use something like pandoc to switch to a different markup language and manually correct any pages where that didn't work. Or I could just render all the existing files to HTML then, and write new posts in the new language.
spc476 | a month ago
I have over 5,600 entries from the past 26 years. I think I have different concerns.
Johz | a month ago
Ah yeah, that's a very specific scenario, then I can understand why you'd be more interested in longevity rather than ease-of-editing.
bitshift | a month ago
Pardon my poking around, but is this a sample of the markup language that you're currently using (SexpCode)?
You can't drop a cliffhanger like that and not tell us! 🙂
spc476 | a month ago
Oh, I checked in that file? Heh.
No, it looks more like this, and I wouldn't recommend it for anyone else, since it's geared more for how I blog. It's a cursed mixture of Markdown, TeX and ORG mode.
mcksp | a month ago
I've made something similar, also SSG in one C file, that works in situ - you write pages in html and it just replace header and footer with your current design (also creates index files, rss, all that stuff).
[OP] rbr | a month ago
I like the design of the author's SSG, in particular, the idea to just copy over all files, except for some files. In the author's case, HTML files. In my case, the exempted files are mako templates (= files with a .mako template), which allows for lightweight interleaving of python and content. I think this approach of copying over everything, and special casing some files, is good for making small and intuitive SSGs.
I was a bit surprised to read the annoyance with parsing markdown. It's not misplaced, and from a dependency minimization point of view it makes sense. But depending on a markdown parser (or a markdown toolkit like Pandoc is pretty acceptable generally IMHO. But I can see the appeal of only depending on a C compiler, too.
In my case I'm depending on pandoc for inferfacing with Markdown. While it's been easy and pleasant to use, it has made my SSG compilation step slow, about 20 seconds. This is not so nice when I'm changing my site and I need a few tries to get it right... The temptation to build a build system is so strong 😄