Add Social Share Links to Page/Element

[mweth]

Context

For public facing instances, the ability to easily share a specific section, image, or page via social media will enhance content accessibility and enhance the user experience.

Description

This proposal is to integrate a social share link plugin within Material for MkDocs. This plugin would enable users to quickly share a link to a specific section (identified by page.md#heading), an image (either to the nearest section or page), or an entire page to various social media platforms. The plugin would automatically generate a shareable URL, which could be automatically generated and places with each page/section or be invoked (**Article ** { socialbutton }). When clicked, it presents users with options to share the content on platforms like Twitter, LinkedIn, Facebook, and others, directly from the documentation site.

The ability to share specific sections or images allows for more targeted and relevant sharing. Users can highlight exactly what they find interesting or valuable, making the shared content more personalized and likely to engage others on social media.

This addition aligns with Material for MkDocs’ principles by:

Enhancing existing features: Social links are already a part of the footer logic and an existing library of icons and layout can be used to implement this feature.

extra:
  social:
    - icon: fontawesome/brands/mastodon 
      link: https://fosstodon.org/@squidfunk

Enhancing accessibility and usability: By making it easier for readers to share content, we extend the reach of the documentation to a wider audience, including those who rely on social media for discovering useful resources.

Maintaining simplicity: The plugin keeps the focus on Markdown content creation without requiring additional knowledge of HTML, CSS, or JavaScript from the document authors.

Promoting Openness and Community Engagement: The ability to share content easily on social media aligns with the open-source spirit of MKDocs, fostering community engagement and collaboration. It allows the content to reach a wider audience, encouraging feedback and contributions.

Supporting all devices: Given the prevalence of social media usage across various devices, this feature ensures that the documentation remains functional and accessible, regardless of the viewing device.

Being lightweight: The proposed feature aims to be fast and unobtrusive, maintaining the theme's commitment to performance and a minimal footprint.

Related links

Social links are already included in footer code: https://squidfunk.github.io/mkdocs-material/changelog/#1.0.0

https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/

https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/meta.md

Use Cases

From an Author's Perspective:

Ease of Implementation: Authors can continue to focus on writing quality Markdown content without worrying about generating anchor links and highlighting them on pages/sections. With automatic or invoked share links, the user can decide when and where the share links appear.

Increased Visibility: By enabling social sharing, authors can more effectively promote their documentation across social media platforms, reaching a wider audience and potentially driving more engagement with their content. This feature aligns with the project's goal of creating accessible, high-quality documentation that serves the needs of a diverse user base.

From a User's Perspective:

Convenience: Heading anchors are not currently shareable. By adding this feature, users can easily share helpful sections, images, or pages with their network, enhancing the collaborative aspect of documentation. This functionality is particularly beneficial in educational, professional, and community settings where sharing resources is commonplace.

Enhanced User Experience: The plugin caters to the modern web user's expectations for interactivity and social connectivity, improving the overall user experience. It aligns with Material for MkDocs' principle of serving documentation that is adaptable and accessible across all devices.

Visuals

This is an example where a link image is clicked, which unfurls social links: https://dev.to/dsasse07/implementing-a-social-share-feature-jd7

Before submitting

• [X] I have read and followed the change request guidelines.
• [X] I have verified that my idea is a change request and not a bug report.
• [X] I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• [X] I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[squidfunk]

Thanks for suggesting. We've evaluated this feature request and currently don't plan to directly add this functionality to Material for MkDocs because of its inherent complexity, and thus necessary effort to pull this off, and rather limited use, as it's likely only useful in blogging contexts to most people, since people usually don't share documentation pages on social media. There are several JavaScript based solutions that can be used out of the box. Additionally, this can be implemented as a third party plugin, as there's no need for a deep integration with Material for MkDocs.

[squidfunk]

On a further note:

Heading anchors are not currently shareable.

They are if you enable toc.permalinks.

[mweth]

On behalf of fellow dumb people who don't don't know what to Google, can you elaborate on the JavaScript based solutions that can be used out of the box and third party plugin route?

Also, THANK YOU for the permalinks note!

[mweth]

EDIT: with toc.permalink enabled, 95% of my issue is solved. Thank you!

P.S. I'm sharing my public service project because it is a little different from what most people are using this for and you might find it amusing: Official Code of Georgia, Illustrated

[squidfunk]

@mweth Sure, I searched for "social share button js" and found plenty of options. However, glad that most of your issue is resolved! Note that many other features allow to share links, i.e. content tabs, as well as code annotations.

If anchors are nested within multiple levels of annotations, sharing them is currently not possible, but we will be working on that soon. Note that this is quite a complex topic given the infinite number of combinations authors can use this project, so please give us some time on that – we have it our backlog.

[squidfunk]

On a further note, we're aware that this project is used in so many more ways than for what it is (or was originally) intended ☺️ We've seen authors using it for their bike shops, course work, personal home pages, digital gardens, yada yada yada. This was also one of the main motivations to build the blog plugin, in order to allow a wider audience to benefit.