Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: warn of styling config restriction (close #1889) #2161

Merged
merged 1 commit into from
Aug 22, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 31 additions & 1 deletion packages/docs/docs/config/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,36 @@ VuePress provides a convenient way to add extra styles. You can create a `.vuepr
}
```

::: warning
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**.
:::

::: details What if you have to import / require normal `css` style sheets?

Use **Absolute path**.

1. Importing / requiring a file from an npm package:

``` stylus
@require '~my-css-package/style.css'
```

2. Importing / requiring a local file:

As there’s an [alias](../plugin/option-api.html#alias) option out there, using webpack alias must be the simplest approach. For example:

```js
// config.js
alias: {
'styles': path.resolve(__dirname, './styles')
}
```

``` stylus
@require '~styles/style.css'
```
:::

**Also see:**

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

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.

``` js
module.exports = {
markdown: {
Expand Down
34 changes: 32 additions & 2 deletions packages/docs/docs/zh/config/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,7 @@ $MQMobile = 719px
$MQMobileNarrow = 419px
```

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

Expand All @@ -179,6 +179,36 @@ VuePress 提供了一种添加额外样式的简便方法。你可以创建一
}
```

::: warning
由于背后的行为,不论是在 `palette.styl` 或是 `index.styl` ,都不能透过 [@import / @require](https://stylus-lang.com/docs/import.html) 從**相对路径**引用一般的 `.css` 样式表。
:::

::: details 那如果你非得要 import / require 一般的 `.css` 样式表呢?

使用**绝对路径**。

1. 从 npm package 引用档案:

``` stylus
@require '~my-css-package/style.css'
```

2. 引用本地档案:

因为已经有 [alias](../plugin/option-api.html#alias) 这个选项,使用 webpack 别名会是最简单的方式,举例如下:

```js
// config.js
alias: {
'styles': path.resolve(__dirname, './styles')
}
```

``` stylus
@require '~styles/style.css'
```
:::

**参考:**

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

Markdown 文件的 headers (标题 & 小标题) 会在准备阶段被提取出来,并存储在 `this.$page.headers` 中。默认情况下,VuePress 会提取 `h2` 和 `h3` 标题。你可以通过这个选项来修改提取出的标题级别。

``` js
module.exports = {
markdown: {
Expand Down