fix: add reactive theme content

[kieranwv]

Description (required)

In shiki's configuration, I set experimentalThemes: { } as documented, but it doesn't work when I dynamically switch dark mode and light mode.

Then I checked the official documentation of shiki and found that I need to manually set some css fragments to get reactive dark mode.

I replaced the .shiki class name with .astro-code and added the code to my documentation project and now it works fine.

I added this usage to the document, hoping to help developers who are unfamiliar with shiki. 😀

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
docs	✅ Ready (Inspect)	Visit Preview	May 6, 2024 11:58am

[astrobot-houston]

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

Here’s what will happen next:

1. 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!

2. In a few minutes, you’ll be able to see a preview of your changes on Vercel 🥳

3. 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.

[Eveeifyeve]

!coauthor

[github-actions]

Co-authored-by: Houston (Bot) <[email protected]>
Co-authored-by: Eveeifyeve <[email protected]>

[sarah11918]

Hi @kaivanwong ! This looks really cool!

We did just update our Shiki config though, and now instead of experimentalThemes it's just themes. Would you mind testing and make sure this still works with themes?

(See the updated, live docs now: https://docs.astro.build/en/guides/markdown-content/#shiki-configuration )

I will also ask @delucis to review, but we are a bit busy with launch week, so thank you for your patience as we catch up! 😄

[kieranwv]

Hi @kaivanwong ! This looks really cool!

We did just update our Shiki config though, and now instead of experimentalThemes it's just themes. Would you mind testing and make sure this still works with themes?

(See the updated, live docs now: docs.astro.build/en/guides/markdown-content/#shiki-configuration )

I will also ask @delucis to review, but we are a bit busy with launch week, so thank you for your patience as we catch up! 😄

Sure, I tested themes and it work normaly, thank you.

Also, it will be great if the experimental field names stay as the same. If I upgrade the version of Astro, I don't need to change my code. 😁

[Eveeifyeve]

Hi @kaivanwong ! This looks really cool!

We did just update our Shiki config though, and now instead of experimentalThemes it's just themes. Would you mind testing and make sure this still works with themes?

(See the updated, live docs now: https://docs.astro.build/en/guides/markdown-content/#shiki-configuration )

I will also ask @delucis to review, but we are a bit busy with launch week, so thank you for your patience as we catch up! 😄

Yeah I thought this LGTM Since I would use this feature as well.

[sarah11918]

Hi @kaivanwong ! We're all catching up now after a busy launch week, and I just noticed the second file changed in this PR, too.

Can you please remove the zh file in this PR? When content changes are proposed to the English site, the PR should contain only a change to the English file, which is treated as the source file for our i18n tracking system.

Only after the English is reviewed, edited, and approved do we consider changes ready for translation. Even small changes to the English site are often revised before publishing, so we ask that you not worry about submitting a translation at the same time, to save you time, and because we have a system for translations already! 🙌

[kieranwv]

Hi @kaivanwong ! We're all catching up now after a busy launch week, and I just noticed the second file changed in this PR, too.

Can you please remove the zh file in this PR? When content changes are proposed to the English site, the PR should contain only a change to the English file, which is treated as the source file for our i18n tracking system.

Only after the English is reviewed, edited, and approved do we consider changes ready for translation. Even small changes to the English site are often revised before publishing, so we ask that you not worry about submitting a translation at the same time, to save you time, and because we have a system for translations already! 🙌

ok, it doesn't matter, I've seen a major update happening to Astro recently. Now, I droped the commit for the zh file.

[sarah11918]

Hi @kaivanwong , thank you for your patience while we discussed this proposed change internally!

We are glad you added the extra information about the astro-code class, and think that's really helpful to have here. We have decided that the exact implementation should be left to Shiki's own docs, since they do have this example there and will keep it updated and maintained. We try whenever possible not to document anything that might change without us knowing if it already exists somewhere else and we can just link to it.

I think adding just a note, and not the specific implementation, calls more attention to Astro's class name, which is really the key idea to get across!

So see what you think of this suggestion!

[sarah11918]

Suggested change

	#### Light and Dark Mode
	To make it reactive to your site's theme, you need to add a short CSS snippet:
	```css title="Query-based Dark Mode"
	@media (prefers-color-scheme: dark) {
	.astro-code,
	.astro-code span {
	color: var(--shiki-dark) !important;
	background-color: var(--shiki-dark-bg) !important;
	/* Optional, if you also want font styles */
	font-style: var(--shiki-dark-font-style) !important;
	font-weight: var(--shiki-dark-font-weight) !important;
	text-decoration: var(--shiki-dark-text-decoration) !important;
	}
	}
	```
	```css title="Class-based Dark Mode"
	html.dark .astro-code,
	html.dark .astro-code span {
	color: var(--shiki-dark) !important;
	background-color: var(--shiki-dark-bg) !important;
	/* Optional, if you also want font styles */
	font-style: var(--shiki-dark-font-style) !important;
	font-weight: var(--shiki-dark-font-weight) !important;
	text-decoration: var(--shiki-dark-text-decoration) !important;
	}
	```
	> The class name used in [shiki](https://shiki.style/guide/dual-themes#query-based-dark-mode) is `.shiki`, here you need to use `.astro-code`.
	:::note [Customizing Shiki themes]
	Astro code blocks are styled using the `.astro-code` class. When following Shiki's documentation (e.g. to [customize light/dark dual or multiple themes](https://shiki.style/guide/dual-themes#query-based-dark-mode)), be sure to replace the `.shiki` class in the examples with `.astro-code`
	:::

I think this note helpfully sends people to a better place to see the example (because Shiki will maintain it and keep it updated in the event that things change) and emphasizes the important point which is the astro-code class used! There may be other situations, not just light and dark mode, where knowing this is helpful to the reader.

[kieranwv]

😀 Thank you very much for your and I think you are right.

[astrobot-houston]

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	guides/markdown-content.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]

Thank you @kaivanwong ! I think this note is going to be really helpful, and really call attention to the main point. Thank you for taking the time to contribute this, and welcome to Team Docs! 🥳

[kieranwv]

Thank you @kaivanwong ! I think this note is going to be really helpful, and really call attention to the main point. Thank you for taking the time to contribute this, and welcome to Team Docs! 🥳

Thank you, and I am happy to be able to make some small contribution. 😸