Skip to content

Commit e690e14

Browse files
nekomeowwwnekomeowww
committed
docs: refactored docs to better guide users
Signed-off-by: Neko Ayaka <neko@ayaka.moe>
1 parent 9f66cfd commit e690e14

13 files changed

Lines changed: 1178 additions & 1079 deletions

File tree

‎docs/.vitepress/config.ts‎

Lines changed: 77 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,33 @@ export const sidebars: Record<string, DefaultTheme.Sidebar> = {
2323
text: 'Integrations',
2424
items: [
2525
{ text: 'Overview', link: '/pages/en/integrations/' },
26+
{
27+
text: 'Markdown-it plugins',
28+
items: [
29+
{ text: 'Bi-directional links', link: '/pages/en/integrations/markdown-it-bi-directional-links/' },
30+
{ text: 'Element Transformation', link: '/pages/en/integrations/markdown-it-element-transform/' },
31+
{ text: 'Lazy loading blurred thumbnails', link: '/pages/en/integrations/markdown-it-unlazy-img/' },
32+
],
33+
},
34+
{
35+
text: 'VitePress plugins',
36+
items: [
37+
{ text: 'Enhanced Readabilities', link: '/pages/en/integrations/vitepress-plugin-enhanced-readabilities/' },
38+
{ text: 'Inline Links Previewing', link: '/pages/en/integrations/vitepress-plugin-inline-link-preview/' },
39+
{ text: 'Blinking highlight targeted heading', link: '/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/' },
40+
{ text: 'Changelog & File history', link: '/pages/en/integrations/vitepress-plugin-git-changelog/' },
41+
{ text: 'Page properties', link: '/pages/en/integrations/vitepress-plugin-page-properties/' },
42+
{ text: 'Previewing image (social media card) generation', link: '/pages/en/integrations/vitepress-plugin-og-image/' },
43+
{ text: 'Enhanced mark elements', link: '/pages/en/integrations/vitepress-plugin-enhanced-mark/' },
44+
{ text: 'Thumbnail hashing for images', link: '/pages/en/integrations/vitepress-plugin-thumbnail-hash/' },
45+
],
46+
},
47+
{
48+
text: 'Obsidian plugins',
49+
items: [
50+
{ text: 'UnoCSS', link: '/pages/en/integrations/obsidian-plugin-unocss/' },
51+
],
52+
},
2653
],
2754
},
2855
{
@@ -46,7 +73,8 @@ export const sidebars: Record<string, DefaultTheme.Sidebar> = {
4673
text: 'Bi-directional links',
4774
collapsed: true,
4875
items: [
49-
{ text: 'Getting Started', link: '/pages/en/integrations/markdown-it-bi-directional-links/' },
76+
{ text: 'Overview', link: '/pages/en/integrations/markdown-it-bi-directional-links/' },
77+
{ text: 'Getting Started', link: '/pages/en/integrations/markdown-it-bi-directional-links/getting-started' },
5078
{ text: 'Syntax', link: '/pages/en/integrations/markdown-it-bi-directional-links/syntax' },
5179
],
5280
},
@@ -58,7 +86,15 @@ export const sidebars: Record<string, DefaultTheme.Sidebar> = {
5886
text: 'VitePress Plugins',
5987
items: [
6088
{ text: 'Enhanced Readabilities', link: '/pages/en/integrations/vitepress-plugin-enhanced-readabilities/' },
61-
{ text: 'Inline Links Previewing', link: '/pages/en/integrations/vitepress-plugin-inline-link-preview/' },
89+
{
90+
text: 'Inline Links Previewing',
91+
collapsed: true,
92+
items: [
93+
{ text: 'Overview', link: '/pages/en/integrations/vitepress-plugin-inline-link-preview/' },
94+
{ text: 'Getting started', link: '/pages/en/integrations/vitepress-plugin-inline-link-preview/getting-started' },
95+
{ text: 'Configuration', link: '/pages/en/integrations/vitepress-plugin-inline-link-preview/configuration' },
96+
],
97+
},
6298
{ text: 'Blinking highlight targeted heading', link: '/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/' },
6399
{ text: 'Changelog & File history', link: '/pages/en/integrations/vitepress-plugin-git-changelog/' },
64100
{ text: 'Page properties', link: '/pages/en/integrations/vitepress-plugin-page-properties/' },
@@ -121,6 +157,33 @@ export const sidebars: Record<string, DefaultTheme.Sidebar> = {
121157
text: '集成',
122158
items: [
123159
{ text: '概览', link: '/pages/zh-CN/integrations/' },
160+
{
161+
text: 'Markdown It 插件',
162+
items: [
163+
{ text: '双向链接', link: '/pages/zh-CN/integrations/markdown-it-bi-directional-links/' },
164+
{ text: '元素转换', link: '/pages/zh-CN/integrations/markdown-it-element-transform/' },
165+
{ text: '懒加载模糊缩略图', link: '/pages/zh-CN/integrations/markdown-it-unlazy-img/' },
166+
],
167+
},
168+
{
169+
text: 'VitePress 插件',
170+
items: [
171+
{ text: '阅读增强', link: '/pages/zh-CN/integrations/vitepress-plugin-enhanced-readabilities/' },
172+
{ text: '行内链接预览', link: '/pages/zh-CN/integrations/vitepress-plugin-inline-link-preview/' },
173+
{ text: '闪烁高亮当前的目标标题', link: '/pages/zh-CN/integrations/vitepress-plugin-highlight-targeted-heading/' },
174+
{ text: '变更日志 及 文件历史', link: '/pages/zh-CN/integrations/vitepress-plugin-git-changelog/' },
175+
{ text: '页面属性', link: '/pages/zh-CN/integrations/vitepress-plugin-page-properties/' },
176+
{ text: '预览图片（社交媒体卡片）生成', link: '/pages/zh-CN/integrations/vitepress-plugin-og-image/' },
177+
{ text: 'mark 元素增强', link: '/pages/zh-CN/integrations/vitepress-plugin-enhanced-mark/' },
178+
{ text: '缩略图模糊哈希生成', link: '/pages/zh-CN/integrations/vitepress-plugin-thumbnail-hash/' },
179+
],
180+
},
181+
{
182+
text: 'Obsidian 插件',
183+
items: [
184+
{ text: 'UnoCSS', link: '/pages/zh-CN/integrations/obsidian-plugin-unocss/' },
185+
],
186+
},
124187
],
125188
},
126189
{
@@ -144,7 +207,8 @@ export const sidebars: Record<string, DefaultTheme.Sidebar> = {
144207
text: '双向链接',
145208
collapsed: true,
146209
items: [
147-
{ text: '快速上手', link: '/pages/zh-CN/integrations/markdown-it-bi-directional-links/' },
210+
{ text: '介绍', link: '/pages/zh-CN/integrations/markdown-it-bi-directional-links/' },
211+
{ text: '快速上手', link: '/pages/zh-CN/integrations/markdown-it-bi-directional-links/getting-started' },
148212
{ text: '语法', link: '/pages/zh-CN/integrations/markdown-it-bi-directional-links/syntax' },
149213
],
150214
},
@@ -156,14 +220,23 @@ export const sidebars: Record<string, DefaultTheme.Sidebar> = {
156220
text: 'VitePress 插件',
157221
items: [
158222
{ text: '阅读增强', link: '/pages/zh-CN/integrations/vitepress-plugin-enhanced-readabilities/' },
159-
{ text: '行内链接预览', link: '/pages/zh-CN/integrations/vitepress-plugin-inline-link-preview/' },
223+
{
224+
text: '行内链接预览',
225+
collapsed: true,
226+
items: [
227+
{ text: '介绍', link: '/pages/zh-CN/integrations/vitepress-plugin-inline-link-preview/' },
228+
{ text: '快速上手', link: '/pages/zh-CN/integrations/vitepress-plugin-inline-link-preview/getting-started' },
229+
{ text: '配置', link: '/pages/zh-CN/integrations/vitepress-plugin-inline-link-preview/configuration' },
230+
],
231+
},
160232
{ text: '闪烁高亮当前的目标标题', link: '/pages/zh-CN/integrations/vitepress-plugin-highlight-targeted-heading/' },
161233
{ text: '变更日志 及 文件历史', link: '/pages/zh-CN/integrations/vitepress-plugin-git-changelog/' },
162234
{ text: '页面属性', link: '/pages/zh-CN/integrations/vitepress-plugin-page-properties/' },
163235
{ text: '预览图片（社交媒体卡片）生成', link: '/pages/zh-CN/integrations/vitepress-plugin-og-image/' },
164236
{ text: 'mark 元素增强', link: '/pages/zh-CN/integrations/vitepress-plugin-enhanced-mark/' },
165237
{
166238
text: '缩略图模糊哈希生成',
239+
collapsed: true,
167240
items: [
168241
{ text: '用法', link: '/pages/zh-CN/integrations/vitepress-plugin-thumbnail-hash/' },
169242
{ text: '尝试 ThumbHash', link: '/pages/zh-CN/integrations/vitepress-plugin-thumbnail-hash/thumbhash' },

‎docs/pages/en/integrations/markdown-it-bi-directional-links/getting-started.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Getting started
2+
3+
## Installation
4+
5+
Install `@nolebase/markdown-it-bi-directional-links` to your project dependencies by running the following command:
6+
7+
::: code-group
8+
9+
```shell [@antfu/ni]
10+
ni @nolebase/markdown-it-bi-directional-links -D
11+
```
12+
13+
```shell [pnpm]
14+
pnpm add @nolebase/markdown-it-bi-directional-links -D
15+
```
16+
17+
```shell [npm]
18+
npm install @nolebase/markdown-it-bi-directional-links -D
19+
```
20+
21+
```shell [yarn]
22+
yarn add @nolebase/markdown-it-bi-directional-links -D
23+
```
24+
25+
:::
26+
27+
## Configuration
28+
29+
### Integrate with VitePress
30+
31+
In the VitePress configuration file (usually `docs/.vitepress/config.ts`, the file path and extension may be different), import `@nolebase/markdown-it-bi-directional-links` as a plugin, and use it as a `markdown-it` plugin in the `markdown` option:
32+
33+
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
34+
35+
```typescript twoslash
36+
import { cwd } from 'node:process' // [!code ++]
37+
import { defineConfigWithTheme } from 'vitepress'
38+
import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links' // [!code ++]
39+
40+
export default defineConfigWithTheme({
41+
lang: 'en',
42+
title: 'Site name', // For reference only, please do not copy directly
43+
description: 'Description', // For reference only, please do not copy directly
44+
themeConfig: {
45+
// Other configurations...
46+
},
47+
markdown: {
48+
config: (md) => {
49+
md.use(BiDirectionalLinks({ // [!code ++]
50+
dir: cwd(), // [!code ++]
51+
})) // [!code ++]
52+
},
53+
},
54+
})
55+
```
56+
57+
### Integrate on-demand
58+
59+
<!--@include: @/pages/en/snippets/configure-on-your-own-warning.md-->
60+
61+
Import this plugin into the file where you can access the [`markdown-it`](https://github.com/markdown-it/markdown-it) instance, and use it as a `markdown-it` plugin:
62+
63+
```typescript twoslash
64+
import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links' // [!code ++]
65+
```
66+
67+
Then you need to use the `use()` member methods from the `markdown-it` instance to use this plugin.
68+
With a options object that contains a `dir` field which is the root directory of your project supplied, the value for `dir` field can be obtained through `cwd()` function call that imported from either `process` or `node:process`:
69+
70+
```typescript twoslash
71+
import MarkdownIt from 'markdown-it'
72+
let markdownIt: MarkdownIt = null as unknown as MarkdownIt
73+
// ---cut---
74+
import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links' // [!code ++]
75+
import { cwd } from 'node:process' // [!code ++]
76+
77+
// Rest of the code...
78+
// @noErrors
79+
markdownIt.use(BiDirectionalLinks({ // [!code ++]
80+
dir: cwd() // [!code ++]
81+
})) // [!code ++]
82+
```

‎docs/pages/en/integrations/markdown-it-bi-directional-links/index.md‎

Lines changed: 5 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,13 @@
11
# Bi-directional Links <Badge type="tip" text="v1.28.0" />
22

3-
## Introduction
4-
53
**Bi-directional links** (also known as internal links), and another concept you may know and hear about [WikiLinks](https://en.wikipedia.org/wiki/Help:Link), holds a important place in the document engineering area. It is usually used to quickly establish a connection (or link) from one page to another page, and widely used in Wiki pages such as [Wikipedia](https://wikipedia.org), and now days popular tools such as [Obsidian](https://obsidian.md/) and [Logseq](https://logseq.com/).
64

75
This plugin is a fully featured compatible implementation version of [Obsidian](https://obsidian.md)'s [internal links](https://help.obsidian.md/Linking+notes+and+files/Internal+links), it follows two rules:
86

97
1. A page's file name (without extension) can be used as a link target, for example: `[[Bi-directional Links Example Page]]` will be parsed as a link to the globally unique `Bi-directional Links Example Page.md` file.
108
2. A link target can be an absolute path, for example: `[[Some Folder/Bi-directional Links Example Page]]` will be parsed as a link to `Some Folder/Bi-directional Links Example Page.md`, usually appears when you have multiple files with the same name.
119

12-
## Demo
13-
14-
::: info Syntax supporting matrix
10+
## Features
1511

1612
<div grid="~ cols-[auto_1fr] gap-1" items-center my-1>
1713
<span i-icon-park-outline:check-one text="green-600" />
@@ -32,8 +28,7 @@ This plugin is a fully featured compatible implementation version of [Obsidian](
3228
<span>Absolute path</span>
3329
</div>
3430

35-
You can discover more syntaxes and features in the [Syntax](/pages/en/integrations/markdown-it-bi-directional-links/syntax).
36-
:::
31+
## How it looks like
3732

3833
Basic: [[Bi-directional Links Example Page]]
3934

@@ -51,81 +46,8 @@ Images are supported:
5146

5247
## Installation
5348

54-
Install `@nolebase/markdown-it-bi-directional-links` to your project dependencies by running the following command:
55-
56-
::: code-group
57-
58-
```shell [@antfu/ni]
59-
ni @nolebase/markdown-it-bi-directional-links -D
60-
```
61-
62-
```shell [pnpm]
63-
pnpm add @nolebase/markdown-it-bi-directional-links -D
64-
```
65-
66-
```shell [npm]
67-
npm install @nolebase/markdown-it-bi-directional-links -D
68-
```
69-
70-
```shell [yarn]
71-
yarn add @nolebase/markdown-it-bi-directional-links -D
72-
```
73-
74-
:::
75-
76-
## Configuration
77-
78-
### Integrate with VitePress
79-
80-
In the VitePress configuration file (usually `docs/.vitepress/config.ts`, the file path and extension may be different), import `@nolebase/markdown-it-bi-directional-links` as a plugin, and use it as a `markdown-it` plugin in the `markdown` option:
81-
82-
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
83-
84-
```typescript twoslash
85-
import { cwd } from 'node:process' // [!code ++]
86-
import { defineConfigWithTheme } from 'vitepress'
87-
import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links' // [!code ++]
88-
89-
export default defineConfigWithTheme({
90-
lang: 'en',
91-
title: 'Site name', // For reference only, please do not copy directly
92-
description: 'Description', // For reference only, please do not copy directly
93-
themeConfig: {
94-
// Other configurations...
95-
},
96-
markdown: {
97-
config: (md) => {
98-
md.use(BiDirectionalLinks({ // [!code ++]
99-
dir: cwd(), // [!code ++]
100-
})) // [!code ++]
101-
},
102-
},
103-
})
104-
```
105-
106-
### Integrate on-demand
107-
108-
<!--@include: @/pages/en/snippets/configure-on-your-own-warning.md-->
109-
110-
Import this plugin into the file where you can access the [`markdown-it`](https://github.com/markdown-it/markdown-it) instance, and use it as a `markdown-it` plugin:
111-
112-
```typescript twoslash
113-
import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links' // [!code ++]
114-
```
115-
116-
Then you need to use the `use()` member methods from the `markdown-it` instance to use this plugin.
117-
With a options object that contains a `dir` field which is the root directory of your project supplied, the value for `dir` field can be obtained through `cwd()` function call that imported from either `process` or `node:process`:
49+
It is easy and straightforward to install the Bi-directional links plugin into your VitePress project, please follow the steps under [Getting started](./getting-started) page!
11850

119-
```typescript twoslash
120-
import MarkdownIt from 'markdown-it'
121-
let markdownIt: MarkdownIt = null as unknown as MarkdownIt
122-
// ---cut---
123-
import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links' // [!code ++]
124-
import { cwd } from 'node:process' // [!code ++]
51+
## Syntax and markups
12552

126-
// Rest of the code...
127-
// @noErrors
128-
markdownIt.use(BiDirectionalLinks({ // [!code ++]
129-
dir: cwd() // [!code ++]
130-
})) // [!code ++]
131-
```
53+
You can discover more syntaxes and features in the [Syntax](./syntax).

‎docs/pages/en/integrations/markdown-it-bi-directional-links/syntax.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ The following syntaxes are supported:
66
<span i-icon-park-outline:check-one text="green-600" />
77
<span>Basic syntax</span>
88
<span i-icon-park-outline:check-one text="green-600" />
9-
<span>Able to handle hash tags <code>#</code></span>
9+
<span>Links with hash tags <code>#</code></span>
1010
<span i-icon-park-outline:check-one text="green-600" />
11-
<span>Able to handle query strings <code>?</code></span>
11+
<span>Links with query strings <code>?</code></span>
1212
<span i-icon-park-outline:check-one text="green-600" />
1313
<span>Images</span>
1414
<span i-icon-park-outline:check-one text="green-600" />

0 commit comments

Comments
 (0)