Human Technology: Text Files
boris-marinov.github.io
boris-marinov.github.io
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...)
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.
I was looking into it for personal blogging I do like the basic formatting and drag-drop image.
Working with content editable is not too bad, turn images to base64 for live preview... but there is also this nice editor already.
Also, car's simplicity is only an illusion. Anything is simple when other people fix and maintain it for you.
[1] https://en.wikipedia.org/wiki/International_Image_Interopera...
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.
The demo page [3] has a bunch of links.
[1] https://iiif.io/ [2] https://ronallo.com/iiif-workshop/presentation/example-manif... [3] https://iiif.io/demos/
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.
At the base of it, my notetaking apps sits on top of a git repository and markdown files.
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.
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.
You mean like some sort of HyperText Markup Language?
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.
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
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 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
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.
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.
> 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.
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.
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.
So, I'm curious about your solution to this.
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.
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.
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)
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...
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.
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.
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.
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.
text-based 3D SCAD which renders while you work.
You can define sub-components as a function, thus allowing multiple placements.
https://marketplace.visualstudio.com/items?itemName=Gruntfug...
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.
Now what I'd be interested in seeing is an argument for traditional publishers or WordPress users to switch to this sort of stack.
Though the biggest problem with this stack is that everything breaks down when you’re doing anything serious with images or layouting.
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?
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)
I am not going to argue against vim but I would argue against being forced or expected to use it.
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.
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.
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.
- 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.
Plain text files.
I knew there was a reason I got on HN at one in the morning. Pointless night redeemed. Also duh I guess, Im just stupid.
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.
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.
?