Plugin users don't know about the template customisation feature

[equivalentideas]

A powerful feature of this plugin is that you can customize the HTML output to suit your specific project needs.

In fact, the maintainers have an expectation that users of this plugin will override the default output.

However, judging from the issues discussion, users don't realise that they can customise the output. @puzrin writes that this is a common mistake: suggesting codebase changes, rather than adding a your own custom template:

As i explained, common mistake is to consider default renderer as out-of-box solution. But it is not. As soon as you accept this fact, you will fine to tune it local.

It seems that some of the most passionate users of this plugin, who are even trying to contribute to it, don't know about one of it's best features, that the output can be customised.

This issue is for discussing what the best way is for plugin users to learn that they can customise the HTML output. Maybe including a section in the readme could be one solution, or at least a good place to start?

Thanks as always for the billiant work on this @puzrin and all the contributors. The analysis here and is all surmised from the issues discussion text and my own experience (I still don't know how to customise the ouput :smile:), so I may have misinterpreted. Of course, that will come out in the discussion :)

[puzrin]

IMHO templates modification is obvious feature of all such plugins. But anyone can do PR with README improvements.

I'd like to close this issue as it tend to be "endless" (without clear criteria "is it solved or not").

[equivalentideas]

Thanks @puzrin , adding it to the readme does seem like a good idea.

it tend to be "endless" (without clear criteria "is it solved or not").

I would politely disagree with this :) I've raised this issue because of what's observable in the issues threads, e.g. that people keep suggesting markup changes and then saying they didn't realise it was customisable. As developers with super specialised knowledge, I'd suggest that's what is obvious to us might not be a good indication of the understanding of users coming to this with different experiences, so maybe better to look at what people are writing.

I would call this issue solved when people stop saying they didn't know they could customise output, or, more practically, when a solution has been implemented, e.g. contributing to the README.

I accept that the feature could be obvious to someone who knows how these plugins work enough to create one :) But, as someone using this plugin in my work, I didn't know it was customisable or that that's common---and probably most importantly, that if it is customisable, I don't know the recommended pattern for doing it. I guess I fall into the group of people who know enough about this to use it in my project, but not enough to know that I'm expected to customise it. As you've suggested, a simple example in the readme would provide all this succinctly.

Anyway, feel free to close this if you like, but you might like to leave it as a prompt for someone who does know the recommended pattern for customisation to pick it up, which might save you the effort of explaining the feature next time someone raises a PR :)

Thanks again.

[puzrin]

I can leave it open for 1 month if it helps. My point is, making PR is more simple than discussing such things in issues.

[equivalentideas]

That sounds good :+1: Totally agree about the PR thing, I just don't have the knowledge yet in this instance. But if I work it out, I'll give it a go.

By the way, I'm using this in an open online resource on refugee lawyering in Australia, so it's going to a good cause :heart:

[thejohnfreeman]

Hi, I really need this right now. Can someone point at any documentation for how to do this? Once I figure it out, I'll come back and add a section to the README.

Alright, I figured it out. Contribution incoming.

[equivalentideas]

Nice work @thejohnfreeman @puzrin :) https://github.com/markdown-it/markdown-it-footnote#customize