HN seems often incapable of thinking about how audiences and use cases differ.
I'm personally a huge fan of using MD for my stuff. I'm a recent convert, but am finding it works brilliantly for my use case which is idea capture, presentations, etc. Obsidian is my tool of choice. I've written a parser in php which converts this markdown into html ready for web publishing. All good.
But.
I also work with 50+ clients who want to manage their own websites. And they want to manage their websites easily, effectively and visually. They want things to look beautiful. They have audiences that they need to engage with content that is not just words but images, video, timelines, maps, iiif manifests, audio, sliders and much more.
This is a different audience. To ask my clients to "just boot up a jekyll instance and commit your content to GitHub" is the most wildly hilarious thing to expect of an editorially focused non-technical set of individuals.
Yes, plain text works beautifully for simple blogs, documentation, notes and more. But there is huge value in thinking about audience, about design, about engagement which goes beyond just a simple "text is right, wordpress is wrong" argument.
Then what seems to happen in geek circles is that all that "wonderful simplicity" is drowned by an absolutely insane set of tools to actually publish. Yes, you've got plain text files but if your stack then has some cli/npm/jamstack/js/gulp/brew horror attached to it, with a truly questionable maintainability problem attached to each and every one of those tools, how simple now?
Really the point is: different strokes for different folks. You can't make a stunning coffee table book in plain text. Much as you might hate it, InDesign is your tool of choice. And that's ok.
(Also, he's just plain wrong about not being able to get his content out of wordpress. There's a solid and very well supported XML export format for all wordpress instances, even wordpress.com...)
Came here to post a similar comment. From the perspective of the user, a Blogger or Wordpress site is far simpler than writing Markdown (in vim, no less!), generating the site, checking it into git, and uploading/pushing to the web server.
Arguing that vim + markdown + static site generator is simpler, and therefore superior to a content management system or blog engine is like arguing that a dirt bike is simpler, and therefore superior to a car. Yes, mechanically, a motorcycle is far simpler than car. But simplicity of implementation leads to complexity of operation, and it's no surprise that most people prefer cars or SUVs for their daily commute, even though the innards of a car are tremendously more complicated than the innards of a dirt bike.
Equating content management systems with SUV-s doesn't do justice to CMS-s or your argument in general, considering the multitude of environment and other issues with SUV-s.
Also, car's simplicity is only an illusion. Anything is simple when other people fix and maintain it for you.
Micro note: today I learned that "IIIF" is the International Image Interoperability Framework [1], a standardized way of, uh, delivering images over the web. You pronounce it "triple-aye-eff" (which seems like a failure of tradition, since I2C is "aye-squared-see" then IIIF should be "aye-cubed-eff", right).
There was me making assumptions about my audience after posting about knowing your audience...
IIIF is a cool approach that is growing in popularity in cultural heritage, the field I work in. The IIIF main site [1] is a bit baffling, but the long and short is it allows for reusable media that does nice stuff like zooms, pagination, commenting, etc. An "IIIF manifest" (examples: [2]) is just some json, which means you can grab IIIF media and re-use it in a viewer wherever you want to.
oh hey that's pretty cool. I was just wondering what the best way would be to store a bunch of image annotations in a really accessible way. Will dig deeper.
And since Computer Geeks are the ones making all the tools, of course there's 100 times more of these "superior" geeky tools than there are tools for the common man.
The fact that I have to struggle to find just a simple WYSIWYG GUI to edit a website for static site generation is nuts. It's not like these are particularly advanced tools that are technically incompatible with static site generation. It's just that computer people would rather hand-craft a website with Markdown and CSS code than compose visually appealing content using a mouse without code.
It seems nobody is creating technology that is both simple and easy to use, it's always one or the other.
I think for the handcrafted markdown people, writing it is easier than GUIing it up. Keyboard-driven workflows that don't depend on bloated graphical environments and browsers are popular among power users for valid reasons.
Have you ever seen what happens when those "normal people" start using Word for anything non-trivial? They _think_ they are making the document look better, but end up with a hard to read, inconsistent mess.
I much prefer a self-hosted WP instance over the wordpress.com offering. WP.com injects tracking cookies and ADs in their free tier, and even with a paid version with your own custom domain, there is still some tracking going on. If you care about the privacy of your visitors, self host WP & don't opt for WP.com
> To ask my clients to "just boot up a jekyll instance and commit your content to GitHub" is the most wildly hilarious thing to expect of an editorially focused non-technical set of individuals.
Perhaps a missing piece of software is a WYSIWYG interface front-end that hides MD, GitHub, Jekyll and other back-end technologies from the user, but still uses plain text in the back end.
There is nothing more durable than plain text, it might be the only thing that you can still read in 50 years.
> Perhaps a missing piece of software is a WYSIWYG interface front-end that hides MD, GitHub, Jekyll and other back-end technologies from the user, but still uses plain text in the back end.
No, this won't work for a simple reason: MarkDown isn't expressive enough for regular users.
They want to play with grids and set backgrounds: SquareSpace, Wix, and some Wordpress themes allow that with ease. They want to place a picture precisely there, which MarkDown also don't allow. And finally, users wants to have pixel-level control of their content. While it's a foolish endeavour to a seasoned WebDev, what everyone else offers blows out MarkDown and Jekyll.
You basically need to either extend MarkDown, or invent a new intermediate language for these.
>a WYSIWYG interface front-end that hides MD, GitHub, Jekyll and other back-end technologies from the user
This exists and is called a "headless CMS". There are plenty out there, I can't speak for all of them, but I once migrated a company blog from wordpress to NetlifyCMS and it was... just ok. The visual editor was good enough (at least compared to WP), but there were a lot of more advanced things that the only way to to them was by writing some React components and referencing them in the markdown. But it allowed a writer -> editor -> publication flow, the github abstraction was well hidden enough, and in case anything went wrong it was pretty easy for a dev to get in there and fix it -- all the content lived in a repo after all.
But again, you admitted that you're at least a team. SquareSpace and Wix (for example) is appealing precisely because most of their users are solely the one maintaining the site, at least when it comes to the editorial and design side. They precisely don't want to know the warts of manually-maintained CMS (and I knew Joomla, it's not pretty) or how to maintain HTTPS, they just want it to act as if it's Word or Photoshop.
This thread is about replacing WordPress with a static site generator, so far we've added a dynamic application with a GUI for site editing, WYSIWYG HTML for site content and layout adjustment. My guess is the next addition will be a form or comment input that requires making the front-end dynamic as well with solid caching as a stopgap. At some point further down the line someone will realize why each "complicated" piece is in WordPress.
Yes, your comment is spot-on. Most programmers will view WordPress with scorn because they see it as a bloated mess, comparable to seeing Word as a bloated mess compared to TeX, Markdown et al. But most of them don't believe - or worse actively deny - that Word's "bloatedness" is simply a consequence that some might use it as a simple document writer, some as a templated document (for use in receipt printing for example), and some will use it for things that I haven't even heard of. Actually, dmje, the grand-grandparent of the comment, has said it succinctly: HN seems often incapable of thinking about how audiences and use cases differ.
One of the problems with text files and the philosophy of chaining little tools together to do something is that what usually happens is a rube gold-berg machine of little dependencies you have to manage to keep things working.
I could spend time working out how Jekyll works, writing a script to deploy the changes and managing changes with git. Alternatively I could just spin up a wordpress instance on a VPS in minutes and start publishing content.
Sometimes the "unix" way isn't the simplest way. Sometimes having a product that already built for that task that is paid for is simpler and a better use of your time.
I like git, markdown files and pandoc for docs and might even use hugo for really simple sites and use some bash / powershell / batch scripts. However if you work with anyone than yourself you will have to document how it works otherwise they will most likely be clueless as to what you have done.
Even in dev circles. Most "dark matter" developers are reluctant of using a command line and only learn what they need to learn to get by. Many just do everything in the IDE and are completely lost outside it.
I do agree with the author, that you should use the simplest tools you can get away with, but (text-files + jekyll + this + that) isnt just text files, as you say its a precarious stack no less complex than some software package or whatever.
I guess if you do just want the truly simplest tool for a website, html is probably better than text files, even if it is a bit less ergonomic to write with
> I do agree with the author, that you should use the simplest tools you can get away with, but (text-files + jekyll + this + that) isnt just text files, as you say its a precarious stack no less complex than some software package or whatever.
They are advocating for sellotaping tools together to build a workflow near the end of the article.
> I guess if you do just want the truly simplest tool for a website, html is probably better than text files, even if it is a bit less ergonomic to write with
Writing HTML when you are trying to write content is pretty painful. Way back in the distant past I used to charge about £100 a HTML page. I ended up learning Perl (and later PHP) so I wouldn't have to write HTML.
Plain text is a mirage, in practice it is not super well defined. I find it funny that we have here lauding the simplicity of plain text while there is right before this a thread about CR/LF.
Practically you are always going to reach beyond just simple printable characters, and the moment you do so you fall into a pit of complexity one way or another.
Regarding Markdown, using * for instead of <em></em> is not significantly simpler conceptually. Indeed I'd argue parsing (or rendering) markdown is not simpler than doing so for equivalent html. That is to say that markdown does not provide any level of abstraction over html, instead it is merely a syntatic transformation.
For the purposes of this article, the author seems to treat writing Markdown and HTML files as equivalent--both are plaintext.
> And similar is the case with simple static HTML websites - a simple static page is better than all publishing platforms that can ever be created.
The content in both of those formats can be read by anything that can read text, in contrast to something like Wordpess which requires a database and large application stack to view its content.
As a copywriter and technical writer who has to deliver content in docx files with custom styles for each client, Pandoc is a life saver. I can write in Markdown and run a script that outputs a (more or less) correctly formatted docx file and drop it in an email or upload to Google Drive.
But the fact that I have to do that reveals the limitations of the plain text everywhere approach. My clients don't want markdown and they wouldn't know what to do with it. They want Word and its revision and editing capabilities, and they'd almost certainly fire me if I insisted they used Git instead.
I've wondered about this many times -- your conversion is a one-way street, right?
Let's say you have your source material in MD stored in Git, convert it to docx and send it to your client. They use Word to make annotations and revisions and send it back to you. Now what? How do you get this back into MD and your Git repo? Of course you can do this by hand, but that's terrible work. It certainly is worse than staying in the Word ecosystem and flying with it. Not that I'm advocating this, but I don't see how "backporting" their proposed changes into some local Git branch in MD scales.
Oh, the Word "mark changes, annotate and pass away" model of change control doesn't work when everybody is using Word either.
It's basically deeply flawed, and once somebody decides to go through that road, your best bet is to read the annotations and redo them manually on the original document. That works about as well if your original is in Word or any other format.
Yes, it's a one-way street. Edits and revisions have to be done in Word, unfortunately. What makes it worse is that most people don't know how to use Word properly either, so you end up with documents with multiple fonts, text in a dozen different colors, half the suggeted edits as comments/annotations and half as text written into the document, random highlights with no context, and so on. Complete pain in the arse. But at least the part I control is plain text, version-controlled, and easily scripted.
It's too often overlooked that HTML is an acceptable* office file format.
Suppose that rather than a docx, you handed them what we might call a "doch": a self-contained (no external resources) .html file that includes more or less what you'd get by doing "Save as HTML" in a traditional office suite. This would work well enough on their end, no? They should still be able to double click to open it. The difference being that since the W3C/WHATWG specs involve a whole programming system supported by the browser, then you could also script a lightweight sidebar that they could use to add their annotations. The positive would be that, since you control the implementation and therefore the experience, you could (a) take the necessary steps to ensure that the alterations they're making follow a consistent format, and (b) can be more easily ingested by your tooling in a way that's compatible with your preferred workflow.
* close enough to cover the 80% of features where it matters (e.g. for media not meant for print)
I’m in the same boat, often, and there is no solution.
I do the original writing with Pandoc/Markdown, but I’ve resigned myself to working in the client’s format for subsequent revisions. If a revision requires a lot of new content, I write that again in Pandoc/Markdown and paste in the converted result.
The first thing that I see again and again here is using the term "Marketing" wrongly: Marketing is not sales, marketing is not Advertising.
Although usually the "Marketing guys" also handle sales and Advertising, marketing is the study of markets, discovering the desires and needs of the people, it is not about how to force people to buy what they don't want or need.
Good Marketing people do not sell you something that you don't need or want, but they know much better than you do what you need or want because they have studied that and they are good at it. Most times they don't even sell, they create and design a product or service because they know it is necessary before it exists.
A great product or service for the right market like Pong the original game, the first desktop laser printer or the Iphone sells itself with little effort.
People like software developers overvalue what they create for the company and undervalue the work of other disciplines. In fact every department tends to do that with other departments.
I am an expert on Tex and LaTex, emacs and Vim, Lisp, and C derivative language programming and Unix systems although I am now entrepreneur.
To say that using those technologies is simpler is forgetting all the time that you invested learning those technologies. In my case, decades.
You know when you need to teach someone a technology like Markdown, you enter the rabbit hole of having to teach them to use Vim, or even installing a webserver so they can see in a beautiful way instead of ugly text, or even installing a Linux on a raspbery pi, and apt-get, and sudo and ls...
I don't really ever consider simplicity when choosing tech. I consider standardization.
If a text file is the standard, I'll use that unless there's a reason to do otherwise. If a million line framework is the standard, I'll start my search there.
Text files don't scale that well. Just try changing one value in a megabytes file. There's no tools for that really. You'll probably spam the disk with a megabyte of data every time.
SQLite is about as easy as text, and scales way better. And it already exists. All the complexity is not your problem. They don't even accept contributions.
I'm generally biased towards do it all systems if there's no major performance or development time penalty.
Complicated tech can be one size fits all and refined over the years. Simple tech encourages ad hoc solutions, pushing the complicated part into YOUR project instead of in an open standard with thousands of devs.
Similar to how Flask apps often end up becoming just as complicated as Django once the app grows beyond a certain size. Except that now you don't have the benefit of standardization that Django provides, because you reimplemented everything in a custom way.
I'm not so sure about that. Complex solutions are mostly prebuilt, and used by thousands. When any one person solves an issue, that's usually the end of it, so it gets more reliable over time. Even Windows seems to have gotten better.
Simple solutions still have a nontrivial amount of code(Otherwise the whole project would just be "use this turnkey app"), but the code is original. It's probably still going to need debugging.
Complex solutions are mostly prebuilt, are used by thousands, and still are horribly buggy. Your typical app or website - say, GMail - is much more buggy, from the user point of view, than its counterpart, say, twenty years ago.
We've just learned to be blind to most of those bugs.
I recently needed to start pumping out complex diagrams for work, so I spent a few hours learning mermaid, realized it couldn't output to SVG, and then spent another hour learning graphviz. Now I can barf out ugly but functional, version controlled diagrams of arbitrary complexity.
While I normally use openSCAD when modelling objects for 3D printing, I recently fired up the web version of SketchUp and knocked out some curtain rod bracket stiffeners in about 15 minutes.
Visual point-and-click tools are great for learning, and continue to be useful for simple, ephemeral things that don't need to be better than arbitrary. As soon as you reach a high level of complexity, or need to iterate on and optimize something, having the text based description language seems to become orders of magnitude more productive.
I suspect 3D CAD is one area where GUI will always win. As far as I know big companies and militaries and cities and all the rest use GUI.
A small subset of people with an impeccable ability to work with 3d stuff in their mind might be more productive in code... till they have to collaborate with others who can't compute a chain of 3 rotations mentally.
I love SketchUp unfortunately it seems to not be maintained. At least the free one lags on a gaming computer. So at some point I have to drop time to learn something like F360. Just sucks when you know something really well and can just model things/no learning curve.
SketchUp itself is under active development, however they've stopped offering a free version of the desktop application and only offer a stripped down web version.
I see. The only other thing is I primarily use it for 3D printing stuff and since it's a surface vs. parametric sometimes something that looks solid is not. I have started using a checker for edges/faces but it's funny when I don't pay attention to a slicer and there's a chunk missing on the print. Anyway yeah mostly the pain now is 2017 version if you rotate a view it lags. But yeah sounds like need to pay for it.
>Todo: export diagrams from inside Markdown source
The problem I encountered is that the vscode preview extension only seemed to work with mermaid embedded inside markdown, but not straight mermaid files. Also, one of my diagrams was complex enough that mermaid was starting to produce useless results, such as overlapping several edges spanning the entire diagram.
In the spirit of the original article, I hopped over to graphviz as the more boring, mature option. The language is less elegant, but is also simpler with less syntactic sugar.
If there was a decent WYSIWYG editor (like Typora) bundled with Pandoc with a myriad of customizable export options, included with a bunch of high-quality themes and templates, while also having a one-click service to upload to a server for static serving, then I don’t see why not. Maybe the technology stack is not the problem, it’s the presentation of it that makes non-tech people gawk at the complexity.
Though the biggest problem with this stack is that everything breaks down when you’re doing anything serious with images or layouting.
That's what I experienced building a static site generator for my dad. You would just dump markdown into a dropbox folder. A cron job would poll from dropbox and generate the website. But even markdown is too daunting for a non-techie. Non-technical users are probably not used to write "code"/"mark-up" and have a good grasp at what's coming out on the other side. The visual aspect, a sort of preview, is missing. There are a lot of options to preview markdown. That's just another hurdle, another tool they might have to learn. It's all just so loosely integrated, even I have a hard time putting it together. Might be fun for us to fiddle around, but it isn't if you just want to put your content out there.
I've started to work on an alternative: Desktop app, with a block based editor (text, images, headings nothing more). Shows a local preview of your site. Outputs static assets and/or uploads directly to Vercel for hosting. Few knobs to fiddle around.
At the end of the day Markdown is just an intermediary shorthand for the eventual output, originally HTML; and HTML is actually standardized. If you’re not going to use the Markdown syntax, then wouldn’t an HTML editor that hides all the HTML do the job?
Actually, you’re right. The only thing people actually need is a good WYSIWYG editor; the format is probably uninteresting to the end user. Though there is a case to be made for using an open, well-documented format (whether it be Markdown or HTML or something else), since without this openness third-party developers would have trouble in developing and customizing their own exporters.
Well, if you’re suggesting HTML (or XML) for that job, then maybe it’s time to resurrect XLST instead of using Pandoc… (https://en.m.wikipedia.org/wiki/XSLT)
There would still be a lot of moving parts on the table. What to do with all these HTML files? How do I link them together? How do I get those files to a hosting provider? Where do I handle global styling? For the content creating itself a WYSIWYG editor would be fine, but there's more to the process.
I'm also guilty of the builder mentality. It's just a fun project to work on and it benefits at least on other person :)
I think the larger part of the problem is exactly what the author seems to miss: even using Jeykll is scary for non-technical users, let alone git. (Try getting your grandfather to restore his accidently deleted posts)
> Preaching to the choir! I'd be surprised to find anyone on HN with an argument against writing your blog/book in markdown with vim.
Time. Wordpress for the most part is WYSIWYG. With any of these static site generators I have to learn the conventions, work out how to install and edit themes and generally there is a lot of faffing.
> Now what I'd be interested in seeing is an argument for traditional publishers or WordPress users to switch to this sort of stack.
There isn't one. It doesn't scale. There is a reason why companies typically use some sort of CMS system. It isn't just ease of editing. You can control when, where and who can publish content to the site. You can localise content. You can version control content. You can have stakeholders review content before it is made public.
Doing that with vim, git and a static site generator and some bash scripts is a faff and will frustrate non-techie people that just wanna copy and paste content from Word.
I don't think there is much of an argument. CMSes work and they do a ton of other stuff besides edit text that people want.
And they can be cloud managed with no manual setup. Their black box point and click model is great for division of labor.
Although, GitHub is a pretty great publishing platform for open source texts, but that's a whole platform that just happens to have text files at the core.
Running your own site... is kinda unpleasant. DokuWiki is a pretty good compromise with most of the benefits of straight text.
There's nothing wrong with just using plain text - without these fancy fangled markdowners. Not for every one, but a plain text website IS fully WYSIWYG and the load times - look out!
Yep. The only reason I use Markdown is for math equations (and yes I am aware of unicode math but it'snot enough). It's nice to see them rendered. Alas, not all Markdown editors have good equation support. And most of them behave horribly with RTL texts...
I tried to write my documentation, CV, presentations, etc in markdown for a few years. It's ok I guess but I was forever dissatisfied with the result presentation.
Finally made the jump to latex and I feel cheated for believing it is too complex and not touching it for all those years. For example https://latex-beamer.com/ for presentations is extremely simple, you can be productive with it in 2-3 hours. Give latex a try, forget markup languages.
I had a similar problem with my markdown CV. The layout was never quite right and it was a lot of iterating to get even that far. I ended up just using pages, which I hardly know, but could get to do what I wanted.
I don't like these "simple" formats because of non-obvious escaping and overloading too many "common" characters, which is even context sensitive (in HTML, it's just three characters anywhere, & → &, < → <, > → >, and maybe " → " if you use attributes). Even in the provided article, there are many such constructs:
- we learn that we need to escape === and --- and ```, but I assume only when it's on a line alone, which seems OK as you probably won't write a paragraph that contains only ```
- then we learn we also need to escape * (e.g. to write 2*2=4), anywhere in the text, but I guess not inside ``` block, so we now need context instead of "find and replace". The escaping mechanism is not mentioned, but hopefully the world has settled on \*, except for dokuwiki which uses %% or whatever
- and you need to escape [ and ] (everywhere or only inside link?)
- How do you do a link or emphasis inside ```? In some MD flavors, it's outright impossible. (e.g. I need to emphasize something in a pasted code, or I'd like to make a function call clickable as "go to definition/documentation"). In HTML you can use most tags, such as <strong> and <a>, inside <pre>
However, when I suggest blogs for other people, the default is WordPress. I'm still navigating and learning the ideal, simplified, pattern with text files without the need to rely on any further complex tools.
Like the author, I also enjoy making things out of plain text. I'm perhaps less evangelical, but after all they are a Vim user, so... ;)
My own flow occurs entirely in Emacs, where I write in Org Mode, then build and deploy to GH Pages using Nikola. No more command-line steps for me! And no inferior new-fangled plain-text format: good ole Org Mode stands the test of time.
> you should always use the weakest technology capable of solving your problem
Wrong, you should always use the technology capable of solving your problem that's also the least amount of work. Very often that's a technology that solves a more general problem, of which yours is but one. And very often it has UX that normal people actually understand.
While I share some of his enthusiasm (albeit not particularly for markdown tools), I'd observe that considering the rich content produced by the editor, Wordpress.com content is pretty exportable as WXR, and once into a self-hosted WP install is _very_ exportable; there are all sorts of tools to get at WP content in different ways.
I'm personally a huge fan of using MD for my stuff. I'm a recent convert, but am finding it works brilliantly for my use case which is idea capture, presentations, etc. Obsidian is my tool of choice. I've written a parser in php which converts this markdown into html ready for web publishing. All good.
But.
I also work with 50+ clients who want to manage their own websites. And they want to manage their websites easily, effectively and visually. They want things to look beautiful. They have audiences that they need to engage with content that is not just words but images, video, timelines, maps, iiif manifests, audio, sliders and much more.
This is a different audience. To ask my clients to "just boot up a jekyll instance and commit your content to GitHub" is the most wildly hilarious thing to expect of an editorially focused non-technical set of individuals.
Yes, plain text works beautifully for simple blogs, documentation, notes and more. But there is huge value in thinking about audience, about design, about engagement which goes beyond just a simple "text is right, wordpress is wrong" argument.
Then what seems to happen in geek circles is that all that "wonderful simplicity" is drowned by an absolutely insane set of tools to actually publish. Yes, you've got plain text files but if your stack then has some cli/npm/jamstack/js/gulp/brew horror attached to it, with a truly questionable maintainability problem attached to each and every one of those tools, how simple now?
Really the point is: different strokes for different folks. You can't make a stunning coffee table book in plain text. Much as you might hate it, InDesign is your tool of choice. And that's ok.
(Also, he's just plain wrong about not being able to get his content out of wordpress. There's a solid and very well supported XML export format for all wordpress instances, even wordpress.com...)