Project

General

Profile

Bug #5180

Markdown h1 not working in Papers

Added by Raffi Khatchadourian over 6 years ago. Updated about 6 years ago.

Status:
Rejected
Priority name:
Normal
Category name:
Social Paper
Target version:
-
Start date:
2016-01-29
Due date:
% Done:

0%

Estimated time:

Description

  1. An h1 heading in markdown tag (like this one) isn't working in social paper.
    1. However, an h2 one does (like this one).

History

#1 Updated by Matt Gold over 6 years ago

Hi Raffi -- looks like Redmine rendered the markdown code. Can you perhaps provide a screenshot or use the code formatting to include it? see this reference sheet -- https://redmine.gc.cuny.edu/help/wiki_syntax.html (available from the Text formatting link above the posting box)

#2 Updated by Boone Gorges over 6 years ago

  • Assignee set to Christian Wach
  • Target version set to 1.9.7

I assume Raffi means:

# Does not work (renders as seen here)

## Works (renders as an h2)

Christian, could you verify and diagnose?

#3 Updated by Christian Wach over 6 years ago

I can confirm this behaviour. However I don't think it's a bug because the vanilla WordPress editor doesn't render the "# Title" markdown either. Received wisdom (!== true, of course) is that a page should contain only one h1 tag, so my guess is that the WordPress JS responsible for the markdown-to-markup conversion ignores attempts to add h1 tags to the content. In keeping with this, WP FEE's TinyMCE toolbar only contains h2 and h3 buttons.

#4 Updated by Christian Wach over 6 years ago

FWIW, here's the code that governs which hN tags are supported, i.e. only h2 through to h6:
https://github.com/cuny-academic-commons/wp-front-end-editor/blob/master/src/js/tinymce.markdown.js#L42

#5 Updated by Christian Wach over 6 years ago

And the WP ticket where markdown support was introduced:

https://core.trac.wordpress.org/ticket/31441

Unfortunately, there's no mention of h1 - and why it's excluded - that I can find. So looks to me like # may be reserved for ordered lists, i.e. prefixing a line with #1, #2 etc.

#6 Updated by Boone Gorges over 6 years ago

  • Status changed from New to Rejected
  • Target version deleted (1.9.7)

Thanks for looking into this, Christian.

However I don't think it's a bug because the vanilla WordPress editor doesn't render the "# Title" markdown either. Received wisdom (!== true, of course) is that a page should contain only one h1 tag, so my guess is that the WordPress JS responsible for the markdown-to-markup conversion ignores attempts to add h1 tags to the content.

This sounds right to me. It's against best practice to have more than one h1 on a page. A reasonable suggestion for the WP editor JS would be for single # to be converted to the next available hx tag, but it's beyond the scope of what we ought to do for SP.

#7 Updated by Raffi Khatchadourian about 6 years ago

I'd like to discuss this a little bit further if you guys don't mind. I've been thinking more about it, and the fact that # happens to map to <h1> is sort of an implementation detail. If I am thinking squarely in markdown, which bosts a minimalistic view-point, I should be able to write multiple #'s in a single document. The fact that that renders to multiple @<h1>@s in the HTML document should not be a concern to the reader. What do you think?

#8 Updated by Boone Gorges about 6 years ago

I agree about the "implementation detail" bit, but only partly, and I don't think I agree on your specific points.

Putting more than one h1 on a page is a violation of standards. These standards are important, in part, for their accessibility ramifications. Screen readers and other assistive technologies depend on markup that is properly semantic. Our users probably don't know or care about these details, and they shouldn't have to: the tools that we build for them should make the decisions for them, and those decisions should be the "right" ones.

I do think that the idea about interpreting # as the next available hx tag is reasonable. It manages to fulfill user expectations (that # will result in Real Big Text) while also preserving the semantic structure of the page. One minor concern about it is that it may violate the expectations of people who are familiar with Markdown and expect a single # to translate to a true h1. Though, I don't worry about this too much - it would be more of a concern if the # processing were anything more than a keyboard shortcut (ie if we were doing real markdown processing in the background).

Also available in: Atom PDF