docs: Expanded sections on applying custom CSS and SCSS to the default theme, and working with dark mode

docs/guide/extending-default-theme.md

@@ -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.
 
 However, there are a number of cases where configuration alone won't be enough. For example:
 
@@ -20,25 +20,129 @@ Before proceeding, make sure to first read [Using a Custom Theme](./custom-theme
 
 ## Customizing CSS
 
-The default theme CSS is customizable by overriding root level CSS variables:
+To apply custom CSS, you first need to create a custom VitePress theme. Place the following code into `.vitepress/theme/index.js` (or `.ts` if you prefer TypeScript). This imports the default theme and adds an additional CSS file to the bundle:
 
-```js
-// .vitepress/theme/index.js
+::: code-group
+```js [.vitepress/theme/index.js]
 import DefaultTheme from 'vitepress/theme'
 import './custom.css'
 
 export default DefaultTheme
 ```
+:::
+
+The default theme CSS is customizable by overriding root level CSS variables. This example shows how to change the site's color scheme from the default VitePress indigo to shades of red, using one of the built-in color schemes:
+
+::: code-group
+```css [.vitepress/theme/custom.css]
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+:root {
+  /* Brand color 1: for colored text and links */
+  --vp-c-brand-1: var(--vp-c-red-1);
+  /* Brand color 2: for button hover state, etc. */
+  --vp-c-brand-2: var(--vp-c-red-2);
+  /* Brand color 3: for button backgrounds, etc. */
+  --vp-c-brand-3: var(--vp-c-red-3);
+  /* Brand color soft: for tip boxes etc. 
+     Must have transparency to account for nested boxes. */
+  --vp-c-brand-soft: var(--vp-c-red-soft);
+}
+```
+:::
+
+You can swap out the word `red` in the CSS above for other built-in colours: `gray`, `indigo`, `purple`, `green`, or `yellow`. 
+
+Or you can use your own custom colors:
 
 ```css
-/* .vitepress/theme/custom.css */
+/* Change site color scheme to orange */
 :root {
-  --vp-c-brand-1: #646cff;
-  --vp-c-brand-2: #747bff;
+   --vp-c-brand-1: orange;
+   --vp-c-brand-2: #ffbf48;
+   --vp-c-brand-3: orange;
+   --vp-c-brand-soft: rgba(250, 215, 151, 0.14);
 }
 ```
 
-See [default theme CSS variables](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css) that can be overridden.
+There are many other CSS variables that can be overridden if required. See [`vars.css`](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css) in the default theme for the full list.
+
+You can also apply any other CSS style rules here. While using CSS variables is good practice to help reduce repetition, plain CSS is also fine.
+
+Just remember to choose colors that work well in both dark and light modes, unless you disable the dark mode toggle or specify unique colors for both light and dark modes. See [Dark Mode](#dark-mode) below for more.
+
+## Using CSS Pre-Processors
+
+If you'd like to use SASS, LESS, or Stylus within your theme, first make sure the relevant pre-processor is installed by running the applicable command:
+
+```sh
+# .scss and .sass
+npm install -D sass
+
+# .less
+npm install -D less
+
+# .styl and .stylus
+npm install -D stylus
+```
+
+Then update your `import` statement to refer to the appropriate file extension:
+
+::: code-group
+```js [.vitepress/theme/index.js]
+import DefaultTheme from 'vitepress/theme'
+import './custom.scss'      // [!code hl]
+
+export default DefaultTheme
+```
+:::
+
+Here's an example SCSS file that could be used to change the brand colors, automatically creating variations from a single base color:
+
+::: code-group
+```scss [.vitepress/theme/custom.scss]
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+ $brand-color: #27afd5;
+
+ :root {
+   /* Brand color 1: for colored text and links */
+   --vp-c-brand-1: #{$brand-color};
+   /* Brand color 2: for button hover state, etc. */
+   --vp-c-brand-2: #{lighten($brand-color, 10%)};
+   /* Brand color 3: for button backgrounds, etc. */
+   --vp-c-brand-3: #{$brand-color};
+   /* Brand color soft: for tip boxes etc. 
+      Must have transparency to account for nested boxes. */
+   --vp-c-brand-soft: #{transparentize($brand-color, 0.86)};
+ }
+```
+
+::: 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).
+:::
+
+## Dark Mode
+
+To control whether the dark mode toggle is enabled or set to light or dark by default, see the [appearance setting](../reference/site-config#appearance).
+
+When dark mode is enabled, the `<html>` root tag will become `<html class="dark">`. This allows you to apply style overrides based on which setting the user has selected:
+
+```css
+.dark {
+  --vp-c-brand-1: orange;
+  --vp-c-brand-2: #ffbf48;
+  --vp-c-brand-3: orange;
+}
+.dark body {
+  background-color: black;
+}
+```
 
 ## Using Different Fonts
 

docs/guide/markdown.md

@@ -1,6 +1,6 @@
 # Markdown Extensions
 
-VitePress comes with built in Markdown Extensions.
+VitePress comes with built in Markdown Extensions that provide extra functionality and styling options beyond plain Markdown.
 
 ## Header Anchors
 

docs/guide/using-vue.md

@@ -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:
 
-```
+```sh
 # .scss and .sass
 npm install -D sass
 
@@ -213,6 +213,8 @@ npm install -D less
 npm install -D stylus
 ```
 
+It's not necessary to install an additional Vite-specific plugin for the pre-processors in the list above.
+
 Then you can use the following in Markdown and theme components:
 
 ```vue

docs/reference/default-theme-config.md

@@ -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):
 
 ```ts
 export default {
@@ -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.
 
 ## i18nRouting
 
@@ -184,6 +184,8 @@ export type SidebarItem = {
 - Default: `true`
 - Can be overridden per page via [frontmatter](./frontmatter-config#aside)
 
+This is typically used to show the "On this page" section, containing links to major headings within the current page.
+
 Setting this value to `false` prevents rendering of aside container.\
 Setting this value to `true` renders the aside to the right.\
 Setting this value to `left` renders the aside to the left.