External previews of Docusaurus links are inconsistent #3024

markerikson · 2020-07-06T01:18:53Z

🐛 Bug Report

I recently updated the Redux Toolkit docs to alpha.58 . The Redux core is still on alpha.54, while React-Redux is still on DSv1.

Somewhere between alpha.54 and alpha.58, something about the generated logos / preview images changed, such that when I paste links to the different docs into Discord, I get very differently-sized link previews:

Why are the logos sized so differently, and what recently changed to cause this?

Have you read the Contributing Guidelines on issues?

Yes

To Reproduce

Paste links to differing versions of the Redux docs into Discord or similar

Expected behavior

The Redux logo would be smaller, and consistently sized across DS alpha versions.

Actual Behavior

(Write what happened. Add screenshots, if applicable.)

Your Environment

Redux core: alpha.54
RTK: alpha.58

Reproducible Demo

Paste these links as of today:

slorber · 2020-07-06T09:57:44Z

I also notice there is a difference.

The best way is to compare the same site/page with 2 deployments:

https://redux-toolkit.js.org/introduction/quick-start
https://deploy-preview-310--redux-starter-kit-docs.netlify.app/introduction/quick-start (older deploy preview I found from Jan 2020, probably D2 54 alpha?)

Seems it could be related to this change: #2436

Anyway, @markerikson I don't think it's a bug, we don't currently specify what the preview should look like, nor guarantee that it should be consistent over time, particularly as we are still in alpha. Having a preference for a smaller version is likely subjective, and the whole D2 userbase would maybe not agree with you here.

Note that we're also working on better social cards: #2968
Upgrading to future versions of D2 might soon give you another kind of social preview.
It might not be exactly what you want, but you should be able able to customize it anyway.

If you have a specific html metadata requirements, and absolutely need an option to enforce these metadatas, we are open to discuss that.

markerikson · 2020-07-06T13:38:41Z

Yeah, that seems like it's likely responsible. Obviously DS itself isn't responsible for how Discord itself displays and formats previews, but it does seem like something about DS's generation is influencing that output.

Ideally, I'd like to see something more similar to how it's looking with the React-Redux site (DSv1): a small image, so that the logo isn't a distraction. I think that's how it was showing up previously, and I'm actually not sure why there's no logo preview for the Redux core link there atm either.

slorber · 2020-07-09T17:07:28Z

We could provide options to influence on the page metadata options, but it will be hard to satisfy perfectly all users in this regard, and handle all existing services saas services reading those metadatas

We don't know exactly the metadatas you need, unless you know exactly what you want and can tell us ;)

If some users want to enforce some metadatas, it's possible to swizzle the components. No need to copy everything.
For example, wrap an existing doc item page and add some meta to override the default ones of the layout:

import OriginalDocItem from "@theme-original/DocItem";
import Head from "@docusaurus/Head";

export default function CustomDocItem(props) {
  return (
    <>
      <Head>
        <meta name="twitter:card" content="summary" />
      </Head>
      <OriginalDocItem {...props} />
    </>
  );
}

@theme-original/DocItem is a special import to enable a comp to wrap itself. It's not documented yet afaik, will need to add that.

markerikson · 2020-09-03T00:56:02Z

Saw an example of this again this evening:

I decided to compare the header tags for Redux, which is on DS v2.alpha-54, and React-Redux, which is still on DS v1:

Tag	Redux	React-Redux
og:image	https://redux.js.org/img/redux-logo-landscape.png	https://react-redux.js.org/img/redux-logo-landscape.png
twitter:image	https://redux.js.org/img/redux-logo-landscape.png	https://react-redux.js.org/img/redux-logo-twitter.png
twitter:image:alt	Image for Redux
twitter:card	summary_large_image	summary
og:title	Server Rendering \| Redux
description	# Server Rendering	`<h1><svg></svg>Hooks</h1>`
og:description	# Server Rendering	`<h1><svg></svg>Hooks</h1>`
og:url	https://redux.js.org/recipes/server-rendering

This must be due to the use of summary_large_image instead of summary.

Frankly, I rather prefer having the smaller preview images - the giant ones distract from the title. Maybe that goes against SEO suggestions.

So, what's the best approach for flipping that value for our docs?

slorber · 2020-09-03T09:45:16Z

Currently this can be changed by swizzling the @theme/Layout comp and changing the header value, but if someone wants to contribute a new theme setting to that we can override the existing value, I'd be fine with that

markerikson · 2020-09-03T14:16:00Z

Since I've never tried doing the "swizzling" thing before, any pointers on how to do so?

slorber · 2020-09-04T12:54:17Z

yarn docusaurus swizzle @docusaurus/theme-classic Layout --danger

This gives you the ability to "override" any theme component (like gatsby shadowing)

We add "--danger" because we can't guarantee the classic theme code will not be upgraded (or API surface updated), and you won't benefit from such upgrades, so if you can avoid swizzle it's better.

The theme whitelist a list of components that are recommended to swizzle (no --danger needed).

I'll add the meta option in a PR because sizzling is not very convenient for such an usecase. Somehow you can compare it to a more convenient patch-package alternative.

see #3024

slorber · 2020-09-04T14:08:53Z

Next release will allow to add/override any meta header:

#3406

module.exports = {
  // ...
  themeConfig: {
    metadatas: [{name: 'twitter:card', content: 'summary'}],
    // ...
  },
};

* ability to add/override theme html metadatas see #3024 * refactor/fix validateThemeConfig tests

markerikson · 2020-09-04T19:04:42Z

Cool, thanks!

markerikson added bug An error in the Docusaurus core causing instability or issues with its execution status: needs triage This issue has not been triaged by maintainers labels Jul 6, 2020

slorber added a commit that referenced this issue Sep 4, 2020

ability to add/override theme html metadatas

1d99014

see #3024

slorber mentioned this issue Sep 4, 2020

feat(v2): ability to add/override theme html metadatas #3406

Merged

slorber closed this as completed in #3406 Sep 4, 2020

slorber added a commit that referenced this issue Sep 4, 2020

feat(v2): ability to add/override theme html metadatas (#3406)

2185294

* ability to add/override theme html metadatas see #3024 * refactor/fix validateThemeConfig tests

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

External previews of Docusaurus links are inconsistent #3024

External previews of Docusaurus links are inconsistent #3024

markerikson commented Jul 6, 2020

slorber commented Jul 6, 2020

markerikson commented Jul 6, 2020

slorber commented Jul 9, 2020 •

edited

Loading

markerikson commented Sep 3, 2020 •

edited

Loading

slorber commented Sep 3, 2020

markerikson commented Sep 3, 2020

slorber commented Sep 4, 2020

slorber commented Sep 4, 2020 •

edited

Loading

markerikson commented Sep 4, 2020

External previews of Docusaurus links are inconsistent #3024

External previews of Docusaurus links are inconsistent #3024

Comments

markerikson commented Jul 6, 2020

🐛 Bug Report

Have you read the Contributing Guidelines on issues?

To Reproduce

Expected behavior

Actual Behavior

Your Environment

Reproducible Demo

slorber commented Jul 6, 2020

markerikson commented Jul 6, 2020

slorber commented Jul 9, 2020 • edited Loading

markerikson commented Sep 3, 2020 • edited Loading

slorber commented Sep 3, 2020

markerikson commented Sep 3, 2020

slorber commented Sep 4, 2020

slorber commented Sep 4, 2020 • edited Loading

markerikson commented Sep 4, 2020

slorber commented Jul 9, 2020 •

edited

Loading

markerikson commented Sep 3, 2020 •

edited

Loading

slorber commented Sep 4, 2020 •

edited

Loading