6 ms·

Show HN: Md2blog – A zero-config static site generator for dev blogs

60 points by schemescape 5y ago

threatofrain 5y ago
Do you have plans for Latex by any chance?
- schemescape 5y ago
  Do you mean embedding Latex in a Markdown code block and having that render at build time (perhaps to SVG) that is embedded in (or linked from) HTML? If so, that might be something I could look into. Version 1 of md2blog actually did almost exactly that for Graphviz diagrams (but I removed that feature because, frankly, I didn't understand the Graphviz license). A quick look indicates that Latex also has its own unique license that is... quite lengthy.
  - powersnail 5y ago
    Mathjax has server-side rendering now, which could be used for this purpose.
- shoo 5y ago
  I recently wrote a few documents in latex after ignoring it for over a decade. Trying to get a working setup with latex + bibtex + a few custom styles was quite annoying (and i work as a backend developer, so i probably tolerate annoying command line tools more than most people). I can appreciate that people (e.g. researchers) who just want to author a document with some equations in latex but who are not programmers or avid command line users might find the entire experience of getting a tolerable latex workflow set up very challenging. I guess that might be partly why https://www.overleaf.com/ https://www.overleaf.com/ has a business model! Hide all the package management and command line tooling nonsense behind a simple web interface. I was very excited to find Thomas Weise had wrangled latex and a Tex Live installation into a docker container: https://github.com/thomasWeise/docker-texlive-thin https://github.com/thomasWeise/docker-texlive-thin Another useful tool is latexmk, which is already installed inside the docker-texlive-thin container : https://mg.readthedocs.io/latexmk.html https://mg.readthedocs.io/latexmk.html By containing the madness of latex tooling and package management with docker and some volume mounts, I could have a reasonably sane build process to manufacture PDFs from latex source files. I don't recommend md2blog add mandatory dependencies on anything related to latex. Another way to think about it might be offering optional latex support through some md2blog plugin mechanism that doesn't know anything about latex. But that path sure won't produce anything resembling a "zero config" static site generator! Might end up with something closer to apache httpd.
philipwhiuk 5y ago
> Instead of fiddling with options and themes, your focus is strictly on writing and publishing content. > FAQ (e.g. themes, command line options, support) Just saying. In the long term I suspect Md2blog will evolve to be little different to Jekyll.
- schemescape 5y ago
  My solution to scope creep was to put the "generic static site generator" part in a separate library (modeled after Metalsmith), so that I can leave md2blog as featureless as possible.
- Zababa 5y ago
  The thing is that this cycle is important, because you can learn it when it's easy to learn and as it evolves. Jekyll has been very frustrating for me to learn because of all the accumulated cruft, even if it solves very real problems. Sometimes you just need to restart to get the new people on board.
4kelly 5y ago
I definitely have spent too long learning and fiddling with SSG’s. Going to give this a try!
- schemescape 5y ago
  I’d greatly appreciate it if you let me know how it goes (even if you hate it). I built it for my own needs, but I’d like to know if anyone else finds it useful. Thanks!
  - 4kelly 5y ago
    So far so good! It matches my desired style and feature set, so I’m probably the ideal candidate ahah. Left a GitHub issue with the precompiled binary install. But it might be my fault. The closest thing to this in terms of out of the box simplicity is probably Material theme for MkDocs [1], which has other features, but no official blog support. [1] https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/
olaven 5y ago
This looks great! I actually made a very similar tool called Markblog[1]. We did a lot the same way (even using Deno!), but we did themes a little differently. I used custom CSS-files, but your approach is even simpler. Not to detract from Md2blog, I just want to add it to the converstaion for anyone interested in these things :) Keep up! [1]: https://github.com/olaven/markblog https://github.com/olaven/markblog
- schemescape 5y ago
  Thanks for sharing! Is there an example site built with Markblog? I didn’t see a link in the readme. It certainly sounds very similar! Edit: Found this link on the Markblog docs: https://olaven.org/ https://olaven.org/ Edit again: I like that you appear to have an automated approach to deploying to GitHub Pages.
  - olaven 5y ago
    Thanks for checking it out! Yeah, like you I made it for personal use :) Thank you!
cxr 5y ago
It would be nice if as part of the zero config effort, programs (esp. programs that aim to be easy-to-use Web-authoring tools) would focus even more on being as close to zero setup/zero installation as possible, too. To wit: This program is written in TypeScript, a browser-incompatible dialect of JS that is nonetheless regularly compiled to standard JS, e.g. to transform a given module into a form that can run in the browser—and yet md2blog itself doesn't. You are expected to either download an out-of-band, platform-specific binary or use Deno to run it. Instead, one should be able to use md2blog and similar programs by using the browser itself to open and run the program, considering it's the universal platform that everyone already has, and it's reasonable to expect that you're going to use it at some point in the pipeline, anyway (e.g. for proofing your work). Even better quick start instructions would look something like this: 0. Start with a directory that contains the site sources that you intend to publish. 1. Save a copy of "md2blog.html" there, too (or anywhere, really). 2. Open the md2blog program in your browser by double clicking md2blog.html. 3. Drag and drop the directory with your Markdown sources (same one from steps 0 and 1) into the newly opened md2blog tab. (For good measure, a copy of these quick start instructions would be shown when you open md2blog.html.)
- dvtrn 5y ago
  Your instructions sound like the description for tiddlywiki.
  - deleted 5y ago
    [deleted]
- schemescape 5y ago
  I much prefer tools that run in a browser (both for convenience and for sand-boxing), but... I think a command line tool is better for a simple file system-based case like this, at least beyond an initial first impression. My workflow is that I write my posts in VS Code, and then if I want to preview or upload, I just hop over to the console and type a command (no mouse needed). Deno's built-in sand boxing is the most convenient command line alternative to browser-based apps that I'm aware of. Edit to add: I have toyed with the idea of integrating VS Code's Monaco editor into a "dev blog in your browser" type of app, but (the last time I checked) durable storage for web app data wasn't reliable (it was more intended to be a cache). Maybe things have changed.
alphabet9000 5y ago
the layout of the demo blog looks really nice, loads immediately, no bloat
- schemescape 5y ago
  Yes, the bloat (e.g. Facebook/Twitter logos) associated with many themes for other static site generators was one of the aspects that drove me to create md2blog's templates from scratch, by hand.
4kelly 5y ago
Perhaps out of scope for your use case, but what’s the status of SEO support? Using frontmatter to generate basic meta tags, twitter/open graph for pretty links, etc. Might be a useful FAQ entry.
- schemescape 5y ago
  md2blog automatically adds the following meta tags: description, keywords. The "keywords" tag includes both the post's category (derived from the parent directory name), as well as any keywords specified in YAML front matter. I don't use Twitter/Facebook, so I wasn't aware of Open Graph. That might be worth looking into. I'm familiar with the concept, but didn't realize there was a standard.
  - mattowen_uk 5y ago
    Horrible though it is, you need to include all the Opengraph tags for Facebook and Twitter, as a) thats how the preview cards are built when sharing over social media, and b) google uses them as good SEO markers. Google have also said in the past, they don't use the 'keywords' meta tag for SEO anymore, due the abuse it gets.
4kelly 5y ago
Love the style and configs! Feature suggestion that I think fits the minimalist style. Support an optional “footer” argument in ‘site.json’. Useful for copyright, social links, ??
- schemescape 5y ago
  Not having some way to specify copyright, etc. is an oversight on my part. Thanks!
MathMonkeyMan 5y ago
Always interesting to see what someone else came up with for their static site generator. If I had known about yours, I might have used it instead of writing mine: https://github.com/dgoffredo/dgoffredo.github.io https://github.com/dgoffredo/dgoffredo.github.io
scary-size 5y ago
Static websites are great! I would love for them to be more popular. But a lot of people are locked out by the technical hurdle. "Just use <SSG> and host on <github/netlify/whatever>" does not work for your aunt, parent or SO. I've tried and went into a different direction and created a desktop app [1] for creating a basic website. Yes it's electron and yes it currently only uploads to Vercel for hosting. But those are things my dad does not care about. I can send him a pre-configured "project" file, so he does not even have to enter any API keys. EDIT: I've re-read this and this sounds like I'm ranting on your project. Not my intention, I love the bloat free sites md2blog generates. Keep it up! [1]: https://www.project-daily.com https://www.project-daily.com
jerjerjer 5y ago
What do you think about Hugo [1]? It supports markdown. Also thinking about hosting a static blog and don't know what ssg from md to choose. [1] https://gohugo.io/ https://gohugo.io/
- schemescape 5y ago
  I like that Hugo ships in a single binary and has a security model around themes. But I found Hugo’s template language to have the most unusual/unintuitive template language of any SSG I tried. In the end, it comes down to personal preference: Are you going to build your own templates or use a canned theme? If DIY, make sure you like the template language, otherwise make sure you can find a theme you like. This ruled out Hugo for me because I didn’t like the template language. Do you think you’ll need to write code to perfect your workflow? If so, use one in a language you’re familiar with. Otherwise, just make sure you can tolerate the install/setup process. This ruled out Jekyll/Pelican for me. If you’re using an SSG with a plug-in architecture, what’s the security model and are you comfortable with it? Security concerns around huge dependency trees pushed me away from Metalsmith.
  - jerjerjer 5y ago
    Thanks!
dmje 5y ago
Literally zero config: wordpress.com

60 points by schemescape 5y ago

threatofrain 5y ago

Do you have plans for Latex by any chance?

schemescape 5y ago
Do you mean embedding Latex in a Markdown code block and having that render at build time (perhaps to SVG) that is embedded in (or linked from) HTML? If so, that might be something I could look into. Version 1 of md2blog actually did almost exactly that for Graphviz diagrams (but I removed that feature because, frankly, I didn't understand the Graphviz license). A quick look indicates that Latex also has its own unique license that is... quite lengthy.
- powersnail 5y ago
  Mathjax has server-side rendering now, which could be used for this purpose.
shoo 5y ago
I recently wrote a few documents in latex after ignoring it for over a decade. Trying to get a working setup with latex + bibtex + a few custom styles was quite annoying (and i work as a backend developer, so i probably tolerate annoying command line tools more than most people). I can appreciate that people (e.g. researchers) who just want to author a document with some equations in latex but who are not programmers or avid command line users might find the entire experience of getting a tolerable latex workflow set up very challenging. I guess that might be partly why https://www.overleaf.com/ https://www.overleaf.com/ has a business model! Hide all the package management and command line tooling nonsense behind a simple web interface. I was very excited to find Thomas Weise had wrangled latex and a Tex Live installation into a docker container: https://github.com/thomasWeise/docker-texlive-thin https://github.com/thomasWeise/docker-texlive-thin Another useful tool is latexmk, which is already installed inside the docker-texlive-thin container : https://mg.readthedocs.io/latexmk.html https://mg.readthedocs.io/latexmk.html By containing the madness of latex tooling and package management with docker and some volume mounts, I could have a reasonably sane build process to manufacture PDFs from latex source files. I don't recommend md2blog add mandatory dependencies on anything related to latex. Another way to think about it might be offering optional latex support through some md2blog plugin mechanism that doesn't know anything about latex. But that path sure won't produce anything resembling a "zero config" static site generator! Might end up with something closer to apache httpd.

philipwhiuk 5y ago

> Instead of fiddling with options and themes, your focus is strictly on writing and publishing content. > FAQ (e.g. themes, command line options, support) Just saying. In the long term I suspect Md2blog will evolve to be little different to Jekyll.

schemescape 5y ago
My solution to scope creep was to put the "generic static site generator" part in a separate library (modeled after Metalsmith), so that I can leave md2blog as featureless as possible.
Zababa 5y ago
The thing is that this cycle is important, because you can learn it when it's easy to learn and as it evolves. Jekyll has been very frustrating for me to learn because of all the accumulated cruft, even if it solves very real problems. Sometimes you just need to restart to get the new people on board.

4kelly 5y ago

I definitely have spent too long learning and fiddling with SSG’s. Going to give this a try!

schemescape 5y ago
I’d greatly appreciate it if you let me know how it goes (even if you hate it). I built it for my own needs, but I’d like to know if anyone else finds it useful. Thanks!
- 4kelly 5y ago
  So far so good! It matches my desired style and feature set, so I’m probably the ideal candidate ahah. Left a GitHub issue with the precompiled binary install. But it might be my fault. The closest thing to this in terms of out of the box simplicity is probably Material theme for MkDocs [1], which has other features, but no official blog support. [1] https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/

olaven 5y ago

This looks great! I actually made a very similar tool called Markblog[1]. We did a lot the same way (even using Deno!), but we did themes a little differently. I used custom CSS-files, but your approach is even simpler. Not to detract from Md2blog, I just want to add it to the converstaion for anyone interested in these things :) Keep up! [1]: https://github.com/olaven/markblog https://github.com/olaven/markblog

schemescape 5y ago
Thanks for sharing! Is there an example site built with Markblog? I didn’t see a link in the readme. It certainly sounds very similar! Edit: Found this link on the Markblog docs: https://olaven.org/ https://olaven.org/ Edit again: I like that you appear to have an automated approach to deploying to GitHub Pages.
- olaven 5y ago
  Thanks for checking it out! Yeah, like you I made it for personal use :) Thank you!

cxr 5y ago

It would be nice if as part of the zero config effort, programs (esp. programs that aim to be easy-to-use Web-authoring tools) would focus even more on being as close to zero setup/zero installation as possible, too. To wit: This program is written in TypeScript, a browser-incompatible dialect of JS that is nonetheless regularly compiled to standard JS, e.g. to transform a given module into a form that can run in the browser—and yet md2blog itself doesn't. You are expected to either download an out-of-band, platform-specific binary or use Deno to run it. Instead, one should be able to use md2blog and similar programs by using the browser itself to open and run the program, considering it's the universal platform that everyone already has, and it's reasonable to expect that you're going to use it at some point in the pipeline, anyway (e.g. for proofing your work). Even better quick start instructions would look something like this: 0. Start with a directory that contains the site sources that you intend to publish. 1. Save a copy of "md2blog.html" there, too (or anywhere, really). 2. Open the md2blog program in your browser by double clicking md2blog.html. 3. Drag and drop the directory with your Markdown sources (same one from steps 0 and 1) into the newly opened md2blog tab. (For good measure, a copy of these quick start instructions would be shown when you open md2blog.html.)

dvtrn 5y ago
Your instructions sound like the description for tiddlywiki.
- deleted 5y ago
  [deleted]
schemescape 5y ago
I much prefer tools that run in a browser (both for convenience and for sand-boxing), but... I think a command line tool is better for a simple file system-based case like this, at least beyond an initial first impression. My workflow is that I write my posts in VS Code, and then if I want to preview or upload, I just hop over to the console and type a command (no mouse needed). Deno's built-in sand boxing is the most convenient command line alternative to browser-based apps that I'm aware of. Edit to add: I have toyed with the idea of integrating VS Code's Monaco editor into a "dev blog in your browser" type of app, but (the last time I checked) durable storage for web app data wasn't reliable (it was more intended to be a cache). Maybe things have changed.

alphabet9000 5y ago

the layout of the demo blog looks really nice, loads immediately, no bloat

schemescape 5y ago
Yes, the bloat (e.g. Facebook/Twitter logos) associated with many themes for other static site generators was one of the aspects that drove me to create md2blog's templates from scratch, by hand.

4kelly 5y ago

Perhaps out of scope for your use case, but what’s the status of SEO support? Using frontmatter to generate basic meta tags, twitter/open graph for pretty links, etc. Might be a useful FAQ entry.

schemescape 5y ago
md2blog automatically adds the following meta tags: description, keywords. The "keywords" tag includes both the post's category (derived from the parent directory name), as well as any keywords specified in YAML front matter. I don't use Twitter/Facebook, so I wasn't aware of Open Graph. That might be worth looking into. I'm familiar with the concept, but didn't realize there was a standard.
- mattowen_uk 5y ago
  Horrible though it is, you need to include all the Opengraph tags for Facebook and Twitter, as a) thats how the preview cards are built when sharing over social media, and b) google uses them as good SEO markers. Google have also said in the past, they don't use the 'keywords' meta tag for SEO anymore, due the abuse it gets.

4kelly 5y ago

Love the style and configs! Feature suggestion that I think fits the minimalist style. Support an optional “footer” argument in ‘site.json’. Useful for copyright, social links, ??

schemescape 5y ago
Not having some way to specify copyright, etc. is an oversight on my part. Thanks!

MathMonkeyMan 5y ago

Always interesting to see what someone else came up with for their static site generator. If I had known about yours, I might have used it instead of writing mine: https://github.com/dgoffredo/dgoffredo.github.io https://github.com/dgoffredo/dgoffredo.github.io

scary-size 5y ago

Static websites are great! I would love for them to be more popular. But a lot of people are locked out by the technical hurdle. "Just use <SSG> and host on <github/netlify/whatever>" does not work for your aunt, parent or SO. I've tried and went into a different direction and created a desktop app [1] for creating a basic website. Yes it's electron and yes it currently only uploads to Vercel for hosting. But those are things my dad does not care about. I can send him a pre-configured "project" file, so he does not even have to enter any API keys. EDIT: I've re-read this and this sounds like I'm ranting on your project. Not my intention, I love the bloat free sites md2blog generates. Keep it up! [1]: https://www.project-daily.com https://www.project-daily.com

jerjerjer 5y ago

What do you think about Hugo [1]? It supports markdown. Also thinking about hosting a static blog and don't know what ssg from md to choose. [1] https://gohugo.io/ https://gohugo.io/

schemescape 5y ago
I like that Hugo ships in a single binary and has a security model around themes. But I found Hugo’s template language to have the most unusual/unintuitive template language of any SSG I tried. In the end, it comes down to personal preference: Are you going to build your own templates or use a canned theme? If DIY, make sure you like the template language, otherwise make sure you can find a theme you like. This ruled out Hugo for me because I didn’t like the template language. Do you think you’ll need to write code to perfect your workflow? If so, use one in a language you’re familiar with. Otherwise, just make sure you can tolerate the install/setup process. This ruled out Jekyll/Pelican for me. If you’re using an SSG with a plug-in architecture, what’s the security model and are you comfortable with it? Security concerns around huge dependency trees pushed me away from Metalsmith.
- jerjerjer 5y ago
  Thanks!

dmje 5y ago

Literally zero config: wordpress.com