It's funny to watch Markdown gradually reinvent HTML as it originally was (though with much more readable syntax)
And I don't actually think that's a bad thing, so long as it stops there. HTML has become much more than documents, so having a constrained subset dedicated to documents is helpful.
"Aside" is very rarely used as a footnote, and doesn't inherently have footnote semantics.
Not even in W3C's rather underrepresented suggested usage (as distinguished from common practice):
The objective of this technique is to use the HTML5 aside element to indicate that it's content is tangentially related to the main article or a parent section. The aside element represents a section of a page that consists of content that could be considered separate from that content. Such sections are often represented as sidebars in printed typography.
The aside element represents a section of a page that consists of content that is tangentially related to the content around the aside element, and which could be considered separate from that content. Such sections are often represented as sidebars in printed typography. The element can be used for typographical effects like pull quotes or sidebars, for advertising, for groups of nav elements, and for other content that is considered separate from the main content of the page.
However, ctrl+f footnote doesn't return anything. What's the current best practice for writing footnotes with semantic html? If I were to implement footnotes with <aside>, how would it look like?
To be fair, it is simpler than HTML. Like Java vs. Python. You can sure do a lot with Java, but sometimes you just want the beauty of Python without injection, ya know?
I don't understand how you can say that. Markdown is massively more complicated than the equivalent HTML. HTML syntax is simple: Every gizmo is expressed as a <tag> and optionally an end </tag>, there are escapes for <, > and &, and that's all that ever needs escaping.
Markdown, on the other hand, has a syntax that is ever expanding. It's all exceptions to exceptions to exceptions (exceptions all the way down).
For example, what happens if in a markdown document talking about regular expressions you have this text: [^A-Za-z]. Will it be interpreted as a footnote? Or is it an exception? Who knows, only trial and error will tell.
You're talking about parsing/syntax, but what matters here is semantics. (Normal) Markdown maps to a small subset of all possible HTML tags, most of them on the simpler end of things, and that makes its overall scope and semantics simpler than those of HTML, even if its syntax is not.
I don't think it's really about parsing/syntax. Or, rather, it is, but that has implications not just for the person writing a markdown parser or renderer, but for the person writing documents in markdown as well.
With HTML, I know that anything inside angle brackets won't get shown, because that's a directive to the rendering engine to do something. Put another way, only <, >, and I guess & are special and need to be escaped if I want to use them. Everything else will show up as I've typed it.
With markdown, a future feature addition could actually change the layout or structure of an existing document, because arbitrary characters (and sequences of characters) mean particular things. Previously, [^1] was a hyperlink to somewhere else (assuming I put "[^1]: https://wherever.com" somewhere else on the page). Now it's a link to that "[^1]: https://whatever.com" text on the same page. This change may have broken existing documents.
Means and ends. If your means are complex, but the ends you are achieving are simple, then you're not getting good value for money. If I am to abide complex syntax then I'd better get sophisticated, powerful semantics in return.
HTML 1.0 (no CSS, no JS, no floats) is very similar in scope to Markdown. I wish every site that uses Markdown would allow me to write something like HTML 1.0 instead. It would be so much easier, at least for me.
Keep in mind that it’s not all about simplicity. One of the selling points of MarkDown is that it’s legible even when left in its plain text source format.
I'd wager that GitHub is one of the biggest publishers of larger-than-bite-sized Markdown documents, and this "selling point" (an argument which I both agree with about [original] Markdown and agree that this is a good property) is pretty much untrue for any given piece you'll find on GitHub. This is thanks to several factors including "GitHub-Flavored Markdown" differing so wildly from the original flavor, and the typical GitHub user just not giving a shit about how the raw form looks—treating it as just another non-WYSIWYG formatting language in the vein of HTML or TeX, since all they're really after most of the time is for their README to work as a substitute for a product landing page.
Pug is HTML but beautiful and more powerful, I’m surprised it hasn’t been brought up.
The best format I’ve found to author web pages, though, is definitely MDSvex [1], which is essentially markdown with built in syntax highlighting for code blocks, vanilla HTML if needed, and Svelte / Svelte components for any reactivity / reusable components if JS is needed. Stick some pug in the Svelte Component and I’ve got unlimited power in a beautiful, readable syntax with 0 boilerplate, all compiling to vanilla HTML and optionally hydrating JS. Love it!
Markdown hasn't changed a bit from its reference implementation, it can't.
Everybody who grabbed onto Markdown and is forking it because they're realizing that it was a very simple tool to solve one man's blogging problem and ignored all the other more comprehensive LWMLs is reinventing HTML.
What's interesting about that is that John Gruber uses footnotes extensively in his own blog posts (and has since approximately 2005), but chooses to implement them with HTML snippets rather than having created a dedicated Markdown syntax for them.
GitHub-flavored Markdown is different; it's almost taken over as the de-facto standard. There are lots of wacky extensions out there, but this isn't just another one of those.
Yeah, the lack of nested formatting in rST is crazy. For me it's annoying I can't just do a simple monospace formatted link in pure rST. Sphinx helps a bit with that depending on what you want to link, but it's not really controllable at the rST level like it is in other markup.
Makes me wonder, since there is evil mode and opinionated Emacs disributions like Spacemacs und Doom Emacs, whether there is a potential for an org-mode focussed and optimized Emacs distribution.
Ease of use should be one of the core goals, then.
I just read that using "id" is the preferred way (see the other reply) "name" is deprecated for this use, but it still works of course (I'm not a web developer, been using the same markdown trick for years)
The details html tag works fine on GitHub; or did you mean you’d like a new syntax that’s more markdownesque?
EDIT: Definite +1 for the stable headers id suggestion. I implemented something similar in a proof of concept app a while back, but it was a suffix rather than a prefix, in brackets, like so:
# About this project { #about }
It worked really well, and the syntax allowed for additional properties like css like class syntax. Thouh we referred to them as tags because they were used to tag sections, paragraphs etc., so we could do some interesting aggregation later on.
We did something similar to this, but used ~ instead, like so:
~ Definition title
The definition data should be indented at the same level
as the title. This let's you nest definitions also:
~ Like this
Here's a nested definition.
We also allowed : instead of ~ but most people seemed to prefer the latter. We didn't collapse anything in rendering though, but it's not a bad idea. The resulting markup when rendered to HTML was actual definition lists (<dl>) though, not details, so that'd either have to be done by nesting details or css magic I suppose.
Is https://github.github.com/gfm/ maintained? If so I would have expected to see this addition in there. On that subject, it's been a while since I needed a new markdown parser but I kinda like this feature, where do I find the source for the parser?
EDIT: OJFord answers my question below.
P.S. Why am I forced to watch (and re-watch) an animated GIF when you could have simply shown the source and resulting rendered HTML in my browser?! Meanwhile, the example code they do provide is left completely without a rendered output. Must everything spoon feed video these days? Madness!
Instead of reinventing the wheel and shoehorning basic functionality into markdown, why not just use a markup format that already “just works”, like asciidoctor?
Awesome. GitHub-flavoured markdown is definitely my favourite Markdown editing experience overall. That’s largely due it being 95% markdown and ‘not Markdown plus a bunch of other cool features with poor interoperability’ that you find in Notion and Confluence.
Is there a proper document editor (eg. Has live preview) that is the same as GitHub-flavored Markdown such that I can copy text into Confluence or Notion and have things ‘just work’? I would use that as my editor and just copy into other places for publish.
I think CommonMark misses the mark (pardon the pun) by not having tables as part of the spec. Mind you, GFM tables leave much to be desired, but I'm constantly writing tables in my notes and it's frustrating to not see this supported in CommonMark.
there was a ``` dangle in the last code fence in a post. It didn't always appear, looked to be dependent upon content in the fences, but often enough as to notice.
A nice addition - I wonder though why GitHub Markdown still doesn't support image resizing. Seems to be one of the most obvious feature if you embed images.
You know what's not supoprted in GitHub Markdown? Anchors. There are no functional anchors on any GitHub page. They have something in their markdown that looks very much like anchors but instead of being an actual HTML anchor it requires loading and executing javascript first.
If github wants to actually support real markdown then footnotes are good, but maybe work on supporting anchors first. They're very important for readmes.
And I don't actually think that's a bad thing, so long as it stops there. HTML has become much more than documents, so having a constrained subset dedicated to documents is helpful.