mkdocs-material

mkdocs-material copied to clipboard

Contribution guidelines

• [X] I've read the contribution guidelines and wholeheartedly agree

I want to suggest an idea and checked that ...

• [X] ... to my best knowledge, my idea wouldn't break something for other users
• [X] ... the documentation does not mention anything about my idea
• [X] ... there are no open or closed issues that are related to my idea

Description

When reading technical documentation, it is sometimes useful to be able to report an issue with a link back to the documentation page. This is not the same as opening a pull / merge request to contribute to the documentation and cover other use cases (see "Use Cases")

On GitHub and GitLab, one could point to a specific issue template and pre-fill one of the field with a link back to the documentation page where the user created the issue from, making it easy to get back to the documentation page, from the issue itself.

Use Cases

Some use cases where opening an issue from a page in the documentation would be needed:

• Reader wants to report an issue on a given documentation page.
• The page includes a piece of code, but it does not work for me. I don't know how to fix it.
• The page describes a feature, but the feature does not work as expected. I want to open a bug with a link back to the documentation page.

Screenshots / Mockups

In social.html, an hyperlink like so: <a target="_blank" href="{{ config.repo_url }}/issues/new?title=&body=%0A%0A%5BEnter%20feedback%20here%5D%0A%0A%0A---%0A%23%23%23%23%20Document%20Details%0A%0A%E2%9A%A0%20Do%20not%20edit%20this%20section.%20It%20is%20required%20for%20GitHub%20issue%20linking.%0A%0A*%20Page%3A%20{{ page.edit_url }}" class="md-footer-social__link fa fa-bug" title="Report an issue"></a>

Will create an issue like so:

It is also possible to create an issue from an issue template and pre-fill some of the fields:

<a target="_blank" href="{{ config.repo_url }}/issues/new?title=&assignees=&labels=&template=bug.yml&description=%5BEnter%20feedback%20here%5D%0A---%0A%23%23%23%23%20Document%20Details%0A%0A⚠%20Do%20not%20edit%20this%20section.%20It%20is%20required%20for%20GitHub%20issue%20linking.%0A%0A*%20Page%3A%20{{ page.edit_url }}" class="md-footer-social__link fa fa-bug" title="Report an issue"></a>

Thanks for suggesting! I'm not sure that social links are the best location for this. In general, a "report an issue for this page" might be a great idea but I'm also not sure whether we can make it configurable to a degree where it is easy to add, as well as flexible enough. I'll investigate as soon as I'm back from vacation.

I've investigated and think, that solving this with customization might be a better fit than configuration. The reason is that we would likely need to support separate URL schemes for each source provider, and syntax might be entirely different. As another upside, with customization, users could decide where they want the "report an issue" link themselves.

Additionally, there was not much resonance on this feature request by other users, so I'm not sure the benefits of this feature would justify the additional maintenance overhead. For this reason, I'm closing this as currently not planned.