I too ran a site on markdown with HTML. Originally I had my own hacky way of using HTML which was effectively to (1) replace all HTML with placeholder_number (2) format the markdown (3) replace placeholder_number with the html that used to be there. Not as simple as that but close.
Eventually i switched to a commonmark spec formatter and then tried to fix any old pages that had spaces in the HTML. Some were basically hard to fix like a pre section with code inside so I added some other hacks to do the same as above for those sections by surrounding them with {{#html}}....stuff..with...blank...lines{{/html}}.
So now my solution is handlebars.js meets markdown-it.
xfeeefeee · 4h ago
I recently discovered a static site generator called Astro, which supports many syntaxes but the .astro is a nice mix of TypeScript and JSX-like syntax. Content can use MDX which is like Markdown but with {JSX} style markup for variables and etc. The static components are used very similar to React, with familiar import statements and <ComponentName props=etc> patterns. It is extremely easy to pick up. Best of all, it has plugins to support all sorts of other interactivity, so you can create interactive 'islands' of content using React or Preact or SolidJS or Vue etc. That way you have most of your content statically generated, and then the dynamic parts can be done from the client side.
Best of all, if you use simple unchanged files for other dynamic stuff like JSON etc, you can just generate those on build and serve those files in the host directly as the 'response' to a simple REST request, which is sometimes overlooked despite being the most fundamental form of a REST API.
I came across this after researching various options for a website that had, mostly for my own entertainment, restrictions on wanting to be mostly statically generated but customizable easily without learning a lot of new syntax / etc, something JSX-like with Markdown support etc, and MDX was an immediate find - and astro was the easiest SSG I found for it after trying with 11ty and several others. Actually felt like a delight playing with it.
angelmm · 4h ago
Custom elements are really great for editors and developers. You can provide a rich set of primitives that editors can use to display certain content. In the past, I used MDX [1] extensively so non-technical writers can create a rich UI for a documentation site.
Ha! Small world! I just started building a documentation editor using markdown, built as a custom element[0]. It's still deeply in alpha, but there is a working demo, at least!
What's the advantage of using Web Components here? Why not process the tag on the server side aswell and replace it with Html?
tolerance · 4h ago
Nice to see pro-Markdown literature that extends its application, but not to the extent that (that I’ve found) its detractors use against it.
There are a lot of nooks in crannies in this article.
superkuh · 5h ago
>In the end, your document is now fully an HTML document, not a Markdown document that becomes an HTML document. It’s a minor perspective shift, but might have some cascading effects on things I’ve written above.
But this style of custom-elements requires successful javascript program execution to achieve that "HTML" document. Just like markdown requires some parser program to turn it in to HTML. It's not really fully an HTML document.
It's a good idea. It just would be a better one to write the custom-elements as wrappers for actual HTML elements. Like how https://blog.jim-nielsen.com/2023/html-web-components-an-exa... shows instead of trying to do it SPA style and requiring perfect JS execution for anything to show properly.
HTML mark-up really isn't that heavy. The avoidance of it seems mostly to be because it's considered "old" and "old" is bad, or at least not useful on a resume. But it's old because it's so good it's stuck around for a long time. Only machine generated HTML is bulky. Hand written can be just as neat and readable as any Markdown.
thangalin · 4h ago
> It just would be a better one to write the custom-elements as wrappers for actual HTML elements.
This allows separating content from presentation, allowing them to vary independently.
spankalee · 4h ago
JavaScript is one of the three core file types of the web. You can rely on it as much as HTML and CSS. I don't get the unique derision of JS compared to the other files types.
rustystump · 1h ago
Generally i agree.
I think there are a group of people who are salty that js became “the lang” for the web. Another group of people loath the framework insanity of webdev. I count myself among the ladder not the former. I equally hate all languages.
Js is heavily overused but the “web” of today is not the web of the 90s or 2010s which some people cannot get over.
superkuh · 4h ago
That's an understandable take in nearly all commercial and institutional contexts. But in others just involving human people, no. Many times JS does fail or isn't available. So building progressively enhanced web documents preserves utility across the spectrum of human visitors (and maintains accessibility). But if you only have a profit motive, then yes, there's no need for robust solutions. The amount of people that can't do JS well won't eat into profits or cause enough complaints to get you in trouble.
lelandfe · 3h ago
I think progressive enhancement is a cool approach to building stuff.
I also think “turn JS on” is a fairly reasonable ask these days. A lot of the web tends to break when CSS is disabled or fails, too.
One additional thing that article fails to mention: you should not test your device in a context where it can cool itself easily. Test on your devices when they are wrapped in a blanket, and while there's another program using 100% CPU.
rustystump · 53m ago
Your conclusion is not the same as the article you link. Js is fine but it should be used relative to the targeted use case.
That astonishingly long and researched read loses impact when it draws a primarily moral based argument in the thesis. Being fast is better for both the privileged and underprivileged.
Moral handwringing rarely moves people to action.
lelandfe · 25m ago
There's also some irony in a four part polemic about overcomplexity.
righthand · 4h ago
Always curious why no one has made Markdown + pugjs-style[0] html parsing system.
We did this a decade or two ago when Markdown was Markdown and pug was Jade. It was great.
Apart from that, also back in the day people were still building pages using e.g. Dreamweaver, so we also put together a thing that could leverage a designer's HTML that rendered as a complete placeholder page. That "works as plain .HTML" became the template, used YAML as data, and Enlive (a Clojure lib) to turn the HTML with its placeholders into a template and then stuff YAML sidecar data into it to generate new HTML.
Not long after, Caddy's markdown support had promise, but agree with another commenter here that a few years ago astro.build started hitting a more interesting spot. In the middle ages between those, yay pandoc.
It's in #6 and #7
https://spec.commonmark.org/0.31.2/#html-blocks
I too ran a site on markdown with HTML. Originally I had my own hacky way of using HTML which was effectively to (1) replace all HTML with placeholder_number (2) format the markdown (3) replace placeholder_number with the html that used to be there. Not as simple as that but close.
Eventually i switched to a commonmark spec formatter and then tried to fix any old pages that had spaces in the HTML. Some were basically hard to fix like a pre section with code inside so I added some other hacks to do the same as above for those sections by surrounding them with {{#html}}....stuff..with...blank...lines{{/html}}.
So now my solution is handlebars.js meets markdown-it.
Best of all, if you use simple unchanged files for other dynamic stuff like JSON etc, you can just generate those on build and serve those files in the host directly as the 'response' to a simple REST request, which is sometimes overlooked despite being the most fundamental form of a REST API.
https://astro.build/
I came across this after researching various options for a website that had, mostly for my own entertainment, restrictions on wanting to be mostly statically generated but customizable easily without learning a lot of new syntax / etc, something JSX-like with Markdown support etc, and MDX was an immediate find - and astro was the easiest SSG I found for it after trying with 11ty and several others. Actually felt like a delight playing with it.
- [1] https://mdxjs.com/
https://stripe.com/blog/markdoc
[0] https://github.com/catapart/magnitce-docs-editor
There are a lot of nooks in crannies in this article.
But this style of custom-elements requires successful javascript program execution to achieve that "HTML" document. Just like markdown requires some parser program to turn it in to HTML. It's not really fully an HTML document.
It's a good idea. It just would be a better one to write the custom-elements as wrappers for actual HTML elements. Like how https://blog.jim-nielsen.com/2023/html-web-components-an-exa... shows instead of trying to do it SPA style and requiring perfect JS execution for anything to show properly.
HTML mark-up really isn't that heavy. The avoidance of it seems mostly to be because it's considered "old" and "old" is bad, or at least not useful on a resume. But it's old because it's so good it's stuck around for a long time. Only machine generated HTML is bulky. Hand written can be just as neat and readable as any Markdown.
pandoc has an extension for this:
https://pandoc.org/demo/example33/8.18-divs-and-spans.html
KeenWrite, my (R) Markdown editor, supports pandoc annotations:
https://youtu.be/7icc4oZB2I4?list=PLB-WIt1cZYLm1MMx2FBG9KWzP...
> Just like markdown requires some parser program to turn it in to HTML.
Or XHTML, which is XML, which can then be transformed into TeX macros, and then typeset into a PDF file with a theme (much like CSS stylizes HTML).
https://youtu.be/3QpX70O5S30?list=PLB-WIt1cZYLm1MMx2FBG9KWzP...
This allows separating content from presentation, allowing them to vary independently.
I think there are a group of people who are salty that js became “the lang” for the web. Another group of people loath the framework insanity of webdev. I count myself among the ladder not the former. I equally hate all languages.
Js is heavily overused but the “web” of today is not the web of the 90s or 2010s which some people cannot get over.
I also think “turn JS on” is a fairly reasonable ask these days. A lot of the web tends to break when CSS is disabled or fails, too.
That astonishingly long and researched read loses impact when it draws a primarily moral based argument in the thesis. Being fast is better for both the privileged and underprivileged.
Moral handwringing rarely moves people to action.
[0] https://pugjs.org/api/getting-started.html
Apart from that, also back in the day people were still building pages using e.g. Dreamweaver, so we also put together a thing that could leverage a designer's HTML that rendered as a complete placeholder page. That "works as plain .HTML" became the template, used YAML as data, and Enlive (a Clojure lib) to turn the HTML with its placeholders into a template and then stuff YAML sidecar data into it to generate new HTML.
Not long after, Caddy's markdown support had promise, but agree with another commenter here that a few years ago astro.build started hitting a more interesting spot. In the middle ages between those, yay pandoc.