TLDR: I was introduced to Markdown on this forum. I think it works well here and on GitHub, but I am wondering how convenient it is for general-purpose offline use.
I like to include a README.txt inside any folders that require some explanation. These could be simulations, experimental results, code, etc. I was excited to start creating README.md instead of README.txt going forward because the formatting options make it much more readable, but I ran into some friction:
No default application on Windows when you double-click on a markdown file from File Explorer.
Different rendering behavior based on client application.
a. VSCode only opens the plain text version by default. Then you have to know the “Open Preview” button exists and find it from the context menu.
a. VSCode won’t respect <Space><Space><Enter> as a newline. It requires "<br>" which looks bad in plain text form.
a. Sometimes need to install extensions for certain elements to render correctly like math, tables, and file links.
a. Limited options for ordered lists.
For the reasons above, I am wondering if I am better off writing a README.doc instead. Everyone already has a word processor installed, and they all support Microsoft Word format now. Plus there won’t be any rendering surprises that way. What do you think has the best balance of portability and features? I want to maximize the ease of knowledge transfer for anyone that comes across my files. .txt is easy to open but hard to read.
I would be annoyed about having to read or edit .docx files. You can write in markdown and use pandoc or other tools to convert it to html (to read in the browser) or to PDF via latex.
I am following this guide. <br> and some_characters <Space> <Space> <Enter> both worked, but the trailing spaces didn’t work on a blank line or after a header line.
Sometimes people say markdown is a superset of html. I don’t know if that’s technically true, but (depending on the implementation) html tags can work.
Huh. Is there a particular reason you need new lines that are not paragraph separated?
One of the reasons markdown is great is because it binds you hands in this. If it’s hard to do, don’t do it, just get used to writing with less explicit formatting. Stop worrying and love the bomb and all that.
I didn’t like how close the header was to the paragraph in the default preview (center). Then I opened an enhanced previewer (right) and the spacing was fine. However, then I wanted the horizontal line back … But yes, I think you are right that I need to forget about spacing details.
I am still concerned about making sure math, tables, and links all render correctly though. They could be difficult to read otherwise. Is there a surefire guide for these?
Yeah definitely don’t worry about these things. They won’t be consistent depending on what software is used to render.
I’m not sure I have great advice for this scenario. In particular, math doesn’t render in github’s default markdown compiler, but it does with others… So there there is definitely no guarantee math will work consistently.
I could use LaTeX … but that’s more overhead than I was hoping for to jot down some quick notes. I am not proficient at setting up a LaTeX document from scratch. I’d probably just go for Word at that point if I am going to keep both a source and PDF file around.
I’d go with Markdown. The raw text could look basically the same even if you went with a plain text document, but you get the added formatting in the right viewer.
It might be considered a bit “heavy” (though not as heavy as Microsoft Word ), but I already have Calibre installed on my Windows machine. It does a fairly good job of rendering Markdown. Mathematical rendering is not available, so that could be a showstopper for you.
There are plenty of good text editors and markdown viewers available. I just use VSCode since I am already using it for Julia. However, I am worried that the layman who doesn’t know what .md is could get stuck when Windows asks them to “Look for an app in the Microsoft Store”, not realizing they can open it with Notepad.
I wouldn’t switch to .doc(x) or any other format because of this reason, the Windows universe will need to get a reasonable default app for Markdown files. No compromise, bad is bad, and .docx is pretty bad.
I think that MS Word is the epitome of rendering surprises, even for plain text, but especially with math. I had the same document render very differently on different machines, with page and line breaks in different places.
For offline use with math, I would just write in LaTeX and also include the resulting PDF in the repository/archive. PDF readers are ubiquitous, PDF is future-proof and renders consistently, you have full control and can also include links.
), but I already have