Show HN: Markdown as web page/site(github.com)
github.com
Show HN: Markdown as web page/site
https://github.com/casualwriter/casual-markdown-page
59 comments
> The next question is, how would you get the second layer of github flavored markdown fluff (latex, mermaid, etc), that is generally not standardized, to be supported in browsers as well?
Don't. GFM should stand for "GitHub Flavored Markup", since that's how people treat it—yet another markup language, which they find more convenient than other markup languages. The "Markdown" as it is used on GitHub and the people who author it abandoned the premise. Markdown was intentionally designed so that the "raw" form of a given Markdown document is supposed to be a valid way for humans to consume it. That's not how Markdown is used on GitHub, however; no one pays any attention to the readability of the raw form. It's just another input for their compile-to-Web pipelines to suck in (or for github.com to render as substitute for a project landing page).
Don't. GFM should stand for "GitHub Flavored Markup", since that's how people treat it—yet another markup language, which they find more convenient than other markup languages. The "Markdown" as it is used on GitHub and the people who author it abandoned the premise. Markdown was intentionally designed so that the "raw" form of a given Markdown document is supposed to be a valid way for humans to consume it. That's not how Markdown is used on GitHub, however; no one pays any attention to the readability of the raw form. It's just another input for their compile-to-Web pipelines to suck in (or for github.com to render as substitute for a project landing page).
Docsify https://docsify.js.org
Astro https://astro.build/
Astro https://astro.build/
This requires JavaScript to dynamically serve HTML. So this wastes everybody’s CPU for a deterministic computation that could be served directly.
I’m not sure what’s the use case for this, but for static content seems wasteful and a bad idea in general.
I’m not sure what’s the use case for this, but for static content seems wasteful and a bad idea in general.
The amount of CPU waste would be negligible.
As someone who does a fair share of browsing on Tor Browser's Safest mode (JS disabled) i entirely disagree with this point. Most use of JS makes my (old) computer really slow and usually leaks memory in some way. This is true on Firefox, Chromium, and all derivatives.
Yes the performance impact of a single "alert()" when i open the page is negligible. The performance impact of parsing Markdown and rendering it as HTML nodes is definitely non-negligible.
I love the idea to support more markdown formats natively for the web (eg. markdown), but i hate client-side scripting shenanigans that don't respect me as a user without the fancy latest iphone. If only some browsers were concerned about emerging protocols/formats & UX instead of increasingly-useless (except for tracking purposes) JS APIs...
Yes the performance impact of a single "alert()" when i open the page is negligible. The performance impact of parsing Markdown and rendering it as HTML nodes is definitely non-negligible.
I love the idea to support more markdown formats natively for the web (eg. markdown), but i hate client-side scripting shenanigans that don't respect me as a user without the fancy latest iphone. If only some browsers were concerned about emerging protocols/formats & UX instead of increasingly-useless (except for tracking purposes) JS APIs...
Why do you use TOR and have JS disabled?
The Grav CMS also internally uses Markdown for the page contents and generates static files: https://getgrav.org/
They do use YAML FrontMatter for attaching metadata so the CMS knows how to process certain pages (e.g. page title, page type etc.), but it isn't too complicated in practice: https://learn.getgrav.org/17/content/content-pages#page-file
They also have an admin plugin, which you can use if you prefer a more traditional workflow, even if it just generates the same file format under the hood: https://learn.getgrav.org/16/admin-panel/introduction
I'm actually using an ancient version of Grav for my own blog, although I had to put the admin path behind additional auth (in addition to the one it already provides), for safety: https://blog.kronis.dev/
I really like hybrid systems like that: a CMS for blogging or just writing in general that's based on Markdown, generates static files for decent performance, but is also extensible with additional functionality, and also has a decent web UI if you want one.
(there are probably other CMSes like that out there, or more generic solutions, too)
Of course, the actual use case for the linked solution is a bit different, being able to dynamically render Markdown client side is also pretty cool! Feels almost more flexible in a way.
They do use YAML FrontMatter for attaching metadata so the CMS knows how to process certain pages (e.g. page title, page type etc.), but it isn't too complicated in practice: https://learn.getgrav.org/17/content/content-pages#page-file
They also have an admin plugin, which you can use if you prefer a more traditional workflow, even if it just generates the same file format under the hood: https://learn.getgrav.org/16/admin-panel/introduction
I'm actually using an ancient version of Grav for my own blog, although I had to put the admin path behind additional auth (in addition to the one it already provides), for safety: https://blog.kronis.dev/
I really like hybrid systems like that: a CMS for blogging or just writing in general that's based on Markdown, generates static files for decent performance, but is also extensible with additional functionality, and also has a decent web UI if you want one.
(there are probably other CMSes like that out there, or more generic solutions, too)
Of course, the actual use case for the linked solution is a bit different, being able to dynamically render Markdown client side is also pretty cool! Feels almost more flexible in a way.
Thank you for mentioning Grav CMS. It was particularly interesting to hear about the concept of "admin panel as a plugin". I like that idea very much, it's perfect for API-first design.
At work I've been trying to solve the question, how can we let the dev team continue to write documentation as Markdown files in Git repos, while not excluding others in the company who need/prefer GUI and rich text editor. I see now that it's possible to have the best of both worlds, with admin UI as a layer on top of the same underlying system, generating Markdown internally.
Still not sure how such an admin interface will integrate with Git though. I suppose "publish" can trigger a Git commit, but I wonder if it's feasible to ensure no Git push conflict when remote is ahead of local, i.e., someone else pushed a change before you did. Otherwise, I imagine the admin UI can get complex if it needs to provide a way to resolve such conflicting changes, with a side-by-side view of diffs.
At work I've been trying to solve the question, how can we let the dev team continue to write documentation as Markdown files in Git repos, while not excluding others in the company who need/prefer GUI and rich text editor. I see now that it's possible to have the best of both worlds, with admin UI as a layer on top of the same underlying system, generating Markdown internally.
Still not sure how such an admin interface will integrate with Git though. I suppose "publish" can trigger a Git commit, but I wonder if it's feasible to ensure no Git push conflict when remote is ahead of local, i.e., someone else pushed a change before you did. Otherwise, I imagine the admin UI can get complex if it needs to provide a way to resolve such conflicting changes, with a side-by-side view of diffs.
Conflicts are not caused by git, they're caused by simultaneous edits. You'd have to solve that problem whatever your backend.
I use this one which is also nice: https://github.com/oscarmorrison/md-page
Don’t forget, Caddy can also serve markdown directly via module:
https://caddyserver.com/docs/modules/http.handlers.templates
Believe there may also be something similar for Apache?
Believe there may also be something similar for Apache?
Unfortunately it won't display without JavaScripts. You can easily fix this by a <noscript> block with the link to the Markdown file; if it is not possible, instead include a description about how to find the Markdown file.
Another alternative that I would suggest is to just serve the files directly (in Markdown or Gemini or PDF or whatever other format they might be). To allow working in a web browser, one idea is to try to implement my idea of a Interpreter response header in web browser, which would be used if the web browser does not understand the file format (if the user has not disabled the use of the Interpreter header). This way, potentially any file format can be implemented.
There is also question about different variants of Markdown. Well, the way to indicate that is by parameters in the MIME type, I think; you can specify if it is Commonmark or something else. This way you can tell which variant it is.
One problem with MIME is that indicating multiple file formats does not work very well. UTI specifies that it is a specific kind of another file format but it must be specified in another file instead of this one and does not have parameters, and has other problems, so UTI is not good either. That is why I wanted to make the "unordered labels file identification" which you can specify, in the same identification, multiple types/parameters, e.g. "text[367]:plaintext:markdown+commonmark".
Another alternative that I would suggest is to just serve the files directly (in Markdown or Gemini or PDF or whatever other format they might be). To allow working in a web browser, one idea is to try to implement my idea of a Interpreter response header in web browser, which would be used if the web browser does not understand the file format (if the user has not disabled the use of the Interpreter header). This way, potentially any file format can be implemented.
There is also question about different variants of Markdown. Well, the way to indicate that is by parameters in the MIME type, I think; you can specify if it is Commonmark or something else. This way you can tell which variant it is.
One problem with MIME is that indicating multiple file formats does not work very well. UTI specifies that it is a specific kind of another file format but it must be specified in another file instead of this one and does not have parameters, and has other problems, so UTI is not good either. That is why I wanted to make the "unordered labels file identification" which you can specify, in the same identification, multiple types/parameters, e.g. "text[367]:plaintext:markdown+commonmark".
Great idea. Keep expanding it as you have time.
thanks. working on markdown-as-blog...
Maybe you can see rentry.co for inspiration.
I'm doing something similar for my personal notes but I combine .md and .html into 1 file. My .html file looks like this:
<html>
<body>
<div class="accordion">
<div class="accordion-item" title="...">
text with markdown syntax goes here
</div>
</div>
<script>
// use showdown.js to convert the innerHTMLin .md syntax to html code
// use bootstrap to make the accordion-item collapsible/expandable
// use js to make a floating TOC
</script>
</body>
</html>
org-mode already has this. Unfortunately, people seem to continue to use the inferior version of org known as Markdown. It is somewhat like how pdf overtook the superior format djvu.
I agree that Markdown is probably an inferior markup format compared to org but serious usage of org is tied to Emacs. Moreover, Markdown (or CommonMark) has an extremely healthy ecosystem and a lot of tools that make life easier, unlike org mode. The most popular static site generators also use Markdown and RST.
Unless using Emacs becomes a user friendly beginner's choice (which it isn't, and that's fine) or Org is able to distinguish itself in isolation from Emacs, I don't see org being widely used anytime soon. If org gains first class support in editors like neovim, vscode and tools like pandoc, mdcat etc, I could see myself using it.
Unless using Emacs becomes a user friendly beginner's choice (which it isn't, and that's fine) or Org is able to distinguish itself in isolation from Emacs, I don't see org being widely used anytime soon. If org gains first class support in editors like neovim, vscode and tools like pandoc, mdcat etc, I could see myself using it.
A handful of folks, myself included, are breaking org out of Emacs, making it more accessible to all.
I built two apps for iOS:
https://flathabits.com
https://plainorg.com
There are other org-based tools out there.
https://BrainTool.org
https://logseq.com
https://orgzly.com
https://beorg.app
https://easyorgmode.com
https://organice.200ok.ch
https://orgro.org
I built two apps for iOS:
https://flathabits.com
https://plainorg.com
There are other org-based tools out there.
https://BrainTool.org
https://logseq.com
https://orgzly.com
https://beorg.app
https://easyorgmode.com
https://organice.200ok.ch
https://orgro.org
There's actually a quite featureful version of org for Neovim: nvim-orgmode https://github.com/nvim-orgmode/orgmode
Richard P. Gabriel (who every Emacs person should know) wrote "Worse is Better"[1] in 1984, which is directly applicable. To summarise, "worse" software prioritises simplicity of implementation and priortises simplicity over correctness.
[1] https://www.dreamsongs.com/RiseOfWorseIsBetter.html
[1] https://www.dreamsongs.com/RiseOfWorseIsBetter.html
so true! markdown is also about simplicity, which is this project try to follow
yes. markdown is html as org-mode, which suitable for web content. web page normally has some add-on components, e.g. header, menu, theme, this is a try to handle them within markdown.
Make Orgdown a real thing and you would have an argument.
org mode is for cli nerds.
I use Markdeep for the same application:
https://casual-effects.com/markdeep/
https://casual-effects.com/markdeep/
I did something similar, but for adding a blog system to a server running PHP: https://github.com/Cristy94/markdown-blog
The idea is that having it server-side allows for the page to be cached by a CDN (e.g. CloudFlare), so you end up serving static HTML, with better performance and SEO than JS-compiled markdown.
The idea is that having it server-side allows for the page to be cached by a CDN (e.g. CloudFlare), so you end up serving static HTML, with better performance and SEO than JS-compiled markdown.
The heavy lifting seems to be actually done via:
https://cdn.jsdelivr.net/gh/casualwriter/casual-markdown/dis...
Which isn't in the github repo.
https://cdn.jsdelivr.net/gh/casualwriter/casual-markdown/dis...
Which isn't in the github repo.
It's in a sibling repo: https://github.com/casualwriter/casual-markdown
it is github cdn. yes it is mardown parser doing 90% job, but only got 1 star. can someone give it a star?
What about Markdeep? Astonished that none of the commenters here seem to know of its existence. See https://casual-effects.com/markdeep/.
I visited the documentation site on a slow mobile connection and it took a long time and even a refresh to load. This seems to be a bad way of doing something that has been solved by static site generators for a long time.
seems not lightweight enough. i will work out a self-sufficient all-in-one verson in 300 lines.
Do you have any examples of what a web site would look like with this?
I was under the impression that using markdown to create html webpages was a common use case, and had been solved. Was I wrong?
(I've used markdown for note taking, not for web pages, hence am asking.)
(I've used markdown for note taking, not for web pages, hence am asking.)
Curious if we've ever considered adding Markdown as a new MIME type that could be accepted directly by browsers (similar to text/plain). It could be nice to serve markdown without needing to even use a static-site generator (but still have the server reasonably render the doc, similar to a reader view).
Beaker Browser did this. The first problem about Markdown is: which variant do you support? The second problem is that people already treat it like a markup language with a mandatory post-processing step and will inevitably desire the level of control/precision that can only be achieved by making it more like HTML (or making liberal use of the <html> escape hatch).
I was under the same impression as well. I have been using https://docusaurus.io/ for some time now and I am very happy with it and I am pretty sure there are other tools out there as well.
reminds me of Znai [1]
What sold me on Znai was the integration of code snippets (straight from source files, mining them out of the code) and integration of diagramming from PlantUML, which is done in a way that is compatible with the format used in Gitlab, VSCode and other markdown renderers.
Markdown has turned into a truly amazing ecosystem.
[1] https://testingisdocumenting.org/znai/introduction/what-is-t...
What sold me on Znai was the integration of code snippets (straight from source files, mining them out of the code) and integration of diagramming from PlantUML, which is done in a way that is compatible with the format used in Gitlab, VSCode and other markdown renderers.
Markdown has turned into a truly amazing ecosystem.
[1] https://testingisdocumenting.org/znai/introduction/what-is-t...
I am hesitant to give it a try. Mostly use sphinx and .rst - docusaurus looks nice but also overengineered.
Is it a lot to set up or is it just markdown all the way and works out of the box?
Is it a lot to set up or is it just markdown all the way and works out of the box?
It only takes a few minutes to set it up. I use it for my blog, very happy with it.
It really looks great. I like your book section - I wonder why we read the same books. HN recommendations maybe; will look into the ones I didn't read. Thanks for sharing
glad to know that.
As far as i know
[1] https://www.mkdocs.org : Markdown to static web page converter
[2] https://rentry.co : Markdown pastebin
[3] https://prose.sh : Markdown blog, upload post via ssh
[4] https://bearblog.dev : Markdown blog, upload post via web-browser
[1] https://www.mkdocs.org : Markdown to static web page converter
[2] https://rentry.co : Markdown pastebin
[3] https://prose.sh : Markdown blog, upload post via ssh
[4] https://bearblog.dev : Markdown blog, upload post via web-browser
There's just a ton of libraries around it. I've used Markdowndeep in C#. I forget all the ones I tried (at least 3) before I settled on that one.
A colleague just mentioned this to me a few days ago:
https://docs.microsoft.com/en-us/powershell/module/microsoft...
A colleague just mentioned this to me a few days ago:
https://docs.microsoft.com/en-us/powershell/module/microsoft...
The usual approach is to compile markdown to html either before uploading to server or server side.
My understanding is this renders markdown to html client side using JavaScript
My understanding is this renders markdown to html client side using JavaScript
good point. markdown as web content is widely used, but not whole web page. the project is a sample to use markdown as whole page by putting web element (header,ment,theme) in frontmater.
Why not rendering a whole site from markdown to HTML in a Cloudflare worker (with cache) instead of on the browser? SEO would benefit too.
I've been using docsify in this manner for a while and it's worked well for me
What's the reason for supporting IE9?
it is coded in vanilla javascript. i do nothing to cater IE9, it just run well. btw, believe there are some scenarios to load page within IE9 (e.g. OLE control, hta script)
FWIW there's nothing about "vanilla JavaScript" that means IE9 will be supported. It's avoiding certain language features and DOM APIs that does it.
Just adding this because it can lead to the implication that not supporting IE9 means you're trying to do something frivolous as opposed to "vanilla JavaScript".
Just adding this because it can lead to the implication that not supporting IE9 means you're trying to do something frivolous as opposed to "vanilla JavaScript".
Hugo
This reminds me of MDWiki: https://dynalon.github.io/mdwiki/
just check it. it is a great project. same design idea, more sophisticated for advanced usage.
[deleted]
But this (along with md-page and mdwiki mentioned in other comments) is actually an interesting small twist on it. Regularly the conversion is done on the server side, and everything is published in html.
Here, you both author and publish in markdown.
What this library does, if I'm reading it correctly, it acts as polyfill that lets legacy evergreen browsers to consume the markdown files that you serve.
You can publish your content in a bit more simpler, yet still declarative format, without any javascript, and still make it accessible, in a properly rendered format, for evergreen browsers.
(Yes, you can still add javascript to markdown files, but it is relatively easy for the agent to just discard any javascript or html.)
The markdown is the source of truth here. No need for rendering everything twice for serving, once for html and once for markdown, and creating a point where their content might diverge.
It's straight out of gemini's playbook.
I think this is a wonderful idea, and if developed a bit further, and adopted more widely, could help push markdown to be a properly supported format in modern browsers.
The next question is, how would you get the second layer of github flavored markdown fluff (latex, mermaid, etc), that is generally not standardized, to be supported in browsers as well?