Skip to content

Tutorial custom page title #12012

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

HiDeoo
Copy link
Member

@HiDeoo HiDeoo commented Jul 10, 2025

Description (required)

Worked on during today's Talking & Doc'ing, this PR addresses an issue where some pages could end up having the same title, which is not ideal for SEO and user experience.

This PR updates the titles of all the tutorial pages to be automatically prefixed by a translatable UI string (tutorial.title.prefix) using a route data middleware.

Tutorial pages can still manually specify their titles for cases where the automatic prefix is not desired using the head frontmatter property.

---
type: tutorial
unitTitle: Something
title: Page title
head:
  - tag: title
    content: Custom title | Docs
---

Related issues & labels (optional)

Copy link

netlify bot commented Jul 10, 2025

Deploy Preview for astro-docs-2 ready!

Name Link
🔨 Latest commit 18ba003
🔍 Latest deploy log https://app.netlify.com/projects/astro-docs-2/deploys/686ff02bf2b9be0008515543
😎 Deploy Preview https://deploy-preview-12012--astro-docs-2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

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

@astrobot-houston
Copy link
Contributor

astrobot-houston commented Jul 10, 2025

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File Note
en/tutorial/0-introduction/index.mdx Source changed, localizations will be marked as outdated.
en/tutorial/1-setup/index.mdx Source changed, localizations will be marked as outdated.
en/tutorial/2-pages/index.mdx Source changed, localizations will be marked as outdated.
en/tutorial/3-components/index.mdx Source changed, localizations will be marked as outdated.
en/tutorial/4-layouts/index.mdx Source changed, localizations will be marked as outdated.
en/tutorial/5-astro-api/index.mdx Source changed, localizations will be marked as outdated.
en/tutorial/6-islands/4.mdx Source changed, localizations will be marked as outdated.
en/tutorial/6-islands/index.mdx Source changed, localizations will be marked as outdated.
src/content/i18n/en.yml Source changed, localizations will be marked as outdated.
src/content/i18n/fr.yml Localization changed, will be marked as complete.
Warnings reference
Icon Description
🔄️ The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

@anaxite
Copy link
Contributor

anaxite commented Jul 10, 2025

Came here from Talking & Doc'ing.

Quick summary of thoughts:

  • I find that greather-than symbols really work for breadcrumbs.
  • Colons or brackets in titles? Either work, but I found that colons are nice.

@sarah11918
Copy link
Member

Strong preference for colons! 😅

Comment on lines +11 to +13
head:
- tag: title
content: 'Build a blog tutorial: Unit 1 - Setup | Docs'
Copy link
Member

@sarah11918 sarah11918 Jul 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a quick note that we want this done for all six of the tutorial units (The check in page only) to match this format! (Remove "Check in:" and replace it with "Build a blog tutorial:")

If you're reading this PR, you could be contributing those changes!

@HiDeoo
Copy link
Member Author

HiDeoo commented Jul 10, 2025

Updated the PR and its description to reflect everything we talked about during T&D.

Something coming to mind is that once we're happy with the English version, I wonder if it could be worth to not immediately merge this PR, but instead ping translators to potentially translate the new UI string/titles in as many languages as possible before merging so search engines cannot end up indexing pages with an updated tutorial page title without a translated prefix? (I guess another possibility could also to tweak the code so that the automatic prefixing is applied only if the new UI string is available in the content language?)

Any thoughts on that?

@HiDeoo HiDeoo marked this pull request as ready for review July 10, 2025 15:10
@HiDeoo HiDeoo added the site improvement Some thing that improves the website functionality - ask @delucis for help! label Jul 10, 2025
@delucis
Copy link
Member

delucis commented Jul 10, 2025

another possibility could also to tweak the code so that the automatic prefixing is applied only if the new UI string is available in the content language?

That’s not a bad idea I’d say. We can use t.exists() for that right?

I think that’s preferable and then each language can translate in their own time.

@sarah11918
Copy link
Member

That idea sounds good! Was also thinking that in the worst case, for the tutorials that are already translated, we should have "Build a blog tutorial" in their language somewhere, and could add that in ourselves for the general case update.

But obviously prefer to let the translators in on the fun, and the solution that allows them to contribute as they are able seems ideal!

@sarah11918
Copy link
Member

Verified all the new page (tab) titles in Chrome are correct for English, and working as expected in French (e.g. Build a blog tutorial: Embarquement: Unité 1 - Configuration | Docs)

@github-actions github-actions bot added the i18n Anything to do with internationalization & translation efforts - ask @YanThomas for help! label Jul 10, 2025
@HiDeoo
Copy link
Member Author

HiDeoo commented Jul 10, 2025

Perfect, updated the PR to include this new logic. I also added a quick French translation for the prefix, so we can test it out.

I'll note that this is the first translation that came to mind, so either we should remove it once we're done testing, or we should spend more than 5 seconds thinking about it and see what would be the best as a page title prefix for the tutorial in French (cc @ArmandPhilippot).

Copy link
Member

@ArmandPhilippot ArmandPhilippot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked the tutorial both in English and French (and somes pages in Spanish to see the difference) and this looks great! Good job 🙌🏽

@@ -51,6 +51,7 @@ progress.done: Terminer
# Tutorial Navigation
tutorial.trackerLabel: Suivi du tutoriel
tutorial.unit: Unité
tutorial.title.prefix: "Tutoriel de création d'un blog : {{title}}"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The only alternative that comes to my mind - if we want to shorten it - would be Tutoriel Créer un blog. But without quotes around the tutorial title (ie. Créer un blog) it feels a bit odd.
So, I think your translation is just fine!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't the English one the same? Build a blog tutorial and "Build a blog" tutorial.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know how it sounds for native English speakers while it sounds okay to me. However, in French I don't have the same feeling... maybe because of the words order...
I would write it Tutoriel « Créer un blog » : (capital letter for tutoriel because this is the beginning of the title, and for créer because we're quoting another title). Using French quotes seems odd in a <title> tag. I think HiDeoo's translation is more appropriate.

But that's only my opinion! So, I left this comment in case I was overthinking and that HiDeoo (or anaxite which is French too I believe?) had a different opinion on the matter! 😄

@sarah11918
Copy link
Member

sarah11918 commented Jul 11, 2025

OK, so noting that now:

  • English (canonical) ✅
  • French (a translated tutorial that does have a value for tutorial.title.prefix) ✅
  • German, Arabic etc: (a non-translated tutorial that does not have a value for tutorial.title.prefix) ✅ (these are completely English)
  • Brazilian Portuguese, Russian etc: (a translated tutorial that does NOT have a value for tutorial.title.prefix) ❌
Screenshot 2025-07-11 08 49 22 These appear to be missing the new prefix entirely

@HiDeoo
Copy link
Member Author

HiDeoo commented Jul 11, 2025

Thanks for testing, if I'm not missing anything, this matches our latest requirements.

To give more details about the last point, this is expected to avoid a search engine temporarily indexing something like Build a blog tutorial: Sobre este Tutorial | Docs, so the current title Sobre este Tutorial | Docs will be used until a translated prefix is available.

@sarah11918
Copy link
Member

Gotcha! Then, looks like all is working as expected. Amazing job!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
i18n Anything to do with internationalization & translation efforts - ask @YanThomas for help! site improvement Some thing that improves the website functionality - ask @delucis for help!
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants