Custom permalinks (anchors) appear on social cards

[YuriiMotov]

We use custom permalinks to ensure anchors are the same for translations of the same page for all languages:

# First Steps { #first-steps }

We just noticed that page previews generated using social cards plugin now display these permalinks:

It seems that this should be handled by plugin automatically. Or, is there an option to configure this?
I looked at docs, but the only way I found is custom layouts

Thanks you!

[squidfunk]

Thanks for asking!

Situation

The main problem this stems from is MkDocs' (our upstream dependency) title handling, which has been broken for a long time. The titles that MkDocs exposes to plugins aren't even consistent across events that are invoked, since it changes after the Markdown has been rendered. A lot of discussion has happened in the upstream repository in the past, but the issues are still unsolved:

• Header and navigation sidebars display incorrectly arbitrary markup mkdocs/mkdocs#3357
• Consider changing the precedence of title sources mkdocs/mkdocs#3532
• Mkdocs no longer respecting set display text for same .md files. mkdocs/mkdocs#3710
• Separate Navigation Title, from Page/Tags/etc. #7670

As we recently wrote in our update on our foundational work, and with close to 100 open issues, MkDocs is effectively unmaintained. However, with our foundational work circling in on an initial release, we're close to creating a new foundation to finally address the issues that have not been addressed in MkDocs.

Workaround

In the meantime, as FastAPI is on Insiders, you can work around the issue by setting the cards title explicitly. Just add the following to the metadata of a page (documentation is here):

---
social:
  cards_layout_options:
    title: First steps
---

# First steps { #first-steps }

I understand that this is not ideal, but as said, it will be resolved soon after our foundational work is out the door.

[YuriiMotov]

Thank you for quick and clear answer!

We ended up solving this with the hook:

def on_page_markdown(
    markdown: str, *, page: Page, config: MkDocsConfig, files: Files
) -> str:
    # Set matadata["social"]["cards_layout_options"]["title"] to clean title (without
    # permalink)
    title = page.title
    clean_title = title.split("{ #")[0]
    if clean_title:
        page.meta.setdefault("social", {})
        page.meta["social"].setdefault("cards_layout_options", {})
        page.meta["social"]["cards_layout_options"]["title"] = clean_title

---

There is one more thing related to social cards (not critical for us at the moment) - if there is a markdown in the page title, it's rendered as is:

# `APIRouter` class

It will be rendered as

`APIRouter` class

https://fastapi.tiangolo.com/assets/images/social/reference/apirouter.png