Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

When you use one of the extensions, like Hugo's figure, which has alt-text support you're about as close to that goal as possible. An image can't be stored in human readable plain text.

The alternative is WYSIWYG formats that aren't plain text.



Doesn't matter how close to the goal you get if it is on the outside...

I'm gonna be annoyed if I clone your repo, open the readme.md and now have to figure out how to read it.

Plain text is awesome, for plain text. If it isn't plain text might as well use a pdf.


There's no reason for this to be all or nothing. This seems perfectly readable to me:

    ![The Google Logo](google-logo.png)
Even if you've never seen markdown before, it's pretty obvious.


How often do you refer to the logo? Try something like this:

   ![Hierarchy of the system](system-hierarchy.png)
You know what it is, but you have no idea what it looks like. Maybe it is a garbage picture that doesn't really add anything. Or maybe the picture is a necessity to understand the architecture of the system. Someone put the time and effort to create that picture, you'd imagine for a reason. Maybe worth having a look?

Maybe, just maybe, looking at that image is a good idea to do before reading 20 pages of documentation? Probably a good idea to look at even if you only intended to glance at the documentation for 20s.

Because that's what markdown mostly is in my experience, documentation. And the images, if they exist, often are a very important part of that.

Now some images are garbage, but you don't know because the alt-text will not be "Superfluous image that doesn't add to the understanding". Maybe it depends on the reader, is the reader fluent in design patterns (and crucially, is the project following the design pattern as is or have they made their custom modifications to it?).

But in reality it will likely be a flowchart. Kind if an important piece that really help when reading the text. Or maybe just an image of a header and all the field sizes. Can you do it without it? Sure. But remember that not all documentation is perfect, it might not have had someone pouring his/her heart in it. It might have been rushed. So as often is the case you actually do need both the image and the text, not just to help understanding (which alone really is reason to make sure you look at both) - but because you need both to get all the information.

I sigh when I see a .md. Especially in documentation, because in reality that probably means that I have to either get the dependencies and look up the build process to build it myself. Or I have to go to the official project web page and browse the documentation there.

If it is a .txt or .pdf I know what I'm in for, and I know I have the tools needed to view it.


You're still using all or nothing thinking. If I wanted to see the diagram then I'd open `system-hierarchy.png` by navigating to that file and clicking on it. Besides, you rarely need to build a markdown file yourself; open it on Git[Hub|Lab] or open the project's web docs. You could prefer a .txt, but that can't display images at all.


Markdown can't display images at all, either... Which is my point.

(you know you can write paths in a .txt file too?)


But you would have to invent or assume a format for that .txt, and markdown is easily rendered if needed


Invent a format? How about, "The system overview has been illustrated in images/system-overview.png"

We use markdown because it is plaintext and accessible. Oh, but you have to convert it yourself. How? Well every project is different but I'm sure you can find a Makefile somewhere in the project. Good luck!

Again, the point again is that markdown is not readable alone.

If it is, then a .txt is strictly superior. If it is not, then never, ever, present it as the final product. Always ship the generated artifacts. The only point you want to actually see the .md file is if you want to make changes to it. Is making changes the primary usecase for your markdown files? I'm going to assume, no.


I'm having a bit of trouble understanding the problem here as well, and kinda hope people expand on it, because insight might think of what to do better.

I edit a number of wikis. This leads to an inevitable amount of instances of having images floating aside the the text. Sometimes there's some peculiar stuff done with tables. But we never actually intermix the text content in a completely unreadable way, at least outside of templates and modules, which are NOT text content meant to be read in the first place and are NOT markdown either.

Every section of text only has text content, and the only alterations to the text come as syntax that strictly surrounds the affected text. If images have peculiar formatting demands, they will exist outside of text (Such as a CLR).




Consider applying for YC's Fall 2025 batch! Applications are open till Aug 4

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: