Setting the share title (og:title metatag) without affecting share image (index.png) on the front page

[pekkaklarck]

I've been experimenting with using Material for Mkdocs as a new documentation platform for Robot Framework, a popular open source automation framework. You can see the current prototype here:
https://pekkaklarck.github.io/manual/latest

I've been really happy with the results (generating API docs and setting up versioning were somewhat challenging but now work fine), but there's a small issue related social previews that I haven't been able to fix. The generated social images (index.png and others) all look fine, but the share title of the front page isn't what I want. The problem is that title is just "Manual", as seen here, when I'd like it to be "Robot Framework Manual" or possibly "Manual - Robot Framework".

I'm able to change the title to what I want by adding

---
title: Robot Framework Manual
---

to the beginning of the front page. Unfortunately that also changes the generated social image (index.png) so that it has a top title "Robot Framework" and a main title "Robot Framework Manual". The current formatting where the latter is just "Manual" looks much better.

Interestingly the same issue doesn't occur with other pages. For example, the preview of the API section has "API - Robot Framework" as its share title, as seen here, and the social image has just "API" as its main title.

Some questions related to this:

1. Is the different behavior with the front page compared to other pages regarding to the share title a feature or a bug?
2. Is it somehow possible to change the front page title without affecting the social image? I assume I could update the og:title metatag after the site is built, but that feels like a hack.
3. If resolving this requires the insider edition, is there any open source discount?

[pekkaklarck]

Another problem with social preview is that it doesn't work well with versioning. For example, https://pekkaklarck.github.io/manual itself has no preview, as seen here, only the page it redirects to has. I already tested that this is easy to fix by manually adding required metatags to /index.html that mike generated for redirection purposes. I don't know would be it easy to enhance mike to do that automatically, but perhaps it would be a good idea to mention this tip somewhere.

Update: I added the aforementioned metatags to /index.html so now https://pekkaklarck.github.io/manual has a social preview as well. Not hard to do and needs to be done only once, but may not be obvious.

[kamilkrzyskow]

Hello @pekkaklarck,
from your shared links for the social preview we can surmise that the title for the embeds is taken from the og:title.

So to answer in order:

1. Is the different behavior with the front page compared to other pages regarding to the share title a feature or a bug?

Title used for the Social Card

mkdocs-material/material/plugins/social/plugin.py

Lines 188 to 189 in 25b2107

	# Compute page title and description
	title = page.meta.get("title", page.title)

Title used for the og:title meta tag:

mkdocs-material/material/plugins/social/plugin.py

Lines 341 to 344 in 25b2107

	# Compute page title
	title = page.meta.get("title", page.title)
	if not page.is_homepage:
	title = f"{title} - {config.site_name}"

From the code we can see the logic is different in both cases, and the different behaviour for the meta tag on non-homepage pages seems to be done on purpose, so it's a feature and not a bug. However, this logic prevents the user from controlling the value.

2. Is it somehow possible to change the front page title without affecting the social image? I assume I could update the og:title metatag after the site is built, but that feels like a hack.

You could use a hook to modify the page.meta.meta contents.
The Social plugin from the Community version of the theme uses the on_page_markdown event with default priority to fill out the meta information.
Therefore you could use either on_page_content/on_page_context to with default priority to change the value before the pages is rendered or use on_page_markdown with a lower priority to override the value in the same event.

• https://www.mkdocs.org/dev-guide/plugins/#on_page_content
• https://www.mkdocs.org/dev-guide/plugins/#event-priorities

Modifying the saved file later is also an option like you said, but I think it would require parsing the HTML, which isn't necessary with using events above. There are also other ways to add customizability here, but modifying the page.meta.meta should be the easiest. Also have in mind that if you plan to switch to the Insiders version, the Social plugin there has a different structure and logic, so any hooks or "changes" to it will likely not be compatible later on.

Example of a hook file:

• https://github.com/squidfunk/mkdocs-material/blob/master/src/overrides/hooks/translations.py

3. If resolving this requires the insider edition, is there any open source discount?

@squidfunk would need to comment on the discount part, but the docs claim there are no discounts
The Insiders version of the Social plugin support Layouts which add more control over how a social card is rendered or what meta tags are added to the site:

• https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#typography
• https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#tags

[pekkaklarck]

Thanks for the reply @kamilkrzyskow!

I was able to fix the issue using hooks as you proposed. As seen here, the title is now "Robot Framework Manual" instead of just "Manual". I hadn't used or even noticed hooks earlier, and I really like how powerful and simple they are when needing to do something a bit more special. I was also happy to get a good answer from the community so quickly.

Based on the code for setting the og:title metatag you showed, it's clear that different behavior on the home page compared to other pages is on purpose. However, my experience from software development is that even when something is done on purpose, it could be a bug rather than a feature. 😃

In this particular case I understand the idea to use a different title format on the home page and on other pages, but in my opinion the home page title should be config.site_name instead of just the page title. In other words, I'd replace the current

# Compute page title 
title = page.meta.get("title", page.title) 
if not page.is_homepage: 
    title = f"{title} - {config.site_name}" 

with

# Compute page title 
title = config.site_name
if not page.is_homepage: 
    page_title = page.meta.get("title", page.title) 
    title = f"{page_title} - {title}" 

Anyway, @squidfunk or whoever wrote the current code may have good reasons for that exact behavior. And for me being able to override the title with hooks is definitely enough.

[pekkaklarck]

I can create a PR. Some questions:

• I noticed that the repo has material/plugins/social/plugin.py and src/plugins/social/plugin.py with identical content. Which one am I supposed to edit? Didn't notice anything about that in CONTRIBUTING.md. This was explained in customization.md.
• Does a change like this need a test? If yes, where can I read more about creating them for this project?
• Should I submit an issue about the problem or is a PR enough?

[squidfunk]

It's all answered in our documentation. And no, you do not create an issue or test – we currently don't have the latter, but this will change soon.

[pekkaklarck]

I didn't actually see anything about the content in the material directory being generated based on the src directory in https://squidfunk.github.io/mkdocs-material/contributing/making-a-pull-request/, but it was explained in https://squidfunk.github.io/mkdocs-material/customization/#environment-setup that's linked from the first page.

I made changes only to src/plugins/social/plugin.py, as instructed, and then npm run build copied them to material/plugins/social/plugin.py. Should include changes to both of these files in the PR or should it contain only the src changes?

I have also the following two changed files in the repository after setting everything up and running npm run build. I haven't touched those myself, so I assume they shouldn't be part of the PR either.

deleted: material/overrides/assets/javascripts/iconsearch_index.json
modified: material/templates/.icons/material/LICENSE

[squidfunk]

src and material need to be included. The other changed files are likely due to a mismatch in versions of npm packages.

[pekkaklarck]

#7608