Prettier display ideas

[hmelman]

It might be nice if markdown-mode implemented some of the ideas shown in this post referring to org-mode. In particular, an option to hide the markup for italics or strong and the ability to display nice unicode bullets.

http://www.howardism.org/Technical/Emacs/orgmode-wordprocessor.html

[jrblevin]

Thanks. I'm on board with all of these ideas, provided of course that they are implemented as optional features. Inspired by AUCTeX, I use variable-height headers locally much like those described in the post.

[jrblevin]

As a first step, fb7b025 adds built-in, customizable support for variable-height header faces. See markdown-header-scaling for details.

[jrblevin]

Perhaps you saw, but another step in this direction is that markdown-mode now supports clickable links for all kinds (inline, reference, angle bracket, and plain URLs). I also added URL hiding (inline and reference) via markdown-hidden-urls. By default, URLs will appear as [link](∞) instead of [link](http://perhaps.a/very/long/url/). This feature can be toggled using C-c C-x C-l (markdown-toggle-hidden-urls). The remaining part here is to write an easy link editing function, but as in org-mode you can delete the last character to edit the URL for now.

I've also got working, but not fully tested code that does the following:

1. hides markup for links, bold, italics, code, and headings
2. uses pretty markup for list bullets, blockquotes, and horizontal rules

The thing I'm not sure about is what to do with headings. With header-scaling on (variable height fonts), is that alone enough to identify the level if the markup is hidden? Other options would be to put small "h1", "h2", etc. indicators in front or to add bullets at the front of varying size like in org-bullets mode.

[jrblevin]

After using it bit longer, for the headings I think adding a bit more range for the scaling and perhaps shading the colors slightly for lower level headings will work just fine. If not I can add some other adornment later. It's simple enough to toggle back to displaying the markup as needed.

Here's a preview. I think this is going to be really nice—thanks for the ideas!

[hmelman]

markdown-hidden-urls looks useful but perhaps not for me. I appreciate the easy toggle and will play with it. I like that the markup characters [] () are dimmer.

• Perhaps the variable should be markdown-hide-urls or markdown-hide-markup
• Perhaps the command should be markdown-toggle-hiding if you'll add more hidden things like markup for bold/italics
• Currently the ∞ is in markdown-markup-face and but the full expanded link is in markdown-url-face. Perhaps the ∞ should be in markdown-url-face as well.

[jrblevin]

As always, thanks for the feedback.

• 40e4901: Shortened URL remains in markdown-url-face. Shortened reference labels remain in `markdown-reference-face'. I had it this way originally, but changed it just before releasing. I think you're right though.

• d276f39: Variable markdown-hidden-urls is now markdown-hide-urls. Function
  markdown-toggle-hidden-urls is now markdown-toggle-url-hiding.

Stay tuned for full markup hiding (as in the screenshot above), which I think is the mode you'll like better and is more in the spirit of this issue...

[jrblevin]

I have now added markup hiding via a custom variable markdown-hide-markup, which determines whether to hide Markdown markup (or otherwise beautify it somehow). Currently it works for italics, bold, inline code, inline links, reference links, angle bracket URLs, and kbd tags. For example, for inline links the brackets, URL, and title will be hidden and only the (clickable) link text will remain. The URL can be seen by hovering with the mouse pointer and edited by deleting one of the invisible brackets or parentheses. This can be toggled interactively using C-c C-x C-m (markdown-toggle-markup-hiding) or from the Markdown | Show & Hide menu.

This setting superceds URL hiding, since it hides URLs completely rather than simply shortening them.

See 8390d07, fd9eb1c, and 6c72cb4 for details.

Headings have proven more complicated than expected, because hiding the markup (by setting the invisible property) breaks all of the heading navigation and outline visibility cycling code. I'm in the process of rewriting that to account for the changes.

Also, beautification of list bullets, blockquotes, and horizontal rules is coming soon. Later I'll work on code blocks, strikethrough, sub/superscripts, footnotes, and so on...

[hmelman]

Looks pretty nice!

I ran into something that I didn't realize. Why do markdown-bold-face (and italic, strike-through and I guess metadata-key) inherit from font-lock-variable-face? I didn't notice it because usually my bold text is a link and the link color overrides the bold color. But I have some plain text that's bold and it's showing up not only bold but also a different color than the surrounding text and it (now?) looks odd.

[abbioro]

I noticed that too, links should at least inherit from the link face so that they are underlined. I guess the rest are up to the author, in Org mode the text doesn't use any special colors for italics/bold/etc. and I prefer it that way. Removing the special coloring from italicized/bold words would make the text look less "noisy" (which is also why I really appreciate being able to hide the asterisks and stuff, it makes Markdown documents a lot more readable).

[jrblevin]

It has only been that way for ten years, so it's understandable that no-one noticed until the markup was hidden :)

Seriously though, I'm not sure if my Emacs at the time (~21 on Linux) could even render bold or italic, but even today italics doesn't work in a terminal, so I also used colors for the faces. I used the font-lock-* faces because I wanted to derive from already defined, but unused, faces so the colors would come from the user's own theme.

Perhaps I can change this now that terminal use is less common and markup can be hidden. In the meantime, as I'm sure you know, the faces are customizable so you can remove the inheritance pretty easily.

[abbioro]

In the meantime, as I'm sure you know, the faces are customizable so you can remove the inheritance pretty easily.

Of course, I don't mind it if you keep it this way. Just some food for thought :P

[hmelman]

I'm definitely a fan of mode faces inheriting from builtin faces and feared I suggested this at some point. :) But in particular for bold and italic I think it's unnecessary to inherit from font-lock faces. There are standard builtin faces "bold" and "italic" that could be used. If italics can't be rendered, it's likely that face does something the user wants. I agree that "link" face is worth considering too.

[jrblevin]

Thanks--Also, the reason I didn't set markdown-link-face to inherit from the link face was exactly because the underline was too busy with all the markup visible. I agree that it makes sense when markup is hidden, but I'm not sure what the best default is now... I could dynamically redefine the face when markdown-hide-markup is changed, but that seems a bit much.

[jrblevin]

There are going to be a lot of changes in the next release, so let's try it out: d2122e1.

[jrblevin]

Update: hidden markup works for headings and blockquotes now, too.

[jrblevin]

Update: also now unordered list bullets, horizontal rules, and strikethrough.

[jrblevin]

Update: now fenced code blocks, definition list items, and sub/superscripts (see GH-134) are supported for markup hiding.

I think that's everything--any comments or suggestions on the implementation?

Update: Fixed GH issue number referenced above.

[hmelman]

Seems nice. I'm good with how bold and italics works. I think the difference with font-lock-variable-face was that when markup was shown it's appropriate to make the text stand out more, with the markup hidden, just getting the bold or italics is the right thing. Lists with bullets look great, and sublists work well.

I don't love that urls now have underlines and are blue, but it's probably the right default and I'll customize markdown-link-face (I typically turn off link underlining in browsers). I think I don't customize the face link because something else looks weird (maybe info or eww?)

I like markdown-fontify-code-blocks-natively. Is there a reason it's not on by default? Maybe the fence lines themselves could be hidden when hiding markup (at least when there's nothing else on the line)? Otherwise there's an extra line above and below the code block and it looks like too much vertical whitespace.

I kinda want headings, when markup is hidden, to be centered. I suspect it won't work well in practice, but I'll throw it out there. I'm thinking centering in this case should have its own user option. Also it should center based on the width of the text on the line. I opened a file with narrow margins in a wider window and realized that I'd want the header centered within the margin and not based on the full width of the window. A complicating factor I know, but just a thought.

Also, maybe there should be a way to specify to open files with markup hidden by default? Maybe it should only do this if the buffer is read-only?

Overall I think this is great stuff and I'm going to enjoy it a lot. Thanks.

[jrblevin]

Thanks for the report. I'm glad you are enjoying it!

I don't love that urls now have underlines and are blue, but it's probably the right default…

I was on the fence about using link, but I thought it was worth trying. I'll take a look at what some popular themes do with it and re-evaluate before the next release.

I like markdown-fontify-code-blocks-natively. Is there a reason it's not on by default?

I was a worried about performance. I also took a cue from org-mode, where org-src-fontify-natively is off by default. (See the related note below about setting default values, which should work better now.)

Maybe the fence lines themselves could be hidden when hiding markup (at least when there's nothing else on the line)?

I agree, but that needs a bit more work. The fenced code block parsing code is pretty complex, and needs to be modified before I can hide those lines.

I kinda want headings, when markup is hidden, to be centered…

I'm quite not sure how to do that (maybe some spacing calculations and a padded display string?), but I'll note it as a feature request and keep it in mind.

Also, maybe there should be a way to specify to open files with markup hidden by default? Maybe it should only do this if the buffer is read-only?

I'm not sure at what point in the day you tried it out, but I also noticed that when markdown-hide-markup was set to t, it didn't apply when opening a new file. I think I fixed that in e0c4412. Let me know if not.

[jrblevin]

Maybe the fence lines themselves could be hidden when hiding markup (at least when there's nothing else on the line)?

I agree, but that needs a bit more work. The fenced code block parsing code is pretty complex, and needs to be modified before I can hide those lines.

I found an easier way to do this in aebc03e.

I'm considering this closed now, but if anyone has other feedback on the new features please feel free to discuss. Thanks again for the suggestions.

[hmelman]

Also, maybe there should be a way to specify to open files with markup hidden by default? Maybe it should only do this if the buffer is read-only?

I'm not sure at what point in the day you tried it out, but I also noticed that when markdown-hide-markup was set to t, it didn't apply when opening a new file. I think I fixed that in e0c4412. Let me know if not.

Didn't realize about the bug but that wasn't what I was thinking. My sense is that when opening a file to edit I'll always want markup shown. So I'll set markdown-hide-markup to nil and toggle as needed. I think I'll consider hidden markup as rendering and I'll occasionally want to open a file not to edit but to view and in those cases, opening it with markup hidden would be nice. I could just open the file in Marked 2 but it might be nice to open in emacs at times. So I was trying to figure out a way to override the default setting of markdown-hide-markup when opening a file. A new command seems overkill, but a way to say that opening a markdown file as read-only should be "rendered" (as markup hidden) seemed like something I might use. Just and idea.

[jrblevin]

Perhaps a new defcustom, something like markdown-hide-markup-when-read-only, combined with a read-only-mode-hook to handle toggling and restoring the state?

[saf-dmitry]

I think raising footnote markers and especially inline footnote text should be optional.

At the same time I would suggest to always display sub- and superscripts as, well, sub- and superscripts and not only if markdown-hide-markup is set to t.

[jrblevin]

Thanks, I'll work in some additional options in the next version.