Styling part for the layout section of blog tutorial is a little bit confusing

devserkan commented 1 week ago

📚 Subject area/topic

Layouts section in Blog tutorial

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/tutorial/4-layouts/1/

📋 Description of content that is out-of-date or incorrect

In the documentation, when giving the instructions for the about.astro page refactor, it says:

(Note: using the BaseLayout to render your about.astro page means you will lose the <style> tag added to the <head> of this page. If you want to keep the custom <h1> style, move the style tag to the body of the page component.)

Even if we do this, the h1 styles are not applied to the page because we are not using h1 in about.astro, so the BaseLayouts styles are applied. I guess this is the default behaviour but in this case the documentation might be confusing for learners. So, maybe there should be a reminder about this is the default behaviour and either we use the element itself in the page or we do not see the styles are applied.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

https://stackblitz.com/github/withastro/blog-tutorial-demo/tree/complete

at-the-vr commented 5 days ago

Hey Devserkan 👋 there is a bullet point stating what you asked for. If this is not what you asked for, feel free to share your thoughts here 😉

devserkan commented 5 days ago

Hey there.

This is the thing. Even if you move the styles it does not work if the styled element does not exist in the page. Let me clarify the scenario.

You have a section which includes h1 tag in your page. Now, you refactored this section to a layout. The h1 is in this layout now. Even if you have styles for h1 it does not apply because h1 does not exist in the page.

In the documentation, this is not clear and even if we do what is told there, it does not work. You can check the official demo app i provided above. The style is there but it is now working.

sarah11918 commented 3 days ago

Yes, I believe we had this conversation in Discord! Thank you for filing this issue to help me remember and track, and I know exactly what you're referring to!

I'm thinking the place to update would be here: https://docs.astro.build/en/tutorial/4-layouts/1/#try-it-yourself---use-your-layout-everywhere

It currently says:

What about a change something like:

Refactor your other pages (blog.astro and about.astro) so that they use your new <BaseLayout> component to render the common page elements. 

Don't forget to...
(that whole list)

:::note[Keeping About page styles]
Using the `<BaseLayout>` to render your `about.astro` page means you will lose the `<style>` tag added to the `<head>` of this page. To continue to style items only at the page level using Astro's scoped styling, move the `<style>`  tag to the body of the page component. This allows you to style **elements created in this page component** (e.g. your list of skills).  Since your <h1> is now created by your layout component, you can add the `is:global` attribute to your style tag to affect every element on this page, including those created by other components: `<style is:global define:vars={{ skillColor, fontWeight, textCase }}>`
:::

(easier to read version)

This keeps the instructions to refactor and the list of things to remember cleaner, and easier to read. Then, calls out specifically what's going on in the About page without cluttering the stuff above?

devserkan commented 2 days ago

This looks perfect. At least now we know that if we don’t add is:global, it won’t take effect. If we want it to apply, this seems to be one way (I assume) to make it work.

Thanks.

sarah11918 commented 1 day ago

Great! Would you like to make the PR yourself @devserkan ? If not, no worries! I'll add the help wanted tag here and anyone is welcome to pick this up and contribute!

withastro / docs