fix: better description and explanation of how to use the dual themes of Shiki

gxlpes commented 2 weeks ago

Description (required)

When trying to implement the dual themes of Shiki, it's necessary to use the CSS snippets that their docs provided. But because of how Astro implements the Shiki under the hood, it's necessary to use the class .astro-code instead of .shiki that their docs stated.

I'm proposing a new section in the Syntax highlighting of Astro docs to make clear to new users how to implement the feature of dual theming. I think that dark/light mode is a key feature and having this new section would make everything clear with Shiki.

The correct CSS to make the CSS dual theme work should be

@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;
  }
}

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;
}

Related issues & labels (optional)

Closes: 8163 | 8152
Suggested label: CSS Configuration of Shiki with dual themes

vercel[bot] commented 2 weeks ago

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

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

astrobot-houston commented 2 weeks ago

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 Vercel 🥳
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 commented 2 weeks ago

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](https://lunaria.dev/reference/configuration/#files-required) 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](https://lunaria.dev/reference/configuration/#ignorekeywords) in the PR's title (ignoring all files) or by [including a tracker directive](https://lunaria.dev/guides/tracking/#tracker-directives) 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 commented 2 weeks ago

Hi @gxlpes ! Thank you for picking up on some outstanding issues in the docs repo! 💪

We actually already have an open PR very close to merging to address this very topic: #7218 You can follow its progress, see my comment to the existing proposal, and comment there!

Since that PR is already open and being worked on for this very thing, I will close this PR. But I encourage you to participate in the other PR! I have a proposed suggestion for the author, and have been waiting to hear back. Would be happy to have your thoughts there.

withastro / docs