Skip to content

Commit 0c8f32b

Browse files
committed
docs: warn of styling config restriction
1 parent 4bdca1c commit 0c8f32b

File tree

2 files changed

+61
-2
lines changed

2 files changed

+61
-2
lines changed

packages/docs/docs/config/README.md

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,35 @@ VuePress provides a convenient way to add extra styles. You can create a `.vuepr
187187

188188
- [Why can’t `palette.styl` and `index.styl` merge into one API?](../faq/README.md#why-can-t-palette-styl-and-index-styl-merge-into-one-api)
189189

190+
::: warning
191+
Because of the behavior behind the scenes, in both `palette.styl` and `index.styl`, the normal `.css` style sheets are not allowed to be imported by [@import / @require](https://stylus-lang.com/docs/import.html) from **relative paths**.
192+
:::
193+
194+
::: tip
195+
What if you have to import / require normal `css` style sheets? **Absolute path**.
196+
197+
1. Importing / requiring a file from an npm package:
198+
199+
``` stylus
200+
@require '~my-css-package/style.css'
201+
```
202+
203+
2. Importing / requiring a local file:
204+
205+
As there’s an [alias](../plugin/option-api.html#alias) option out there, using webpack alias must be the simplest approach. For example:
206+
207+
```js
208+
// config.js
209+
alias: {
210+
'styles': path.resolve(__dirname, './styles')
211+
}
212+
```
213+
214+
``` stylus
215+
@require '~styles/style.css'
216+
```
217+
:::
218+
190219
## Theming
191220

192221
### theme
@@ -321,7 +350,7 @@ This option is also included in [Plugin API](../plugin/option-api.md#extendmarkd
321350
- Default: `['h2', 'h3']`
322351

323352
While preparing the page, headers are extracted from the Markdown file and stored in `this.$page.headers`. By default, VuePress will extract `h2` and `h3` elements for you. You can override the headers it pulls out in your `markdown` options.
324-
353+
325354
``` js
326355
module.exports = {
327356
markdown: {

packages/docs/docs/zh/config/README.md

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,36 @@ VuePress 提供了一种添加额外样式的简便方法。你可以创建一
179179
}
180180
```
181181

182+
::: warning
183+
由于背后的行为,不论是在 `palette.styl` 或是 `index.styl` ,都不能透过 [@import / @require](https://stylus-lang.com/docs/import.html)**相对路径**引用一般的 `.css` 样式表。
184+
:::
185+
186+
::: tip
187+
那如果你非得要 import / require 一般的 `.css` 样式表呢? **绝对路径**
188+
189+
1. 从 npm package 引用档案:
190+
191+
``` stylus
192+
@require '~my-css-package/style.css'
193+
```
194+
195+
2. 引用本地档案:
196+
197+
因为已经有 [alias](../plugin/option-api.html#alias) 这个选项,使用 webpack 别名会是最简单的方式,举例如下:
198+
199+
```js
200+
// config.js
201+
alias: {
202+
'styles': path.resolve(__dirname, './styles')
203+
}
204+
```
205+
206+
``` stylus
207+
@require '~styles/style.css'
208+
```
209+
:::
210+
211+
182212
## 主题
183213

184214
### theme
@@ -313,7 +343,7 @@ module.exports = {
313343
- 默认值: `['h2', 'h3']`
314344

315345
Markdown 文件的 headers (标题 & 小标题) 会在准备阶段被提取出来,并存储在 `this.$page.headers` 中。默认情况下,VuePress 会提取 `h2``h3` 标题。你可以通过这个选项来修改提取出的标题级别。
316-
346+
317347
``` js
318348
module.exports = {
319349
markdown: {

0 commit comments

Comments
 (0)