Options for wrapping or shrinking long text without whitespace in social cards

[joshooaj]

We use mkdocs-material-insiders for our PowerShell module documentation, and it's common to have long command names in Verb-Noun syntax where there are no spaces, there's usually a hyphen, and we use pascal case like Add-VmsLoginProviderClaim.

The doc pages for each command are titled using the command name, and that leads to social cards with truncated title strings like this:

I can see in src/plugins/social/plugin.py on line 578 that words are split on whitespace using words = re.split(r"\s+", unescape(typography.content)). Is there any merit in adding another option to configure the overflow behavior by making the regex pattern used to break text configurable? In my case I might break on "-" characters, but I could imagine others breaking on "." or "/" for example? I could see this being a fairly low-impact and specific issue for the broader user base though, and "fixing it" adding unnecessary complexity.

As I understand it, my alternatives for getting my long titles to fit properly right now include...

1. Increasing width of the layer.
2. Increasing the number of typography lines for the layer, and/or decreasing the line height, thus decreasing the font size.
3. Learning jinja and "preprocessing" my long titles by inserting a whitespace character after the dash? Maybe using zero-width whitespace characters like \u200B to "trick" the overflow behavior to wrap the line?

[squidfunk]

I'm not sure, whether you're aware of that setting (or if there's a bug), but you should be able to use the shrink setting for overflow. This should automatically adjust the font size, so it fits into one line. Example:

size: { width: 1200, height: 630 }
layers:
  - size: { width: 832, height: 310 }
    offset: { x: 62, y: 160 }
    typography:
      content: "{{ page.title }}"
      overflow: shrink
      align: start
      color: white
      line:
        amount: 3
        height: 1.25
      font:
        family: Roboto
        style: Bold

Other than that, we're currently knee-deep in foundational work, so we're only fixing bugs right now. However, you could open a feature request if the setting mentioned above doesn't lead to the desired outcome, which we can implement later.

[joshooaj]

I tried overflow: shrink but maybe it has unexpected behavior when there's no whitespace? A long title without whitespace looks to overflow the entire text to the next line leaving the first line blank, and it doesn't try to either shrink or overflow to the next line after that.

Here is an example of a card with and without a space, followed by the title layer. If you consider this behavior a bug, I'm happy to open an issue on it and make a PR if I think of a good way to handle it.

Without space

A blank line is rendered, followed by the entire text on the second line. There's some shrinkage but the text still doesn't fit on one line and isn't shrunk to fit.

With space

As long as there's enough whitespace to break text before it overflows the container, shrink seems to work great.

Short title

And here's how a short title is rendered for comparison.

Title layer from layout

  - size: { width: 1150, height: 250 }
    offset: { x: 25, y: 190 }
    typography:
      content: *page_title
      overflow: shrink
      color: *color
      line:
        amount: 1
        height: 1
      font:
        family: Noto Sans
        variant: *font_variant
        style: Regular

[squidfunk]

Thanks for providing more details. So, if you change the separator in the plugins source (in the material folder) to also split at other characters like - or /, does that solve your problem? Note that we would need to provide lookahead, and probably tie the character to the left, so "Foo-Bar" splits as "Foo-" and "Bar". If that works, we could consider making the regular expression configurable as a plugin setting. Although, further testing might be required.

[joshooaj]

I haven't had a chance to try changing the plugin source - I'll tinker with it later tonight and see what I can come up with!

[squidfunk]

On a further note, you can always override the title and set it specifically for the social card – there will always be cases where this will yield better results than the heuristics the social plugin tries to employ when computing the title:

---
social:
  cards_layout_options:
    title: A shorter title that looks better on the social card
---

# ALongTitleWithoutSpaceThatDoesNotRenderWellOnASocialCad

[joshooaj]

That's a good idea - there are hundreds of command pages that are auto-generated and I'm thinking it might be easiest to make a build step that adds a custom title to the front matter based on the length of the command name. I'll still look into the overflow: shrink behavior though. It seems like it should keep adding lines (and shrinking text) until a long unbroken string of text fits on the first line.