Markdown Tutorial | Hacker News Reader

Markdown Tutorial

markdowntutorial.com

112 pointsvinnyglennon57 comments

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!

Perhaps one of the easiest ways to learn markdown in short time amongst loads of tutorials online.

When you search for 'markdown cheatsheet' on duck duck go, you get a cheat sheet at the top. Wouldn't that be enough?

https://duckduckgo.com/?t=ffab&q=markdown+cheatsheet&ia=answ...

I don't use duck duck go but this is awesome too!

I highly recommend it, I have been using it for years now.

More comprehensive reference here,

https://github.github.com/gfm/

The only problem I have with markdown is that it's inherently based on those keyboard layouts with easy access to # and `.

In other news, website looks like crap on Firefox mobile.

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?

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.

> Perhaps this would address the problem you're talking about?

He's talking about physical keyboard layout, nothing you suggested will help with that.

https://en.wikipedia.org/wiki/Keyboard_layout

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.

Markdown is fickle and at times unpredictable, and should not be the default formatting method for user input, imo.

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.

"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).

I don't like Markdown for non-technical users.

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.

Always thought that Markdown was primarily made to convert to HTML.

The point is that it's easy to write and easy to parse. It doesn't matter what your emitter 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.

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 expects to be written to 80 columns or less

Not at all.

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.

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.

I would recommend AsciiDoctor: https://asciidoctor.org/

Sweet, had no idea that existed. Will check it out soon!

Sadly, there no any Qt-based editor for AsciiDoctor, such as Ghostwriter or ReText for Markdown.

Another great alternative is Wikitext used by the Wikipedia (among many others) see https://www.wikipedia.org or https://en.wikipedia.org/wiki/Help:Wikitext

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:

#1: That's the only reason.

FYI: # is already "reserved" in markdown for headings. So in theory markdown is also not workable, in practice :-).

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 :-)

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.

Plain HTML is super verbose for basic text formatting. Having to wrap every paragraph is super annoying UX.

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.

Is that a spec or it just happens?

Part of the spec, and recommender by many people.

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

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.

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.

In practice you can always skip the closing p tag. The difference is inconsequential (it only matters for the whitespace).

https://html.spec.whatwg.org/

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.

reStructuredText is another one,

- https://en.wikipedia.org/wiki/ReStructuredText

- https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quic...

Check out commonmark for something less fickle than your average flavor. It adds a specification so users and developers know what to expect.

> unpredictable

A short feedback loop (e.g. live preview) should take care of that.

I recommend reading the past HN post and thread "Don't write documentation in Markdown" https://news.ycombinator.com/item?id=22675165

which flavor of markdown is this ?

Just the original, Daring Fireball Markdown.

Why the sudden popularity of markdown these days? I do not understand.

Markdown is 15 years old, and adoption has been relatively gradual. I believe you're experiencing the frequency illusion. https://en.wikipedia.org/wiki/List_of_cognitive_biases#Frequ...

On the other hand - was its popularity ever "down"?

Markdown has no reasonable support for RTL.

How do you mean? Markdown is just a funny looking way to type things.

is it really md's job? How can it even support RTL? I would have thought that falls under the editor/parser.

Reply on news.ycombinator.com