Closed Kristinita closed 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
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.
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.
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. 👍
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.
That stated, do note:
My take on issues and PRs and the processing of these is the following:
Some of the pitfalls I see for open source projects are:
In the case of this particular issue.
@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.
@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.
Hi @naokazuterada, your suggestion on use of the wontfix
label would do
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
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 :-)
@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.
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.
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?
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>
.
<style>
inside markdown (See this)@Kristinita Is my understanding enough? And could you agree with that?
@jonasbn @Kristinita Hello, how are you? Could you give me a reply please?
hi @naokazuterada sorry for not responding got caught up in work and some other open source projects :-)
@naokazuterada your observations are more to the bone than mine. So in order to meet @Kristinita use-case some post processing would be better.
@naokazuterada based on your example and conclusion I tend to agree with you - request is out of scope for MarkdownTOC
@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.
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:
Thanks.