Agreed, but what else is there for simple formatting like headings, bold, underline, img? I had to go with markdown because I could not find anything else out there.
PS: Why not have the best of both worlds, that is, Markdown and Wikitext? Yes, you can; see Texti (Text with Formatting Instructions) - https://texti.github.io
Texti is yours? It looks like an interesting experiment. Lots of good ideas in it, though it gets way too unfocused/wip in the second half of the document, especially in some areas like the "blocks". (Also your emojis are broken)
Having hash line comments is probably a non-starter in a text format (the latex % syntax is probably a better idea indeed if you want line comments). Also the -- strikethrough -- syntax will probably conflict too much. You want comments to use a syntax which is otherwise nearly unused.
Thanks for your kind words (yes, sorry for the missing disclaimer). Texti is slowly evolving :-) The point is NOT to invent new syntax [1], thus, using the established unix-style/shell-style/python-style/ruby-style for comments. For a litte real world examples that generated HTML, LaTeX and Markdown from Texti see https://github.com/texti/texti.github.io/tree/master/samples
PS: The main missing feature (among others) in Markdown and that rocks Wikitext (and Texti too) is built-in (recursive) templates (with optional parameters) using the {{}} syntax.
[1]: I know % is not new because it's used in LaTeX but LaTeX is esoteric compared to Python, Ruby, Shell Scripts, Unix Configs, etc.
Yeah I figured, and I personally really like # for comments in code, but here's a list of reasons why I don't think hash as comment in text is workable, in practice:
Well, that's true, you have a point there ;) It's probably my bias talking. Good luck with the project; I love Markdown, but it's great that other people are exploring alternatives.
Why not plain html? For simple formatting like you mention, it really is simple, and it has all the power you could want if you want if you to go further.
HTML5 is not all that verbose. You can omit closing tags for many elements (for example, </p>, </li> and </td>). Many other tags are also implicitly opened, like <body> and the like. I actually prefer it to markdown for most cases.
For some examples of modern html, see google's style guide for html, section 3.1.7 shows an example of a complete and correct document that may blow your mind. Also, the examples of tables and lists without closing elements:
It sounds good in theory, but in practice it adds a huge mental overhead.
> A p element's end tag may be omitted if the p element is immediately followed by an address, article, aside, blockquote, details, div, dl, fieldset, figcaption, figure, footer, form, h1, h2, h3, h4, h5, h6, header, hgroup, hr, main, menu, nav, ol, p, pre, section, table, or ul element, or if there is no more content in the parent element and the parent element is an HTML element that is not an a, audio, del, ins, map, noscript, or video element, or an autonomous custom element.
If I want to convert my work to PDF or MS Word format, that's easy to do if I've used markdown, due to the existence of converters. If the document is written in html, the conversion is more difficult. Any html extensions that need to be converted by hand stand out in a markdown document.
Markdown is at a sweet spot that combines ease of read and write for technical and non-technical users. It's primarily made to be written and shared as-is.
Sweet spot as long as you don’t want anything basic like using colors. In my experience Markdown has been about as much painful and frustrating than helpful.
Color isn't really that basic a thing - you need to take into account the medium that the color will be displayed in to do it correctly.
However, as Markdown is supposed to be nothing more than a superset of HTML, you can simply reach for CSS. It won't always render the best if you're moving from Markdown to physical medium, but that's largely dependent on the engine.
I very rarely, if ever, encounter markdown inputs where markdown is a superset of HTML. Almost always script tags and various other sorts of active content are stripped at the very least.
If certain tags are being stripped, then you're probably in a position where arbitrary input isn't desirable.
If this is an input to a website, for example, the webmaster really doesn't desire everyone to be able to reinvent the blink tag, or be able to express everything in rainbow fonts.
In which case Markdown shines, for it's ability to express simple markup, that can be safely expressed.
You can use colors - like in html and css you keep style and structure separate. If you want all your heading 2 blue, for example, than you can use h2 { color: blue; } and so on and so forth.
PS: By the way, you are currently commenting in text without colors - how do you feel?
Commenting of HN is very different than writing educational context. Colors made it really easier to show correspondences in-between languages, especially when they are in different order. I also had the problem the other day when writing software documentation (imagine code portion without colors... hopefully in this case third party lib are doing the job).
You (and other posters) can ironize as much as they want, the truth is dealing with colored text in Markdown is equals to inputting raw HTML, as which point mixing the two markup languages is more painful than going raw HTML.
Well, (raw) Markdown is about content, not form. I don't have any example on the top of my head when color is part of content, but if that's a common use case of yours, text processors are probably a better tool than Markdown.
Markdown expects to be written to 80 columns or less. It doesn't have to be but that it what's expected. Which makes it very much about form as you have to manually "form"at it.
"Markdown is at a sweet spot that combines ease of read and write for technical and non-technical users."
Not in my purely anecdotal experience. While many (but not all) developers like markdown, I've yet to come across non-technical users who like it (tolerate it perhaps, but not like).
On Reddit, I frequently see mistakes caused by Markdown behaving unexpectedly. Common problems include:
- "How old are you?" "52." gets renumbered into "How old are you?" "1.".
- People using single linebreaks for poetry and song lyrics, and being confused when they get collapsed into a single line.
GitHub Flavored Markdown _does_ fix both these problems, but for some reason, regular Markdown is a lot more common, even when targeting non-technical users.
I am not technical. I started using markdown to write my university papers, and it really helped with quickly formatting my text (as well as not worrying about Microsoft Word crashing). I really think more people should be aware of it as it would speed up so many workflows. Thanks for this tutorial!
I have almost entirely switched to using an editor which supports real-time preview for Markdown editing. There is a plugin for my editor (VSCode - but I'm sure that something similar exists for most other editors that support plugins) which has keyboard shortcuts for marking content as a given type (e.g. Alt+c will mark selected text as inline code). Perhaps this would address the problem you're talking about?
I understand that. If you don't have a # readily available, but your editor allows you mark a line as Heading 1 by pressing Ctrl+1, then it does in fact address their problem.
Surely there are workarounds, one could also just switch to an US layout (an instantaneously become a faster, less tired developer, since the same problem happens with commonly used symbols such as / [ ] etc. which are easy to type on anglophone keyboards).
It's probably a unsolvable problem unless:
- everyone adapts to using common, more difficult to type, characters such as " or ? (but then how does the system differentiate between common figures of speech and formatting?)
- everyone switches to US/ENG layouts, but we already had enough US-centric systems in the past and I don't know how many wouldn't see this change as a personal/national attack
- the creation of a Fn keys standard, but that means all hardware producers would have to comply to eat (yeah) and mobile typing would become problematic, along with extra strain from having to press the "fn" modifier
- your solution, which i find elegant, but adopted OS-wise instead of just inside an editor plugin. but then what if ctrl-1 is my shortcut for switching desktops, or closing windows?
Maybe the only cure is to accept defeat, create localized versions and create translators - after all this seems how languages work.
58 comments
[ 5.2 ms ] story [ 122 ms ] threadhttps://github.github.com/gfm/
https://duckduckgo.com/?t=ffab&q=markdown+cheatsheet&ia=answ...
PS: Why not have the best of both worlds, that is, Markdown and Wikitext? Yes, you can; see Texti (Text with Formatting Instructions) - https://texti.github.io
Having hash line comments is probably a non-starter in a text format (the latex % syntax is probably a better idea indeed if you want line comments). Also the -- strikethrough -- syntax will probably conflict too much. You want comments to use a syntax which is otherwise nearly unused.
PS: The main missing feature (among others) in Markdown and that rocks Wikitext (and Texti too) is built-in (recursive) templates (with optional parameters) using the {{}} syntax.
[1]: I know % is not new because it's used in LaTeX but LaTeX is esoteric compared to Python, Ruby, Shell Scripts, Unix Configs, etc.
#1: That's the only reason.
It's kind of like:
1. FC Köln - that's a football club name (and not a list marker). Try it in markdown - same gotcha :-)
For some examples of modern html, see google's style guide for html, section 3.1.7 shows an example of a complete and correct document that may blow your mind. Also, the examples of tables and lists without closing elements:
https://google.github.io/styleguide/htmlcssguide.html
> A p element's end tag may be omitted if the p element is immediately followed by an address, article, aside, blockquote, details, div, dl, fieldset, figcaption, figure, footer, form, h1, h2, h3, h4, h5, h6, header, hgroup, hr, main, menu, nav, ol, p, pre, section, table, or ul element, or if there is no more content in the parent element and the parent element is an HTML element that is not an a, audio, del, ins, map, noscript, or video element, or an autonomous custom element.
https://html.spec.whatwg.org/multipage/syntax.html#syntax-ta...
This is so complicated. In the end it's easier for me to close the tag instead of second guessing if I may skip it or may not.
- https://en.wikipedia.org/wiki/ReStructuredText
- https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quic...
However, as Markdown is supposed to be nothing more than a superset of HTML, you can simply reach for CSS. It won't always render the best if you're moving from Markdown to physical medium, but that's largely dependent on the engine.
If this is an input to a website, for example, the webmaster really doesn't desire everyone to be able to reinvent the blink tag, or be able to express everything in rainbow fonts.
In which case Markdown shines, for it's ability to express simple markup, that can be safely expressed.
PS: By the way, you are currently commenting in text without colors - how do you feel?
You (and other posters) can ironize as much as they want, the truth is dealing with colored text in Markdown is equals to inputting raw HTML, as which point mixing the two markup languages is more painful than going raw HTML.
Not at all.
Not in my purely anecdotal experience. While many (but not all) developers like markdown, I've yet to come across non-technical users who like it (tolerate it perhaps, but not like).
On Reddit, I frequently see mistakes caused by Markdown behaving unexpectedly. Common problems include:
- "How old are you?" "52." gets renumbered into "How old are you?" "1.".
- People using single linebreaks for poetry and song lyrics, and being confused when they get collapsed into a single line.
GitHub Flavored Markdown _does_ fix both these problems, but for some reason, regular Markdown is a lot more common, even when targeting non-technical users.
A short feedback loop (e.g. live preview) should take care of that.
In other news, website looks like crap on Firefox mobile.
He's talking about physical keyboard layout, nothing you suggested will help with that.
https://en.wikipedia.org/wiki/Keyboard_layout
It's probably a unsolvable problem unless: - everyone adapts to using common, more difficult to type, characters such as " or ? (but then how does the system differentiate between common figures of speech and formatting?) - everyone switches to US/ENG layouts, but we already had enough US-centric systems in the past and I don't know how many wouldn't see this change as a personal/national attack - the creation of a Fn keys standard, but that means all hardware producers would have to comply to eat (yeah) and mobile typing would become problematic, along with extra strain from having to press the "fn" modifier - your solution, which i find elegant, but adopted OS-wise instead of just inside an editor plugin. but then what if ctrl-1 is my shortcut for switching desktops, or closing windows?
Maybe the only cure is to accept defeat, create localized versions and create translators - after all this seems how languages work.