add docs for meta attribute in Code component #9054

jcayzac · 2024-08-10T00:49:51Z

Description (required)

Documentation for withastro/astro#11605

Related issues & labels (optional)

For Astro version: `4.14.0`. See astro PR 11605

First-time contributor to Astro Docs?

Discord: @jcayzac

netlify · 2024-08-10T00:50:10Z

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`84f8382`
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/66bb9ef9ce1cd80008a80cb6
😎 Deploy Preview	https://deploy-preview-9054--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-08-10T00:50:22Z

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

Our GitHub bots will run to check your changes.
If they spot any broken links you will see some error messages on this PR.
Don’t hesitate to ask any questions if you’re not sure what these mean!
In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.
One or more of our maintainers will take a look and may ask you to make changes.
We try to be responsive, but don’t worry if this takes a few days.

astrobot-houston · 2024-08-10T00:55:24Z

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	reference/api-reference.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

Thanks for submitting this along with your PR, @jcayzac !

I think we can do better than duplicating an entire huge example just to add the meta property, though. So I may decide this should just be a line in the main transformers section, and we just show one example including the meta tag. We do something similar in the config section on the Markdown page, where we just show one config example, and one of the plugins happens to have additional options passed.

I'm thinking maybe something like:

[Shiki transformers](https://shiki.style/packages/transformers#shikijs-transformers) can optionally be applied to code by passing them in through the `transformers` property as an array. Since Astro v4.14.0, you can also provide a string for [Shiki's `meta` attribute](https://shiki.style/guide/transformers#meta) to pass options to transformers.

And then update the code sample to include both transformers in the array, plus the meta option, highlighting the two lines relevant to transformers (we use Expressive Code to do that in Docs 😉)

astro title="src/pages/index.astro" {12-13}

What do you think about something like that?

src/content/docs/en/reference/api-reference.mdx

sarah11918 · 2024-08-12T11:40:11Z

Oops, I see from the original PR that you're describing meta completely independent of the transformer usage. I think I need more context about how you see this feature used, as your examples are probably showing specific use cases without painting a general picture first. (Which is why I inferred incorrectly what the option was in general).

I asked for clarification in the PR there, or you can reply here!

If meta is a standalone attribute that has use outside of transformers, then it shouldn't be explained within transformers. I'll need a more general introduction to what meta is and is used for first, and then we can show examples. This will help me figure out where the documentation goes.

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

jcayzac · 2024-08-12T11:54:12Z

I asked for clarification in the PR there,

Erika replied there.

I'm thinking maybe something like:
[Shiki transformers](https://shiki.style/packages/transformers#shikijs-transformers) can optionally be applied to code by passing them in through the `transformers` property as an array. Since Astro v4.14.0, you can also provide a string for [Shiki's `meta` attribute](https://shiki.style/guide/transformers#meta) to pass options to transformers.
And then update the code sample to include both transformers in the array, plus the meta option, highlighting the two lines relevant to transformers

LGTM!

(we use Expressive Code to do that in Docs 😉)
astro title="src/pages/index.astro" {12-13}

I did not understand that part. Expressive Code is not relevant to that documentation.

sarah11918 · 2024-08-12T12:00:28Z

Expressive Code is not a part of what we are documenting here, but it's how we have to format our code samples of your example here! I'm just pointing out that I find it coincidental that you have provided an example about line highlighting showing how to do it one way, but in order for us to actually document that, we have to use Expressive Code to do the highlighting of your example! 😄

sarah11918 · 2024-08-12T14:45:29Z

Thanks @jcayzac ! Can you please take a look over my changes and make sure they're correct? Anything else you notice or want to see different here?

src/content/docs/en/reference/api-reference.mdx

sarah11918

Approving for docs! @jcayzac , if you spot anything before this is released, feel free to return and let me know.

Otherwise, I'll consider this PR to be ready for our minor release on Thursday! Thank you for this contribution, and welcome to Team Docs! 🥳

jcayzac · 2024-08-13T00:29:16Z

src/content/docs/en/reference/api-reference.mdx

@@ -2124,7 +2124,8 @@ console.log(foo + bar) // [!code focus]
 <Code
  code={code}
  lang="js"
-  transformers={[transformerNotationFocus()]} />
+  transformers={[transformerNotationFocus(),[transformerMetaHighlight()]}


There is a bogus square bracket here.

Suggested change

transformers={[transformerNotationFocus(),[transformerMetaHighlight()]}

transformers={[transformerNotationFocus(), transformerMetaHighlight()]}

Great, thanks! Oops! We'll fix this when we decide exactly which transformer(s) we should show!

src/content/docs/en/reference/api-reference.mdx

jcayzac · 2024-08-13T00:33:31Z

src/content/docs/en/reference/api-reference.mdx

@@ -2124,7 +2124,8 @@ console.log(foo + bar) // [!code focus]
 <Code
  code={code}
  lang="js"
-  transformers={[transformerNotationFocus()]} />
+  transformers={[transformerNotationFocus(),[transformerMetaHighlight()]}


Because transformerNotationFocus blurs everything but the line marked with // [!code focus], using it together with transformerMetaHighlight makes little sense IMHO.

Or at least the highlighted line should be the same as the focused line.

OK! Shall we just delete the NotationFocus transformer then? Would also be OK if you wanted to suggest two that did go together! Just let me know.

@sarah11918 sorry it took me some time to circle back to this PR. I see it's merged now.

The example now doesn't work. I has style for a transformer that's not used, and doesn't have any style for the transformer it uses.

The fixed example is that of the original commit: 975a6e1#diff-42959260ea642887b866e8e276a4520c1f112356eb9c15b31e510132a481aed6R2147-R2165

jcayzac · 2024-08-13T00:34:01Z

Thanks @sarah11918, I commented on the issues I found.

src/content/docs/en/reference/api-reference.mdx

add docs for meta atrribute in Code component

975a6e1

github-actions bot added the i18n Anything to do with internationalization & translation efforts - ask @YanThomas for help! label Aug 10, 2024

removed fr translation

4a31ca4

github-actions bot removed the i18n Anything to do with internationalization & translation efforts - ask @YanThomas for help! label Aug 10, 2024

jcayzac changed the title ~~add docs for meta atrribute in Code component~~ add docs for meta attribute in Code component Aug 11, 2024

Princesseuh added this to the 4.14 milestone Aug 12, 2024

sarah11918 reviewed Aug 12, 2024

View reviewed changes

src/content/docs/en/reference/api-reference.mdx Outdated Show resolved Hide resolved

Update src/content/docs/en/reference/api-reference.mdx

74258ec

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

bluwy mentioned this pull request Aug 12, 2024

fix: code component was missing support for meta string withastro/astro#11605

Merged

combine in transformers section

bc09fbc

sarah11918 reviewed Aug 12, 2024

View reviewed changes

src/content/docs/en/reference/api-reference.mdx Outdated Show resolved Hide resolved

update import statement

57dee44

sarah11918 approved these changes Aug 12, 2024

View reviewed changes

sarah11918 added the Merge Queue Approved and ready to be merged (wait for feature release if also labelled M-O-R)! label Aug 12, 2024

jcayzac commented Aug 13, 2024

View reviewed changes

src/content/docs/en/reference/api-reference.mdx Show resolved Hide resolved

jcayzac commented Aug 13, 2024

View reviewed changes

sarah11918 reviewed Aug 13, 2024

View reviewed changes

src/content/docs/en/reference/api-reference.mdx Outdated Show resolved Hide resolved

only one transformer

d555d82

Merge branch 'main' into fix/code-meta

84f8382

sarah11918 changed the base branch from main to 4.14.0 August 13, 2024 17:59

sarah11918 mentioned this pull request Aug 14, 2024

4.14.0 Minor Release Docs #9081

Merged

Merge branch '4.14.0' into fix/code-meta

76fcc03

sarah11918 merged commit 94753c2 into withastro:4.14.0 Aug 14, 2024
1 check passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add docs for meta attribute in Code component #9054

add docs for meta attribute in Code component #9054

jcayzac commented Aug 10, 2024

netlify bot commented Aug 10, 2024 •

edited

Loading

astrobot-houston commented Aug 10, 2024

astrobot-houston commented Aug 10, 2024 •

edited

Loading

sarah11918 left a comment

sarah11918 commented Aug 12, 2024

jcayzac commented Aug 12, 2024 •

edited

Loading

sarah11918 commented Aug 12, 2024

sarah11918 commented Aug 12, 2024

sarah11918 left a comment

jcayzac Aug 13, 2024

sarah11918 Aug 13, 2024

jcayzac Aug 13, 2024

sarah11918 Aug 13, 2024

jcayzac Aug 15, 2024

jcayzac commented Aug 13, 2024

	transformers={[transformerNotationFocus(),[transformerMetaHighlight()]}
	transformers={[transformerNotationFocus(), transformerMetaHighlight()]}

add docs for meta attribute in Code component #9054

add docs for meta attribute in Code component #9054

Conversation

jcayzac commented Aug 10, 2024

Description (required)

Related issues & labels (optional)

For Astro version: 4.14.0. See astro PR 11605

First-time contributor to Astro Docs?

netlify bot commented Aug 10, 2024 • edited Loading

✅ Deploy Preview for astro-docs-2 ready!

astrobot-houston commented Aug 10, 2024

astrobot-houston commented Aug 10, 2024 • edited Loading

Lunaria Status Overview

Tracked Files

sarah11918 left a comment

Choose a reason for hiding this comment

sarah11918 commented Aug 12, 2024

jcayzac commented Aug 12, 2024 • edited Loading

sarah11918 commented Aug 12, 2024

sarah11918 commented Aug 12, 2024

sarah11918 left a comment

Choose a reason for hiding this comment

jcayzac Aug 13, 2024

Choose a reason for hiding this comment

sarah11918 Aug 13, 2024

Choose a reason for hiding this comment

jcayzac Aug 13, 2024

Choose a reason for hiding this comment

sarah11918 Aug 13, 2024

Choose a reason for hiding this comment

jcayzac Aug 15, 2024

Choose a reason for hiding this comment

jcayzac commented Aug 13, 2024

For Astro version: `4.14.0`. See astro PR 11605

netlify bot commented Aug 10, 2024 •

edited

Loading

astrobot-houston commented Aug 10, 2024 •

edited

Loading

jcayzac commented Aug 12, 2024 •

edited

Loading