docs: Expanded sections on applying custom CSS and SCSS to the default theme, and working with dark mode #2377
Conversation
SimonEast
changed the title
SimonEast
changed the title
Changed `config.ts` to `config.[extension]`
Minor correction, adding extra CSS variable, and correcting typo
Added --vp-c-brand-light that was missing
brc-dd
force-pushed
the
main
branch
2 times, most recently
from
7ad4a4e
to
f0d3082
Compare
|
I've updated my PR so that the docs match the latest VitePress theme. Would be great to get any final feedback/tweaks that might be preventing it from being merged in. I think it's important to get people up and running fast with the default theme but allow them to easily swap the color scheme for something that matches their project, and that's what this PR is intended to do. |
| @@ -17,7 +17,7 @@ export default { | |||
| } | |||
| ``` | |||
|
|
|||
| **The options documented on this page only apply to the default theme.** Different themes expect different theme config. When using a custom theme, the theme config object will be passed to the theme so the theme can define conditional behavior based on it. | |||
| **The options documented on this page only apply to the default theme.** Different themes expect different theme configuration options. When using a custom theme, the theme config object will be passed to the theme so the theme can define conditional behavior based on it. | |||
There was a problem hiding this comment.
the earlier one was already clear IMO
There was a problem hiding this comment.
Well the first few times I read that sentence, it stumped me. I thought What does that even mean? I thought "configuration options" would be a small improvement and more accurate term.
But I can skip the change if necessary.
| @@ -1,6 +1,6 @@ | |||
| # Default Theme Config | |||
|
|
|||
| Theme config lets you customize your theme. You can define theme config via the `themeConfig` option in the config file: | |||
| Theme config lets you customize your theme. You can define theme config via the `themeConfig` option inside [`.vitepress/config.[extension]`](./site-config): | |||
There was a problem hiding this comment.
don't think this is needed either
There was a problem hiding this comment.
Perhaps it's obvious once you've used VitePress for a while, but as a newcomer it's not clear which config file this is referring to and where it's located. I initially wondered "Does VitePress have more than one config file?" and "Is there a theme config file, or is it the same as the VitePress config file?" and "Which folder should I be looking in?".
I think having the path here reduces that initial confusion.
| @@ -200,9 +200,9 @@ Note that this might prevent certain tokens from being syntax highlighted proper | |||
|
|
|||
| ## Using CSS Pre-processors | |||
|
|
|||
| VitePress has [built-in support](https://vitejs.dev/guide/features.html#css-pre-processors) for CSS pre-processors: `.scss`, `.sass`, `.less`, `.styl` and `.stylus` files. There is no need to install Vite-specific plugins for them, but the corresponding pre-processor itself must be installed: | |||
| VitePress has [built-in support](https://vitejs.dev/guide/features.html#css-pre-processors) for CSS pre-processors: `.scss`, `.sass`, `.less`, `.styl` and `.stylus` files. Simply install the pre-processor itself using the applicable command: | |||
There was a problem hiding this comment.
again unnecessary change. please avoid just rephrasing and moving things around
There was a problem hiding this comment.
I felt the "Vite-specific plugin" point was a side-note that just added confusion when I initially read it (it led me to ask "Am I supposed to understand the difference between a Vite-plugin and a pre-processor?"). The revised version jumps straight to the commands necessary to get them up and running, and puts the side-note below, for those needing it.
But if you feel strongly about keeping it as is, I can revert.
| @@ -4,7 +4,7 @@ outline: deep | |||
|
|
|||
| # Extending the Default Theme | |||
|
|
|||
| VitePress' default theme is optimized for documentation, and can be customized. Consult the [Default Theme Config Overview](../reference/default-theme-config) for a comprehensive list of options. | |||
| VitePress' default theme is optimized for documentation, and a number of elements can be customized via `.vitepress/config.[extension]`. Consult the [Default Theme Config Overview](../reference/default-theme-config) for a comprehensive list of options. | |||
There was a problem hiding this comment.
site config has a separate section, no need to keep putting same thing everywhere.
There was a problem hiding this comment.
As mentioned in another comment, I initially found it confusing to work out which config file I was supposed to modify. Just trying to help new users get up to speed quickly.
If you're opposed to the repetition, perhaps it could just be a hyperlink instead, like this:
| VitePress' default theme is optimized for documentation, and a number of elements can be customized via `.vitepress/config.[extension]`. Consult the [Default Theme Config Overview](../reference/default-theme-config) for a comprehensive list of options. | |
| VitePress' default theme is optimized for documentation, and a number of elements can be customized via [the site config file](../reference/site-config). Consult the [Default Theme Config Overview](../reference/default-theme-config) for a comprehensive list of options. |
| ::: code-group | ||
| ```js [.vitepress/theme/index.js] |
There was a problem hiding this comment.
code groups are not meant to just show title, keep the original formatting
There was a problem hiding this comment.
Well, I find it cleaner and clearer to have the filename outside the actual code block. It also means that when you click the "copy" button, you don't have the additional comment included. I think using a code-group tab for this purpose is a clean solution, but if you're against that I can revert to the original.
| ::: tip | ||
| When SASS variables or functions are used to define a CSS variable, they need to be wrapped in `#{ ... }`. See the SASS documentation [here](https://sass-lang.com/documentation/breaking-changes/css-vars) and [here](https://sass-lang.com/documentation/variables). | ||
| ::: |
There was a problem hiding this comment.
remove this, we don't need to teach sass/scss to users. if someone is using a pre processor they should be aware of it's syntax
There was a problem hiding this comment.
Yes, I agree that it's not necessary to explain basic SCSS syntax for the most part, however in this case I believe explaining the #{ ... } syntax is warranted since:
- It's difficult to find within the SASS documention. It's hidden under a "breaking changes" document, and not mentioned at all on the main SASS Variables doc page where you would expect.
- Combining CSS variables and SASS variables may not be standard practice for many devs (generally you would stick to one or the other), but when customizing VitePress in this way it becomes necessary
Having this tip here would have saved me 20mins of hunting through my CSS inspector for why it wasn't working, and then paging through multiple Google results until I found the issue.
Hi VitePress team,
I spent some time figuring out how to apply style customizations to the default theme, and would like to contribute back to the official documentation to assist others in this process.
Here's my pull request, which relates only to the docs.
Since this is my first one, please feel free to provide feedback or tweaks/adjustments to what I have written, and I can make any necessary changes if required.
Cheers.