Skip to content

Commit 02816cf

Browse files
docs: warn of styling config restriction (#2161)
1 parent c68a4e7 commit 02816cf

File tree

2 files changed

+63
-3
lines changed

2 files changed

+63
-3
lines changed

packages/docs/docs/config/README.md

+31-1
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,36 @@ VuePress provides a convenient way to add extra styles. You can create a `.vuepr
183183
}
184184
```
185185

186+
::: warning
187+
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**.
188+
:::
189+
190+
::: details What if you have to import / require normal `css` style sheets?
191+
192+
Use **Absolute path**.
193+
194+
1. Importing / requiring a file from an npm package:
195+
196+
``` stylus
197+
@require '~my-css-package/style.css'
198+
```
199+
200+
2. Importing / requiring a local file:
201+
202+
As there’s an [alias](../plugin/option-api.html#alias) option out there, using webpack alias must be the simplest approach. For example:
203+
204+
```js
205+
// config.js
206+
alias: {
207+
'styles': path.resolve(__dirname, './styles')
208+
}
209+
```
210+
211+
``` stylus
212+
@require '~styles/style.css'
213+
```
214+
:::
215+
186216
**Also see:**
187217

188218
- [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)
@@ -321,7 +351,7 @@ This option is also included in [Plugin API](../plugin/option-api.md#extendmarkd
321351
- Default: `['h2', 'h3']`
322352

323353
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-
354+
325355
``` js
326356
module.exports = {
327357
markdown: {

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

+32-2
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,7 @@ $MQMobile = 719px
165165
$MQMobileNarrow = 419px
166166
```
167167

168-
::: danger Note
168+
::: danger
169169
你应该**只在**这个文件中定义变量。因为 `palette.styl` 将在根的 stylus 配置文件的末尾引入,作为配置,它将被多个文件使用,所以一旦你在这里写了样式,你的样式就会被多次复制。
170170
:::
171171

@@ -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+
::: details 那如果你非得要 import / require 一般的 `.css` 样式表呢?
187+
188+
使用**绝对路径**
189+
190+
1. 从 npm package 引用档案:
191+
192+
``` stylus
193+
@require '~my-css-package/style.css'
194+
```
195+
196+
2. 引用本地档案:
197+
198+
因为已经有 [alias](../plugin/option-api.html#alias) 这个选项,使用 webpack 别名会是最简单的方式,举例如下:
199+
200+
```js
201+
// config.js
202+
alias: {
203+
'styles': path.resolve(__dirname, './styles')
204+
}
205+
```
206+
207+
``` stylus
208+
@require '~styles/style.css'
209+
```
210+
:::
211+
182212
**参考:**
183213

184214
- [为什么不能把 `palette.styl``index.styl` 合并到一个 API?](../faq/#为什么不能把-palette-styl-和-index-styl-合并到一个-api)
@@ -317,7 +347,7 @@ module.exports = {
317347
- 默认值: `['h2', 'h3']`
318348

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

0 commit comments

Comments
 (0)