Layouts page rewrite by sarah11918 · Pull Request #9335 · withastro/docs

sarah11918 · 2024-09-07T13:31:57Z

Description (required)

This lightly updates the /basics/layouts.mdx guide page to:

Prepare for a rewrite of the existing Markdown page that will hold more of the Markdown-specific content (e.g. the removed code example of exported properties) so that the Layout page is less cluttered and mostly focused on the pattern
Simplify by downplaying MDX and concentrating on Markdown (our built-in, first class citizen) (as the new Markdown page will, moving some content directly to the MDX page)

The only content temporarily lost in published docs as a result of this is the code example, but a version of that will exist in the new Markdown page, where it is more helpful and discoverable.

netlify · 2024-09-07T13:32:15Z

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	`7280072`
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/66dc66849f14b600085b77c9
😎 Deploy Preview	https://deploy-preview-9335--astro-docs-2.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.

astrobot-houston · 2024-09-07T13:35:06Z

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

Locale	File	Note
en	basics/layouts.mdx	Source changed, localizations will be marked as outdated.

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.

sarah11918 · 2024-09-07T13:47:48Z

-  </body>
-</html>
-```
+<ReadMore>Learn more about Astro’s Markdown and MDX support in our [Markdown guide](/en/guides/markdown-content/).</ReadMore>


Just noting that it's an intentional choice to leave "and MDX" in here because this section only is about MDX. And, the Markdown guide is a good place to read about general Markdown (in MDX) stuff.

sarah11918 · 2024-09-07T13:48:28Z

-
 <ReadMore>Learn more about [slots](/en/basics/astro-components/#slots).</ReadMore>

+## Using TypeScript with layouts


Just noting that I moved this up for prominence, and to push the Markdown layout content (more niche/specific use case) lower on the page.

sarah11918 · 2024-09-07T13:49:30Z

 ### Importing Layouts Manually (MDX)

-You may need to pass information to your MDX layout that does not (or cannot) exist in your frontmatter. In this case, you can instead import and use a [`<Layout />` component](/en/basics/layouts/) and pass it props like any other component:
+You can also use the special Markdown layout property in the frontmatter of MDX files to pass `frontmatter` and `headings` props directly to a specified layout component in the same way. 


Just noting that this is basically what you get when you use the layout property in MDX files, so rather than complicate the list above, I intentionally made the entire thing above about Markdown, in favour of a streamlined sentence here.

at-the-vr

Sending in couple of title suggestions 😄

ArmandPhilippot

I have nothing to say with your changes (except a typo in a code block). Looks good to me!

Some additional feedback about the page structure:

Moving the Typescript section outside of the Markdown layouts seems more consistent to me (this has nothing to do with Markdown). So I approve!
I wonder if "Nesting Layouts" should not be between "Using TypeScript with layouts" and "Markdown Layout". Like you said, Markdown Layout are "more niche/specific use case" so I think this section should be the last... Especially if we want to encourage people to use content collections when possible... That said, my opinion may be biased. 😅

I also added other suggestions on portions you did not modify. This is mostly nitpicking!

Co-authored-by: Armand Philippot <git@armand.philippot.eu> Co-authored-by: Atharva <atharvapise19@gmail.com>

sarah11918 · 2024-09-07T14:45:31Z

I wonder if "Nesting Layouts" should not be between "Using TypeScript with layouts" and "Markdown Layout".

I did think about this, and debate it. BUT, I ended up thinking that it was more useful after showing Markdown layouts, because that's actually the exact pattern we were intending to show: having a Markdown layout wrapped in your regular BaseLayout. So, I think the stronger argument is to show it after we've shown BlogPostLayout(Layout) so that the use case for it has already been made.

And, you should see the changes coming to the Markdown page... it's really going to be encouraging collections! 😄

sarah11918 · 2024-09-07T14:46:27Z

Thank you both for your reviews @ArmandPhilippot and @at-the-vr ! I really appreciate getting feedback on a quiet Saturday so I can keep on trucking.... 🚚

sarah11918

Why did I make a review instead of comment? Have to finish this off.

ArmandPhilippot · 2024-09-07T14:50:05Z

that's actually the exact pattern we were intending to show: having a Markdown layout wrapped in your regular BaseLayout.

Oh yes, I hadn't paid attention to the example in "Nesting Layouts"... the order is therefore consistent.

Signed-off-by: Thomas Bonnet <thomasbnt@protonmail.com>

* i18n(fr): Update `basics/layouts` from #9335 Signed-off-by: Thomas Bonnet <thomasbnt@protonmail.com> * i18n(fr): Update `basics/layouts` from #9344 Signed-off-by: Thomas Bonnet <thomasbnt@protonmail.com> * Update src/content/docs/fr/basics/layouts.mdx Co-authored-by: Armand Philippot <git@armand.philippot.eu> * Update src/content/docs/fr/basics/layouts.mdx Co-authored-by: Armand Philippot <git@armand.philippot.eu> * Nesting Layouts part Signed-off-by: Thomas Bonnet <thomasbnt@protonmail.com> * Update src/content/docs/fr/basics/layouts.mdx Co-authored-by: Armand Philippot <git@armand.philippot.eu> --------- Signed-off-by: Thomas Bonnet <thomasbnt@protonmail.com> Co-authored-by: Armand Philippot <git@armand.philippot.eu> Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com>

Layouts page rewrite

5fcdf1d

sarah11918 commented Sep 7, 2024

View reviewed changes

Comment thread src/content/docs/en/basics/layouts.mdx Outdated

avoid dupe language

59672c3

sarah11918 commented Sep 7, 2024

View reviewed changes

at-the-vr reviewed Sep 7, 2024

View reviewed changes

Comment thread src/content/docs/en/basics/layouts.mdx Outdated

Comment thread src/content/docs/en/basics/layouts.mdx Outdated

ArmandPhilippot reviewed Sep 7, 2024

View reviewed changes

Apply suggestions from code review

7280072

Co-authored-by: Armand Philippot <git@armand.philippot.eu> Co-authored-by: Atharva <atharvapise19@gmail.com>

sarah11918 commented Sep 7, 2024

View reviewed changes

Comment thread src/content/docs/en/basics/layouts.mdx Outdated

sarah11918 merged commit 1096370 into main Sep 7, 2024

sarah11918 deleted the layouts-revamp branch September 7, 2024 14:50

jsparkdev mentioned this pull request Sep 8, 2024

i18n(ko-KR): update layouts.mdx #9340

Merged

vrabe mentioned this pull request Sep 9, 2024

i18n(zh-tw): update basics/layouts.mdx #9364

Merged

thomasbnt added a commit to thomasbnt/docs that referenced this pull request Sep 9, 2024

i18n(fr): Update basics/layouts from withastro#9335

65b0a1b

Signed-off-by: Thomas Bonnet <thomasbnt@protonmail.com>

thomasbnt mentioned this pull request Sep 9, 2024

i18n(fr): Update basics/layouts from #9335 #9368

Merged

Nin3lee mentioned this pull request Sep 12, 2024

i18n(zh-cn): Update layouts.mdx & markdown-content.mdx & referenced links #9381

Merged

trueberryless mentioned this pull request Nov 15, 2024

i18n(de): recreate basics/layout.mdx #10034

Merged


		<ReadMore>Learn more about [slots](/en/basics/astro-components/#slots).</ReadMore>

		## Using TypeScript with layouts

Uh oh!

Conversation

sarah11918 commented Sep 7, 2024

Description (required)

Uh oh!

netlify Bot commented Sep 7, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-docs-2 ready!

Uh oh!

astrobot-houston commented Sep 7, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

Uh oh!

sarah11918 Sep 7, 2024

Choose a reason for hiding this comment

Uh oh!

sarah11918 Sep 7, 2024

Choose a reason for hiding this comment

Uh oh!

sarah11918 Sep 7, 2024

Choose a reason for hiding this comment

Uh oh!

at-the-vr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ArmandPhilippot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sarah11918 commented Sep 7, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sarah11918 commented Sep 7, 2024

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ArmandPhilippot commented Sep 7, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

netlify Bot commented Sep 7, 2024 •

edited

Loading

astrobot-houston commented Sep 7, 2024 •

edited

Loading

sarah11918 commented Sep 7, 2024 •

edited

Loading

ArmandPhilippot commented Sep 7, 2024 •

edited

Loading