Display permalinks on hover

[anlau]

Closes issue #37. It's a change in behavior.

Result:

Removed css section "before" had quite an evolution in mkdocs theme. I took the final version (see PR 1931).

Note styles used for "headerlink" class. "font-family" and "font-weight" are the same as on "fa" class.

[chrissimpkins]

Thoughts about the anchor icon? TBH, I'm not a huge fan. I do like the on hover behavior and ability to have a header perma link.

[anlau]

Hehe, no problem! It can be changed in mkdocs.yml:

markdown_extensions:
    - toc:
        permalink: # Some Font Awesome icon or True

[chrissimpkins]

Is it possible to change the default that is used in this project without the yml configuration edit by a user? Do you know if we can add it to the https://github.com/chrissimpkins/cinder/blob/master/cinder/mkdocs_theme.yml?

[anlau]

I'm not sure it's possible. Theme configurations are loaded under "theme" (config['theme']). markdown_extensions are a level above, at the root (config['markdown_extensions']).

[mmatyas]

Would it be possible for the permalink option to support both characters and a FA icons? Personally I'd prefer keeping the default ¶-sign, a literal anchor is not particularly meaningful in non-English languages.

[anlau]

True (or any yaml equivalent) displays ¶-sign. Otherwise, set character is used. If headerlink class uses Font Awesome then an icon is displayed. It raises a good point. Yes it both options are available but it's hard to accommodate both with the same css. I think we have to commit on one (and maybe document it).

I did some more tests:

1. permalink: True

.headerlink {
    display: none;
    padding-left: .5em;
}

permalink can't be changed to a FA icon.

2. permalink:  # Link icon, maybe this is a better one ;)

.headerlink {
    font-family: "Font Awesome 5 Free";
    font-size: 14px;
    font-weight: 900;
    display: none;
    padding-left: .5em;
}

Note that content wiggles when h6 is hovered.

If permalink is set to True then ¶-signs look small.

3. Maybe we could use option 2 but increase font-size; with 18px it wiggles at h5. Also, it doesn't look as good as option 1 and FA icons seem a bit big on headers besides h2.

In any case, one user can modify the css with "extra_css" configuration.

Let me know what you think.

[chrissimpkins]

My 2 cents is that the link icon more intuitively indicates that this is a link to the header. I'm not opposed to the pilcrow symbol. It is likely used frequently enough out there for this purpose.

As I mentioned before, I would really prefer not to show an anchor icon by default and force users to explicitly edit configuration files to use something else. If the markdown_extensions > toc > permalink setting is not present in a user configuration file, does this mean that they get no permalinks? Or is the new behavior always on hover permalinks with anchor icon default that can be modified to a different icon if you specify the permalink setting (True or icon name) in the yaml config file?

[anlau]

Configuration is on the user side. Without permalink, headerlink a is not generated. This is the default for a fresh install (mkdocs new myproject). One user can then set permalink to true to use the default permalink character (¶). Or any other character (or a FA icon if it's supported by his theme).

I'm not sure if I prefer the icon or the symbol.

[chrissimpkins]

Configuration is on the user side. Without permalink, headerlink a is not generated. This is the default for a fresh install (mkdocs new myproject). One user can then set permalink to true to use the default permalink character (¶). Or any other character (or a FA icon if it's supported by his theme).

I'm not sure if I prefer the icon or of the symbol.

This approach sounds good to me. Willing to merge this.

[chrissimpkins]

@mmatyas any thoughts about the two approaches that Antoine posted above?

[mmatyas]

Sure, that sounds fine to me as well!

[anlau]

So, which one should I go for? Style-wise I have a small preference for the symbol.

If it can help, MkDocs default themes use a Font Awesome icon and Material theme a symbol.

On a side note, after this PR is completed we should update MkDocs themes page (update screenshot and add badge: https://img.shields.io/pypi/dm/mkdocs-cinder).

[chrissimpkins]

So, which one should I go for? Style-wise I have a small preference for the symbol.

If it can help, MkDocs default themes use a Font Awesome icon and Material theme a symbol.

On a side note, after this PR is completed we should update MkDocs themes page (update screenshot and add badge: https://img.shields.io/pypi/dm/mkdocs-cinder).

Which one is the symbol? The pilcrow?

[anlau]

Yes, the pilcrow. Sorry if it was not clear.

[chrissimpkins]

Sounds good to me. Let's go with that approach.

[chrissimpkins]

All set to go here after 92bedf9 @anlau?

[chrissimpkins]

This looks great Antoine. I am updating the documentation with these changes but I can't figure out how to activate the Font Awesome icons. When I try to enter a FA icon name, the hover link shows me the string that I enter, not an icon.

[chrissimpkins]

Reviewing the conversation, it looks like you indicated that with this approach we cannot use FA icons. Only the pilcrow. I think that I misunderstood. Will merge and push this release with documentation of the pilcrow only. If it is possible to use FA icons too, please let me know and we will update the docs.

[chrissimpkins]

Released in v1.1.0

https://github.com/chrissimpkins/cinder/releases/tag/v1.1.0

Thank you very much for the changes here Antoine!

[chrissimpkins]

I activated this on our documentation site too btw 👍

[anlau]

Reviewing the conversation, it looks like you indicated that with this approach we cannot use FA icons. Only the pilcrow. I think that I misunderstood. Will merge and push this release with documentation of the pilcrow only. If it is possible to use FA icons too, please let me know and we will update the docs.

Indeed, there's no font-family: "Font Awesome 5 Free", so you can't use FA icons without additional modifications (ex. using an extra_css). Like I said above, it's hard to find css properties which render nicely both cases (see option 3). But you can still use an UTF-8 character of your choice. Maybe we could do something to support both correctly.

[chrissimpkins]

I'm happy with where we are now! I was just trying to figure out how to document FA icon use and kept getting the string that I entered into the configuration file as the permalink 😀