So the main advantage is that no build step is necessary to create a website based on this? But I think most websites will require a build step at some point anyway - whether it's to build CSS, optimise images, automatically create sitemaps, etc. And people who use something like Markdeep are technical so they won't mind such step.
And once it's there, I don't see the point anymore - just add a Markdown to HTML conversion to the build process and that's it. That's more robust and reliable that client side rendering.
There's lots of apps that do real-time rendering of Markdown, either for side-by-side editing, or for rendering snippets (comments, examples, etc.) that are stored as Markdown.
The main advantage is that you can write a document, send it per email or check it into a VCS and the other party can immediately see the rich rendered version without having to install anything. I don’t see much value for websites, except maybe for a blog where you want to do minimal maintenance.
The result looks beautiful but there are too many surprising magical actions for my taste. E.g., I wonder how "Last year MIT handed out 104 degrees to wombats." would be rendered.
> The result looks beautiful but there are too many surprising magical actions for my taste. E.g., I wonder how "Last year MIT handed out 104 degrees to wombats." would be rendered.
I read the linked page, but couldn't tell how it's performing its magic. Are some or all of the words you used triggers for magical actions?
I use it for documentation, notes and manuals and it’s great for that purpose. The fact that it renders out of the box greatly simplifies things, as you don’t need to deal with setting up and maintaining any infrastructure.
If you'll indulge me for a moment, I have a story to tell:
Many years ago, I had this idea of creating a documentation tool for my hobby projects that was based on Awk.
I liked Doxygen, but it was a bit heavy duty for a small C library with only a handful of functions. You could almost guarantee that Awk would be available on the system where you might be compiling the project, so you could just bundle the awk script with your sources, add two lines to your makefile and have HTML documentation ready to go.
Now I had never heard of Markdown at this time; It was before StackOverflow or GitHub was a thing (perhaps they existed, but I haven't used them yet). Therefore my syntax was a crude markup scheme that was difficult to explain and didn't always work correctly.
Skip forward a couple of years and I had the bright idea to rewrite the script to rather use a Markdown syntax. This ended up being one of those hobby projects that you never really finish, and it grew organically to include all sorts of Markdown features. The result of that effort is now on GitHub [1].
Where does Markdeep fit into all of this? Sometimes when I stumble upon a project on GitHub that I find interesting, I click on the author's name to see what other repositories they have that looks interesting. One day I browsed GitHub like that and stumbled upon user r-lyeh's `stddoc.c` file [2].
It is a C program that simply extracts the comments from your source file and appends the Markdeep tags to the end. If you save the result to a HTML file, you achieve the same result as my script, except the implementation is much much simpler.
I nearly fell off my chair when I realised that all the effort I put into my own script was basically made useless(*) by Markdeep. Instead of parsing the markdown, I could rather have had Markdeep do all the heavy lifting, and it comes with a bunch of very nice features that I doubt I'd ever be able to implement in my own script.
(*) my script strives for compatibility with GitHub-flavoured markdown, so you could do things like extract the markdown in your code comments to, say, a GitHub wiki, and the markdown flavour stays the same between your README.md and your code documentation.
This is actually how the bundled, first-party rustdoc that ships with the rust compiler works. Triple slash /// comments above public API members are extracted as-is, rendered as markdown, cross-linked to one another, and rendered to HTML.
I believe I saw this on Hackernews when this appeared earlier. However, I'm not sure where this fits in -- too complex for simple stuffs and not suitable for the complex ones either.
I also realize that the minified version is a 200+ KB file of JavaScript that one need to carry around with every simple Markdown file.
Nonetheless, I like the concept and hope I remember this when the need arises.
You might also like to look Texme[1] - Self-rendering Markdown + LaTeX documents.
15 comments
[ 3.4 ms ] story [ 47.0 ms ] threadAnd once it's there, I don't see the point anymore - just add a Markdown to HTML conversion to the build process and that's it. That's more robust and reliable that client side rendering.
I read the linked page, but couldn't tell how it's performing its magic. Are some or all of the words you used triggers for magical actions?
https://news.ycombinator.com/item?id=22348190 (360 points | 2020 | 108 comments)
https://news.ycombinator.com/item?id=10402121 (256 points | 2015 | 78 comments)
Many years ago, I had this idea of creating a documentation tool for my hobby projects that was based on Awk.
I liked Doxygen, but it was a bit heavy duty for a small C library with only a handful of functions. You could almost guarantee that Awk would be available on the system where you might be compiling the project, so you could just bundle the awk script with your sources, add two lines to your makefile and have HTML documentation ready to go.
Now I had never heard of Markdown at this time; It was before StackOverflow or GitHub was a thing (perhaps they existed, but I haven't used them yet). Therefore my syntax was a crude markup scheme that was difficult to explain and didn't always work correctly.
Skip forward a couple of years and I had the bright idea to rewrite the script to rather use a Markdown syntax. This ended up being one of those hobby projects that you never really finish, and it grew organically to include all sorts of Markdown features. The result of that effort is now on GitHub [1].
Where does Markdeep fit into all of this? Sometimes when I stumble upon a project on GitHub that I find interesting, I click on the author's name to see what other repositories they have that looks interesting. One day I browsed GitHub like that and stumbled upon user r-lyeh's `stddoc.c` file [2].
It is a C program that simply extracts the comments from your source file and appends the Markdeep tags to the end. If you save the result to a HTML file, you achieve the same result as my script, except the implementation is much much simpler.
I nearly fell off my chair when I realised that all the effort I put into my own script was basically made useless(*) by Markdeep. Instead of parsing the markdown, I could rather have had Markdeep do all the heavy lifting, and it comes with a bunch of very nice features that I doubt I'd ever be able to implement in my own script.
[1]: https://github.com/wernsey/d.awk [2]: https://github.com/r-lyeh/stddoc.c
Was there meant to be a following footnote (*)?
(*) my script strives for compatibility with GitHub-flavoured markdown, so you could do things like extract the markdown in your code comments to, say, a GitHub wiki, and the markdown flavour stays the same between your README.md and your code documentation.
YMMV on whether this is actually a useful quality
I also realize that the minified version is a 200+ KB file of JavaScript that one need to carry around with every simple Markdown file.
Nonetheless, I like the concept and hope I remember this when the need arises.
You might also like to look Texme[1] - Self-rendering Markdown + LaTeX documents.
1. https://github.com/susam/texme