Skip to content

Commit

Permalink
docs: warn of styling config restriction
Browse files Browse the repository at this point in the history
  • Loading branch information
billyyyyy3320 committed Mar 2, 2020
1 parent 4bdca1c commit 0c8f32b
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 2 deletions.
31 changes: 30 additions & 1 deletion packages/docs/docs/config/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,35 @@ VuePress provides a convenient way to add extra styles. You can create a `.vuepr

- [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)

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

::: tip
What if you have to import / require normal `css` style sheets? **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'
```
:::

## Theming

### theme
Expand Down Expand Up @@ -321,7 +350,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
32 changes: 31 additions & 1 deletion packages/docs/docs/zh/config/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,36 @@ VuePress 提供了一种添加额外样式的简便方法。你可以创建一
}
```

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

::: tip
那如果你非得要 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'
```
:::


## 主题

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

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

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

0 comments on commit 0c8f32b

Please sign in to comment.