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: update docs on links #1440

Merged
merged 4 commits into from
Mar 13, 2019
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
31 changes: 14 additions & 17 deletions packages/docs/docs/guide/markdown.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,7 @@ Headers automatically get anchor links applied. Rendering of anchors can be conf

### Internal Links

Inbound links ending in `.md` or `.html` are converted to `<router-link>` for SPA navigation.

Each sub-directory in your static site should contain a `README.md`. It will automatically be converted to `index.html`.

::: tip
When writing the relative path to a directory's `index.html`, don't forget to close it off with a `/`, otherwise you will get a 404. For example, use `/config/` instead of `/config`.
:::

If you want to link to another markdown file within a directory, remember to:

1. Append it with either `.html` or `.md`
2. Make sure the case matches since the path is case-sensitive

#### Example
Internal links are converted to `<router-link>` for SPA navigation. Also, every `README.md` or `index.md` contained in each sub-directory will automatically be converted to `index.html`, with corresponding url `/`.

Given the following directory structure:

Expand All @@ -38,14 +25,24 @@ Given the following directory structure:
└─ four.md
```

And providing you are in `foo/one.md`:

```md
[Home](/) <!-- Sends the user to the root README.md -->
[foo](/foo/) <!-- Sends the user to index.html of directory foo -->
[foo heading anchor](/foo/#heading) <!-- Anchors user to a heading in the foo README file -->
[foo - one](/foo/one.html) <!-- You can append .html -->
[foo - two](/foo/two.md) <!-- Or you can append .md -->
[foo heading](./#heading) <!-- Anchors user to a heading in the foo README file -->
[bar - three](../bar/three.md) <!-- You can append .md (recommended) -->
[bar - four](../bar/four.html) <!-- Or you can append .html -->
```

### Redirection for URLs <Badge text="1.0.0-alpha.37"/>

VuePress supports redirecting to clean links. If a link `/foo` is not found, VuePress will look for a existing `/foo/` or `/foo.html`. Conversely, when one of `/foo/` or `/foo.html` is not found, VuePress will also try the other. With this feature, we can customize your website's urls with the official plugin [@vuepress/plugin-clean-urls](../plugin/official/plugin-clean-urls.md).

::: tip
Regardless of whether the permalink and clean-urls plugins are used, your relative path should be defined by the current file structure. In the above example, even though you set the path of `/foo/one.md` to `/foo/one/`, you should still access `/foo/two.md` via `./two.md`.
:::

### External Links

Outbound links automatically gets `target="_blank" rel="noopener noreferrer"`:
Expand Down
31 changes: 14 additions & 17 deletions packages/docs/docs/zh/guide/markdown.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,7 @@

### 内部链接

内部的、并以 `.md` or `.html` 结尾的链接,将会被转换成 `<router-link>` 用于 SPA 导航。

站内的每一个子文件夹都应当有一个 `README.md` 文件,它会被自动编译为 `index.html`。

::: tip
在链接到一个文件夹的 `index.html` 时,确保你的链接以 `/` 结尾,否则该链接将导致 404。比如,用 `/config/` 而不是 `/config`。
:::

如果你想要链接到另一个 markdown 文件:

1. 确保链接以 `.html` 或 `.md` 结尾;
2. 确保路径大小写正确,因为路径的匹配是大小写敏感的。

#### 示例
网站内部的的链接,将会被转换成 `<router-link>` 用于 SPA 导航。同时,站内的每一个文件夹下的 `README.md` 或者 `index.md` 文件都会被自动编译为 `index.html`,对应的链接将被视为 `/`。

以如下的文件结构为例:

Expand All @@ -38,14 +25,24 @@
└─ four.md
```

假设你现在在 `foo/one.md` 中:

``` md
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

假设你现在在 foo/one.md

上面的这句话建议移到这个的前面,我作为阅读者找了一会儿才看到这个前提。

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

已修改~

[Home](/) <!-- 跳转到根部的 README.md -->
[foo](/foo/) <!-- 跳转到 foo 文件夹的 index.html -->
[foo heading anchor](/foo/#heading) <!-- 跳转到 foo/index.html 的特定 anchor 位置 -->
[foo - one](/foo/one.html) <!-- 具体文件可以使用 .html 结尾 -->
[foo - two](/foo/two.md) <!-- 也可以用 .md -->
[foo heading](./#heading) <!-- 跳转到 foo/index.html 的特定标题位置 -->
[bar - three](../bar/three.md) <!-- 具体文件可以使用 .md 结尾(推荐) -->
[bar - four](../bar/four.html) <!-- 也可以用 .html -->
```

### 链接的重定向 <Badge text="1.0.0-alpha.37"/>

VuePress 支持重定向到干净链接。如果一个链接 `/foo` 找不到,VuePress 会自行寻找一个可用的 `/foo/` 或 `/foo.html`。反过来,当 `/foo/` 或 `/foo.html` 中的一个找不到时,VuePress 也会尝试寻找另一个。借助这种特性,我们可以通过官方插件 [@vuepress/plugin-clean-urls](../plugin/official/plugin-clean-urls.md) 定制你的网站路径。

::: tip 注意
无论是否使用了 permalink 和 clean-urls 插件,你的相对路径都应该依赖于当前的文件结构来定义。在上面的例子中,即使你将 `/foo/one.md` 的路径设为了 `/foo/one/`,你依然应该通过 `./two.md` 来访问 `/foo/two.md`。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这里的 clean-urls 建议加上你插件的 github 地址

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

上一段中已经有链接了,所以认为这里不需要了。

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

恩恩~

:::

### 外部链接

外部的链接将会被自动地设置为 `target="_blank" rel="noopener noreferrer"`:
Expand Down