Meta Tags, OpenGraph and Twitter Cards

shaedrich commented 3 months ago

Fixes #546

netlify[bot] commented 3 months ago

Deploy Preview for pony-tutorial ready!

Name	Link
Latest commit	80259c2ec9f2a917c554ea392e0e21464e334707
Latest deploy log	https://app.netlify.com/sites/pony-tutorial/deploys/665fc94a4ee772000785ad46
Deploy Preview	https://deploy-preview-548--pony-tutorial.netlify.app
Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

shaedrich commented 3 months ago

Result: 😍 grafik

SeanTAllen commented 3 months ago

One of my favorite things about when we moved from the Hugo theme I did that supported meta tags and twitter cards was that we didn't have to try to come up with descriptions for every page. It was a slog in some cases.

We will discuss at sync and perhaps other maintainers will see the value. I personally have been down the road of this already with our old setup and I didn't see the value in it. It was just extra work, extra stuff to maintain so I'm not in favor, but others might be.

Will update further after our next sync call.

Thanks for opening this PR Sebastian. Your commitment to improving the tutorial has been impressive and inspiring to watch as the updates flow into my inbox.

shaedrich commented 3 months ago

One of my favorite things about when we moved from the Hugo theme I did that supported meta tags and twitter cards was that we didn't have to try to come up with descriptions for every page. It was a slog in some cases.

You unfortunaly see it from a slightly "wrong" angle. I totally see, that you don't want to write these descriptions. But I wouldn't call a SSG engine "better" when it is lacking a fairly standard feature, just because I personally don't like the work that goes into it and I, unlike many other people, don't use that feature.

Sorry if I'm out of line here.

SeanTAllen commented 3 months ago

Can the title come from the H1 in the page? Having in metadata, it could get out of sync.

shaedrich commented 3 months ago

Can the title come from the H1 in the page? Having in metadata, it could get out of sync.

It could. However, as you see, this works fine on page but less so more often than not taken out of context as it will be when sent as a link.

SeanTAllen commented 3 months ago

It could. However, as you see, this works fine on page but less so more often than not taken out of context as it will be when sent as a link.

Can it come from the existing breadcrumb stuff in mkdocs?

jemc commented 3 months ago

I'm in agreement with @SeanTAllen on this point.

I admit that having page-specific information in the Card can be useful for someone glancing quickly card but it's a fairly small amount of value and I don't think it outweighs the maintenance effort being added.

Here are my concrete set of concerns:

the problem of drift between in the title in the metadata vs the title in the H1
the problem of drift between chapter title in the metadata vs the actual title of the containing chapter
the problem where all these meta fields are hidden during normal browsing, and someone may not notice that they need to update them when only looking at the static site in the netlify preview.
the description copy, being hidden may not get as much attention as it perhaps should during maintenance

Some alternative ideas discussed in sync:

try to pull the title info from the H1 and the chapter title, instead of duplicating that info
use a generic description for the entire tutorial, or perhaps a per-chapter description as a compromise.

shaedrich commented 3 months ago

Maybe, I didn't explain my concerns in a reasonable way: For example: Do you know how many pages named "Overview" we have? Quite a few, actually. This raises the question: Overview of what? So, this gives the user essentially nothing. Does that make it a little clearer?

It could. However, as you see, this works fine on page but less so more often than not taken out of context as it will be when sent as a link.

Can it come from the existing breadcrumb stuff in mkdocs?

@SeanTAllen Sounds good 👍🏻 I made the necessary changes

perhaps a per-chapter description as a compromise

@jemc This isn't really a compromise. This essentially has the same problem as a generic description for the entire tutorial. It doesn't say what's on the page. I wouldn't go as far as saying that this way we lie to the user but we get close to it by not telling them where the link actually leads to and instead claim, the entire chapter was just one page.

And as you were worried about Google/SEO: I'm not entirely sure how Google actually determines that but multiple pages with the same description could be seen as "duplicate content", which that would have a negative impact on the SEO.

shaedrich commented 2 months ago

See https://github.com/ponylang/pony-tutorial/issues/546#issuecomment-2189685936

ponylang / pony-tutorial