>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.
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.
Built a few reusable templates and JSON for storing game data (maybe not ideal at scale, but seems to be working for now). JavaScript, CSS, and MDX. Hosted on Netlify which is an 'Official Deployment Partner'. It's light and simple. So far has been a joy to work with.
> 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
Other web frameworks support this too, if you look for "static export" options. Next.js, for example, supports this via the getInitialProps function.
What I like especially about Astro, that you perform this data loading during build time from any component/file on your page. With Next.js, this is only possible via the top level Page component.
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!
Because if you're relying on server-side software to process your finished product, then your finished product is vulnerable to dependency rot and overall general software rot.
But if you process your markup at build time into it's finished HTML, then you can host it anywhere - anytime and it'll work.
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.
I've recently hit a very similar problem. There's various problems with the web components (like he mentions) and I wanted a better way to write plain html with components. I ended up making a tiny python build script to process fake html components into proper HTML: https://github.com/shminge/builder
I've designed it for myself, deliberately to work around the flaws with web components mentioned. It hugely speeds up my process of writing pages for my blog (after trying everything, I've ended up just writing plain html) because I can define a component that holds all the boilerplate of the page (header, css, etc) and then write my pages as `<pagelayout> <p> body content here </p> </pagelayout>` and have that be expanded into proper valid HTML
My tool of choice for what TFA describes is Vitepress. Markdown plus about a dozen useful plugins and understands Vue3 components and treats each *.md as an SFC.
It certainly is a joy! I'd generalise it to any reasonable plaintext format.
Org mode keeps me locked in for this very reason.
No need for Emacs... pandoc (which I use) builds my static site. It supports enough Org markup to let me compile header metadata, latex, footnotes, markup etc. as well as inline live JavaScript code and use it in-page, just like I'd do in a regular stand-alone HTML page.
For example: a post with inlined static HTML and JavaScript, freely mixed-and-matched with org-native source block syntax. No plugins needed.
Github-rendered in repo (not github pages): It is (surprisingly) good enough for most Org content, including generating a nice Table of Contents... Except for any footnotes, and inlined or hosted JavaScript source (understandably, security may be a concern). https://github.com/adityaathalye/shite/blob/master/sources/p...
24 comments
[ 3.1 ms ] story [ 44.1 ms ] threadBut 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.
[0] https://pugjs.org/api/getting-started.html
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.
Built a few reusable templates and JSON for storing game data (maybe not ideal at scale, but seems to be working for now). JavaScript, CSS, and MDX. Hosted on Netlify which is an 'Official Deployment Partner'. It's light and simple. So far has been a joy to work with.
Other web frameworks support this too, if you look for "static export" options. Next.js, for example, supports this via the getInitialProps function.
What I like especially about Astro, that you perform this data loading during build time from any component/file on your page. With Next.js, this is only possible via the top level Page component.
And if using app router model, that is part of React server components.
There are a lot of nooks in crannies in this article.
- [1] https://mdxjs.com/
MDX is great and I like to use it.
[0] https://github.com/catapart/magnitce-docs-editor
https://stripe.com/blog/markdoc
I wrote quite a bit about Fluid, which is the C# implementation of Liquid. https://deanebarker.net/tech/fluid/
But if you process your markup at build time into it's finished HTML, then you can host it anywhere - anytime and it'll work.
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.
I've designed it for myself, deliberately to work around the flaws with web components mentioned. It hugely speeds up my process of writing pages for my blog (after trying everything, I've ended up just writing plain html) because I can define a component that holds all the boilerplate of the page (header, css, etc) and then write my pages as `<pagelayout> <p> body content here </p> </pagelayout>` and have that be expanded into proper valid HTML
It hits a sweet spot for me.
(I swear, I have never tried to do something this foolish… I swear…)..."
I will say, that almost didn't make me laugh, bur, I will not swear.
I've recently come off from one such rabbit hole - A CLI tool for Pre-processing vue project templates. It was over-engineered.
Will probably go back to re-build it when I get the free time.
└── Dey well; Be well
Org mode keeps me locked in for this very reason.
No need for Emacs... pandoc (which I use) builds my static site. It supports enough Org markup to let me compile header metadata, latex, footnotes, markup etc. as well as inline live JavaScript code and use it in-page, just like I'd do in a regular stand-alone HTML page.
For example: a post with inlined static HTML and JavaScript, freely mixed-and-matched with org-native source block syntax. No plugins needed.
Raw: https://raw.githubusercontent.com/adityaathalye/shite/refs/h...
Pandoc-rendered live site: Compare Raw source with this section: https://www.evalapply.org/posts/animate-text-art-javascript/...
Github-rendered in repo (not github pages): It is (surprisingly) good enough for most Org content, including generating a nice Table of Contents... Except for any footnotes, and inlined or hosted JavaScript source (understandably, security may be a concern). https://github.com/adityaathalye/shite/blob/master/sources/p...