HTML5 update

Jeff Mcneill edited this page Jul 14, 2016 · 8 revisions
Clone this wiki locally

I think we need a path forward for the generated markup. A few things are beginning to be outdated by HTML5. The problem is that some websites depend on the current markup, making all this a breaking change for those sites. And it's hard to evaluate how many site such changes would break.

Generated Markup

My current idea is to make a big leap to update everything to HTML5 in one shot, with a configuration option to revert to the old markup. The big leap would make it noticeable so that things aren't breaking sneakily one by one at each update. Making a list of everything in need for an update would be a good start. So here is a tentative list, feel free to improve:

Footnotes (Extra)

Currently using the rev attribute for back-links. This attribute is no longer in HTML5.

Tables (Extra)

Currently using the align attribute for cell alignment. This attribute is no longer in HTML5.

Ordered Lists (Extra)

HTML5 brings back attributes like type to change the counter in an ordered list. This attribute would be helpful for legal documents. Currently the only solution is to wrap the list in another element and style it with CSS.

New Syntax Elements (for PHP Markdown Extra)

HTML 5 introduces new elements. While Markdown doesn't try to convey everything that is possible with HTML, some of the new things might benefit having a Markdown-specific syntax.

Figures with captions

The HTML <figure> element allows us to regroup some content being used for illustrative purpose, often images. The <figcaption> element lets us put a caption on a figure.

Idea: use "!" to create a figure:

[ Figure 1: some image ]
!	![image_alt](image_url "image title")

[ Figure 2: some text ]
!	paragraph

	this is it

	blah bla

[ Figure 3: some code ]
!	~~~

[ Figure 4: some table ]
!	[ Table 1: passwords for all my friends ]
	user | password
	---- | --------
	mike | mypass

[ Figure 5: nested figures ]
!	[ Figure X: another figure ]
	!	[ Figure Y: yet another ]
		!	this is getting ridiculous

Now, just make the leading "!" and indentation optional for an image and you get this:

[ Figure 1: A simple image ]
![image_alt](image_url "image title")

And preceding the figure with a caption could be optional:

!	some figure with text and without a caption

And we might want to allow the caption to appear below the figure:

![image_alt](image_url "image title")
[ Figure 1: A simple image ]

Alternative Figure Using Fence

The Markdown Extra Extended fork has experimental support for figure via an alternative fence using the equals sign.

=== [Figure 1: A simple image]

Including a method for attaching classes and possibly IDs to figures would also be helpful. A figure containing a blockquote might be handled drastically different from a figure containing an image or a video.

Alternative Implicit Figure Using Div

The implicit figure option in Pandoc may be of interest.

Table captions

Not really new in HTML5, but if we add captions for figures, it should work the same way for table.

Notes / Comments

  • There seem to be two or three things here. One is implementing some HTML5 stuff (e.g., figure), and a second is updating the deprecated stuff (e.g., table align). I guess a third thing is how to deal with implementing the first or the second, but the implementation issue of updating the deprecated need not require implementing the new (obviously this point is already made here). Priority might be on the stuff that is deprecated, which would make the task easier, as opposed to one fell swoop.
  • Also it would be great to have the updates in a way so that whatever might change in terms of the markdown syntax itself a search-and-replace would help with the old stuff out there.