Skip to content

docs: add Tailwind instructions on how to use multiple configs#3198

Closed
HiDeoo wants to merge 2 commits intowithastro:mainfrom
HiDeoo:hd-docs-tailwind-multiple-config
Closed

docs: add Tailwind instructions on how to use multiple configs#3198
HiDeoo wants to merge 2 commits intowithastro:mainfrom
HiDeoo:hd-docs-tailwind-multiple-config

Conversation

@HiDeoo
Copy link
Copy Markdown
Member

@HiDeoo HiDeoo commented May 13, 2025

Description

This PR updates the Tailwind instructions to help with issue 6 in #3162:

When using custom pages or Starlight at a subpath and want to use Tailwind on both your main site/custom pages and Starlight, you propably want to use a default Tailwind setup for your main website/custom pages and a different one for Starlight which would use the Starlight’s Tailwind compatibility package.

  1. My initial assessment was only focusing on the case of using Starlight at a subpath.

  2. My initial idea was to add a small sentence in the existing Tailwind instructions, e.g.:

    If you are using Starlight at a subpath, you can use a different Tailwind CSS file for your main website often imported in a layout component.

  3. After discussing the topic during Talking and Doc'ing, the idea of creating a entirely new sub-section "Add site-wide Tailwind support with Starlight at a subpath" was identified as a better approach. Even though it was vaguely similar to the existing "Add Tailwind to an existing project" section, it gives the user better instructions, and in the "Tailwind CSS" intro section, we can link to the various possible setups.

  4. When working on the PR and checking various support threads, I realized that this setup may not only be useful for Starlight at a subpath, but also for users who want to use custom pages.

This PR keeps the new idea of creating a new sub-section but tries to cover both use cases: custom pages and Starlight at a subpath.

Other ideas discarded during T&D:

  • Not re-using src/styles/global.css in our "Add Tailwind to an existing project" section but instead creating a new src/styles/starlight.css file so that it's more obvious that this file is only used for Starlight and the other one is only used for the main site/custom pages.

    This was discarded because src/styles/global.css is automatically scaffolded by Astro and this use-case is still a small percentage of users. That would mean that most people would end up with an src/styles/global.css file that they don't need.

@netlify
Copy link
Copy Markdown

netlify bot commented May 13, 2025

Deploy Preview for astro-starlight ready!

Name Link
🔨 Latest commit aa2efa8
🔍 Latest deploy log https://app.netlify.com/projects/astro-starlight/deploys/6826f5c7bb3a46000822e590
😎 Deploy Preview https://deploy-preview-3198--astro-starlight.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
1 paths audited
Performance: 100 (no change from production)
Accessibility: 100 (no change from production)
Best Practices: 100 (no change from production)
SEO: 100 (no change from production)
PWA: -
View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

@github-actions github-actions bot added the 📚 docs Documentation website changes label May 13, 2025
@astrobot-houston
Copy link
Copy Markdown
Contributor

astrobot-houston commented May 13, 2025

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/css-and-tailwind.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.

@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented May 13, 2025

⚠️ No Changeset found

Latest commit: aa2efa8

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@awhitford
Copy link
Copy Markdown

Is the Starlight with Tailwind example going to be updated to match these instructions? It sounds like we should get global.css and starlight.css out of the box.

Just like someone might add Starlight to an Astro project, the other way around is also logical; I should be able to easily add custom Astro pages to a Starlight project.

@HiDeoo
Copy link
Copy Markdown
Member Author

HiDeoo commented May 16, 2025

Is the Starlight with Tailwind example going to be updated to match these instructions? It sounds like we should get global.css and starlight.css out of the box.

Not something planned with this approach as described at the end of the PR body.

I'm working on another PR as an alternative to this one, doing what you described and taking another approach for the docs that I plan to share with the team to discuss the pros/cons of both approaches.

@delucis
Copy link
Copy Markdown
Member

delucis commented Jul 14, 2025

Closing in favour of #3273!

@delucis delucis closed this Jul 14, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

📚 docs Documentation website changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants