[Feature request] Permalink support

Kristinita commented 7 years ago

1. Request

It would be nice, if you add feature — permalink next to the anchor as Python documentation.

2. Justification

Quick getting links to sections in HTML-articles.

3. Steps to reproduce

User convert Markdown with TOC, created by your package, to HTML → user hover mouse to any anchor.

4. Expected behavior

If "permalink": true,

user will see, for example, ¶ symbol.

If user click to ¶ symbol:

user get in URL-bar of browser permalink to anchor.

5. Examples on other apps

For example, it realized in Python documentation. Example page:

Python documentation

Thanks.

jonasbn commented 7 years ago

Good morning @naokazuterada

You need to decide with this is something we need to proceed with, I have labelled the issue as a new feature, but a decision has to be made on whether it should be implemented.

jonasbn

naokazuterada commented 7 years ago

Good morning @jonasbn, and sorry for late reply @Kristinita.

I have thought about this request well, but decided not to implement it. This feature seems to change the original document too much. And I think this plugin is not the best place to implement that function. I think markdown renderer is more appropriate place.

I'm sorry I couldn't follow your request, but I close this issue.

Kristinita commented 7 years ago

Replies

I have thought about this request well, but decided not to implement it.

This feature can be as an option, not by default. It can be useful for another users.

I think markdown renderer is more appropriate place.

I wrote similar feature request in Python Markdown issue tracker → Python Markdown owner close my issue.

but I close this issue.

This is open source: if you don't want add this option, another users can add it. So, I think, close unfixed issues — is not a good practice.

Thanks.

naokazuterada commented 7 years ago

This is open source: if you don't want add this option, another users can add it. So, I think, close unfixed issues — is not a good practice.

I understand what you saying. I reopened this issue for someone fork and implement this in the future. 👍

jonasbn commented 7 years ago

I went through a lot of the older issues on the issue list yesterday and recommended a handful closed. Here is my rationale behind this and general handling of issues and PRs on an open source project.

Starting with the open source aspect, this is a general observation, and is by no means specific to this project.

The author in a project like this (in this case @naokazuterada) always have the privilege to decide on the scope and direction of the project and what should stay and what should go (alternatively a project organisation could be established)
You can always fork the project and implement your own changes/features/fixes (licensing applies)
A project is by no means obliged to adopt all requests

That stated, do note:

A project is empowered by its users and project organisation
Do note that PRs (working and with passing tests) have a higher chance of inclusion
Open source development/maintenance is often done in spare time, meaning that time is often limited
Respect users and their requests and issues, they spent time contacting/describing their case - respond as fast as possible to get clarification
Respect contributors, they spent time developing their change - respond as fast as possible to get clarification
Respect the author, often the author started scratching their own itch, meaning perhaps they did not want to get into maintenance etc. of a project beyond their own requirements, many projects are just a small part of a larger stack/toolchain etc. meaning the author have other projects, which might have higher priority (this addresses the empowerment mentioned first, perhaps it is beyond the project scope to exploit this aspect)

My take on issues and PRs and the processing of these is the following:

Only keep issues open, which you want to address or which makes sense in the context of informative level (known bugs/issues) etc. for the latter, this can alternatively be documented in the general documentation as limitations etc and then closed (if they will never be addressed)
A project with lots of open issues and PR could give the impression of being unmaintained or unresponsive, so only keep open relevant issues - address issues and PRs ASAP
Closed issues do not go away, they are still available, but they have been addressed and nothing further will be done

Some of the pitfalls I see for open source projects are:

loss of interest from the authors/contributors
broken promises, features never being implemented, bugs never being fixed, releases never being made
too much maintenance and support

In the case of this particular issue.

It should be closed if no plans exist to implement it (if anybody want to pick it up, they will still be able to find it)
I find the use-case interesting, but it is @naokazuterada who has to decide (his decision for now is to keep it open)

@naokazuterada please evaluate my rationale and lets discuss on how to apply the principles you can support to this to this project. I have no obligations or special interest in the project apart from that I am a user and a contributor, so I respect your work and decisions completely. If I disagree I can always walk away. The project is a good a healthy project and I want to keep contributing to keeping it that for as long as I have the interest and your accept.

naokazuterada commented 7 years ago

@jonasbn

First of all, I appreciate your many contributions. I cannot thank you enough. And I read your observations and thoughts interestingly. Thank you so much.

As you guessed above, this project began with my personal purpose since a long time ago. I do not use it anymore. My motivations are technical interest and to communicate with users in English through this project (I mean just for the purpose of "learning"). These are almost everything.

A project with lots of open issues and PR could give the impression of being unmaintained or unresponsive...

It's undesirable for this project to give users such impressions. And I noticed that you were doing best for that. Thank you again.

In this case, I've already accepted @Kristinita's request (to keep this issue opened) once.

But I was worried whether my decision was right or not after I commented. I thought that my decision was a temporary measure. I remembered that the other similar issues (not accepted feature requests in the past) is closed. The only difference is whether the reporter clearly requested keeping the issue to be opened. So it's nice for me that you pointed out this, and give me a chance for re-thinking.

Here is my suggestion.

How about "Add wontfix label and close" ? I use this label in meaning of "This issue will not be fixed in the future". (Isn't it correct way of use? I'm not sure why you removed it. If it's not suitable, we can create another label for these not accepted feature requests.) The other not accepted feature requests in the past should also be handled in the same way. Then people can find them easier. As you mentioned above, people can find this issue even if it's closed.

At first, I would like to hear your opinion. Please let me know.

Thank you.

jonasbn commented 7 years ago

Hi @naokazuterada, your suggestion on use of the wontfix label would do

jonasbn commented 7 years ago

Lets work our some guidelines for the project at some point, perhaps we can discuss this on Gitter or IRC.

Anyway to get back on topic with this particular issue.

I have never really worked with permalinks before, so I read the article on Wikipedia. As far as I can see, they way we generate anchors we would have to do some more, since the TOC generation is a somewhat dynamic feature (one of it's strengts IMHO).

If the usage pattern is to stick to a template for documentation or somewhat static titles between generations of revision this could work. The plugin should add the domain part and then keep the generated part, the domain part should perhaps be a part of the configuration - please beware my knowledge on permalinks is newly acquired and I might have misunderstood aspects or subtleties.

The plugin can as such not ensure that the permalinks will work since only a Markdown representation is generated. It is the final renderring which is depending on the context of use of the generated Markdown (and HTML hints) in systems like Github, Gitlab etc. which gives the final results and should work, which from a Markdown perspective is somewhat out of our control.

Can you assert that it would work if we would insert the following HTML hint (lifted and modified from the mentioned Wikipedia article) according to this example:

Our basic Markdown:

# Introduction

Markdown rocks!

Our MarkdownTOC generated product:

<!-- MarkdownTOC -->
- [Introduction](#introduction)
<!-- /MarkdownTOC -->

# Introduction

Markdown rocks!

The rendered HTML version could (example copied from Github) rendered as follows:

<!-- MarkdownTOC -->
<ul>
  <li><a href="#introduction">Introduction</a>
</ul>
<!-- /MarkdownTOC -->

<h1 id="introduction">Introduction</h1>

With a configuration parameter like the following, indicating the URL to be used for permalinks.

<!-- MarkdownTOC permalink_url="http://example.com/"-->
- [Introduction](#introduction)
<!-- /MarkdownTOC -->

# Introduction

Markdown rocks!

MarkdownTOC could generate the following Markdown

<!-- MarkdownTOC permalink_url="http://example.com/"-->
- [Introduction](#introduction)
<!-- /MarkdownTOC -->

<link rel="bookmark" href="http://example.com/introduction" />
# Introduction

Markdown rocks!

Which would then possibly be rendered as follows (depending on context):

<!-- MarkdownTOC -->
<ul>
  <li><a href="#introduction">Introduction</a>
</ul>
<!-- /MarkdownTOC -->

<link rel="bookmark" href="http://example.com/introduction" />
<h1 id="introduction">Introduction</h1>

Please take into consideration I am making this up as I go a long, in order to outline a possible approach and getting an understanding of the proces etc.

@naokazuterada you are the expert on MarkdownTOC and I am just here to learn and possibly contribute - have I misunderstood permalinks and the MarkdownTOC proces.

Looking forward to your feedback

jonasbn commented 7 years ago

Hi @Kristinita

I have no prior experience with permalink generation, in your suggestion you would rely on a boolean (true/false), but would that suffice? it seems the domain part of the URL (and perhaps even the protocol designator and path) play an important part. MarkdownTOC only generates Markdown - the product is in general not aware of how it's product is hosted/served and distributed.

Please let me know if I am rambling, it is getting late here and I am getting tired :-)

naokazuterada commented 7 years ago

@jonasbn Thank you very much for working late for this plugin. :clap: And, sorry for my late reply. It took times to understand your texts. :disappointed_relieved:

Lets work our some guidelines for the project at some point, perhaps we can discuss this on Gitter or IRC.

It's a nice idea! Is the discussion theme 'Operation guideline for GitHub Issues', isn't it? I will be looking for some model in other projects later. It's no problem that using Gitter. But 'distinguish between Gitter and GitHub Issues properly' is also ambiguous for me. If you have a clear criteria, please let me know and we should write it down on README.md or CONTRIBUTING.md.

I've read the article on Wikipedia. I appriciate that you have spent a lot of time to think about "permalink" deeply.

Perhaps my understanding is not enough, but I write my concerned below.

Point 1

At first, I think you are right that 'parmalink' should be absolute path in the strict meaning. But in this case, within the document itsself, it is not necessary to be absolute. Relative path link can also work. So permalink_url attribute is not necessary, I think.

Point 2

Next, I'm not sure about this line below.

<link rel="bookmark" href="http://example.com/introduction" />

What resorce did it point to? I can understand if it is http://example.com/#introduction. But it's http://example.com/introduction. URL Hash permalinks is not allowed strictly?

Point 3

And your solution can not meet @Kristinita's request

I think the feature @Kristinita wants is like below.

<!-- MarkdownTOC permalink="true"-->
- [Introduction](#introduction)
<!-- /MarkdownTOC -->

# Introduction

Markdown rocks!

After "Update TOC"

<!-- MarkdownTOC permalink="true"-->
- [Introduction](#introduction)
<style>
  h1>a[data-markdowntoc],
  h2>a[data-markdowntoc],
  h3>a[data-markdowntoc],
  h4>a[data-markdowntoc],
  h5>a[data-markdowntoc],
  h6>a[data-markdowntoc]
  {
    visibility: hidden;
  }
  h1:hover>a[data-markdowntoc],
  h2:hover>a[data-markdowntoc],
  h3:hover>a[data-markdowntoc],
  h4:hover>a[data-markdowntoc],
  h5:hover>a[data-markdowntoc],
  h6:hover>a[data-markdowntoc]
  {
    visibility: visible;
    color: #0072aa;
    text-decoration: none;
    font-size: 0.8em;
    padding: 0 4px 0 4px;
  }
  h1:hover>a:visited[data-markdowntoc],
  h2:hover>a:visited[data-markdowntoc],
  h3:hover>a:visited[data-markdowntoc],
  h4:hover>a:visited[data-markdowntoc],
  h5:hover>a:visited[data-markdowntoc],
  h6:hover>a:visited[data-markdowntoc]
  {
    color: #6363bb;
  }
</style>
<!-- /MarkdownTOC -->

# Introduction <a data-markdowntoc href="#introduction">¶</a>

Markdown rocks!

And HTML would be like below.

<!-- MarkdownTOC -->
<ul>
  <li><a href="#introduction">Introduction</a></li>
</ul>
<style>
  h1>a[data-markdowntoc],
  h2>a[data-markdowntoc],
  h3>a[data-markdowntoc],
  h4>a[data-markdowntoc],
  h5>a[data-markdowntoc],
  h6>a[data-markdowntoc]
  {
    visibility: hidden;
  }
  h1:hover>a[data-markdowntoc],
  h2:hover>a[data-markdowntoc],
  h3:hover>a[data-markdowntoc],
  h4:hover>a[data-markdowntoc],
  h5:hover>a[data-markdowntoc],
  h6:hover>a[data-markdowntoc]
  {
    visibility: visible;
    color: #0072aa;
    text-decoration: none;
    font-size: 0.8em;
    padding: 0 4px 0 4px;
  }
  h1:hover>a:visited[data-markdowntoc],
  h2:hover>a:visited[data-markdowntoc],
  h3:hover>a:visited[data-markdowntoc],
  h4:hover>a:visited[data-markdowntoc],
  h5:hover>a:visited[data-markdowntoc],
  h6:hover>a:visited[data-markdowntoc]
  {
    color: #6363bb;
  }
</style>
<!-- /MarkdownTOC -->

<h1 id="introduction">Introduction <a data-markdowntoc href="#introduction">¶</a></h1>

Markdown rocks!

Note: I don't use class attribute, because there are conflict posibilities with other stylesheets. Note: :hover is not supported in style attribute, so I have to use <style>.

Reason why I decided to refuse this request

Adding stylesheets is necessary
- Too much document alteration for this plugin
- Difficulty of maintenance in the future
- We cannot create perfect stylesheet (There are many patterns can not cope)
- Github doesn't allow <style> inside markdown (See this)
- Simply ugly...
tracking anchors correctly inside heading is difficult
- The plugin will be lost anchors if the user has edited it even if it's a little
  - If it's happened the heading link in TOC will break
- Difficulty of restoring original document
Fundamentally this is not this plugin's matter
- Markdown render is more suitable for this

@Kristinita Is my understanding enough? And could you agree with that?

naokazuterada commented 7 years ago

@jonasbn @Kristinita Hello, how are you? Could you give me a reply please?

jonasbn commented 7 years ago

hi @naokazuterada sorry for not responding got caught up in work and some other open source projects :-)

On point 2.

@naokazuterada your observations are more to the bone than mine. So in order to meet @Kristinita use-case some post processing would be better.

On point 3

@naokazuterada based on your example and conclusion I tend to agree with you - request is out of scope for MarkdownTOC

naokazuterada commented 7 years ago

@jonasbn Thank you for your reply! I'm glad to get your approval.

@Kristinita I will close and add wontfix label to this issue If you do not object. Please give me approval.

naokazuterada / MarkdownTOC