Skip to content

Commit 153deb8

Browse files
author
sqrtthree
committed
Add English part of the docs
resolve #5
1 parent 0f533ee commit 153deb8

File tree

11 files changed

+755
-28
lines changed

11 files changed

+755
-28
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ There are some global dependencies you need to set up.
3333
### Installing
3434

3535
```bash
36-
# Install vuepress
36+
# Install VuePress
3737
yarn global add vuepress # OR npm install -g vuepress
3838

3939
# Install theme

‎docs/0-getting-started/README.md‎

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,43 @@
11
# Getting Started
22

3-
Sorry, but I'm still writing this doc.
3+
## Build with
44

5-
Stay tuned, it will appear in a day or two.
5+
The project is based on the following open source technologies:
6+
7+
- [Node.js](https://nodejs.org/)
8+
- [VuePress](https://github.com/vuejs/vuepress)
9+
10+
## Dependencies
11+
12+
Before you start using this theme, please make sure that the following dependencies are installed.
13+
14+
- [Node.js](https://nodejs.org/)
15+
- [VuePress](https://github.com/vuejs/vuepress)
16+
- [vuepress-theme-api](https://github.com/sqrthree/vuepress-theme-api)
17+
18+
If you already have [Node.js](https://nodejs.org/), you can install `VuePress` and `vuepress-theme-api` with the following commands.
19+
20+
```bash
21+
# Install VuePress
22+
yarn global add vuepress # OR npm install -g vuepress
23+
24+
# Install theme
25+
yarn global add vuepress-theme-api # OR npm install -g vuepress-theme-api
26+
```
27+
28+
::: warning Local Dependencies
29+
If you want to use `VuePress` in an existing project and manage documents in that project, you should install VuePress as a local dependency. It should be noted that you also need to install [vuepress-theme-api](https://github.com/sqrthree/vuepress-theme-api) as a local dependency.
30+
:::
31+
32+
## How to use
33+
34+
`VuePress` will use its own default theme by default, so we need to configure the theme option in `.vuepress/config.js` to specify `vuepress-theme-api` to apply the theme. See [VuePress | Using a theme](https://vuepress.vuejs.org/theme/using-a-theme.html) to get more details.
35+
36+
```js{5}
37+
// .vuepress/config.js
38+
module.exports = {
39+
title: 'Hello, World.',
40+
description: '📦 🎨 A api-friendly theme for VuePress.',
41+
theme: 'api',
42+
}
43+
```

‎docs/1-configurations/1-components.md‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
---
2+
title: Built-in Components
3+
---
4+
5+
<Block>
6+
7+
# Built-in Components
8+
9+
Thanks to [Using Vue in Markdown](https://vuepress.vuejs.org/guide/using-vue.html) feature of `VuePress`, we can directly use Vue components in Markdown files.
10+
11+
In order to better display the content of the document, the theme has built-in several useful components, which you can use directly in any Markdown file.
12+
13+
Built-in components are available out of the box, and you can still write Markdown syntax content in the components.
14+
15+
Currently, the following components are mainly built-in:
16+
17+
[[toc]]
18+
19+
</Block>
20+
21+
<Block>
22+
23+
## Block Component
24+
25+
26+
The `Block` component is mainly used to divide the page structure. Each `Block` component is a content group. It is convenient for you to control the page structure freely and flexibly.
27+
28+
<Example>
29+
30+
Usage:
31+
32+
```vue
33+
<Block>
34+
35+
Contents...
36+
37+
</Block>
38+
```
39+
40+
</Example>
41+
42+
</Block>
43+
44+
<Block>
45+
46+
## Example Component
47+
48+
The `Example` component is used to specify the content of the dark area on the right in the `<Block>` component. It can clearly identify the current part of the content as a use case.
49+
50+
<Example>
51+
52+
Usage:
53+
54+
```vue
55+
<Block>
56+
57+
Contents...
58+
59+
<Example>
60+
61+
Some examples...
62+
63+
</Example>
64+
65+
</Block>
66+
```
67+
68+
</Example>
69+
70+
</Block>
71+
72+
<Block>
73+
74+
## CURL Component
75+
76+
The `CURL` component is a very useful component for better displaying `curl` commands when writing APIs.
77+
78+
For example, the following content will be rendered into the form on the right:
79+
80+
````vue
81+
<CURL>
82+
```bash
83+
curl -X POST https://api.example.com/v1/auth/login \
84+
-H 'Content-Type: application/json' \
85+
-H 'Authorization: Bearer <const name="MOCK_TOKEN" />' \
86+
--data '{
87+
"username": "my-username",
88+
"password": "my-password"
89+
}'
90+
```
91+
</CURL>
92+
````
93+
94+
The `CURL` component will automatically generate a button below the component. When the button is clicked, it will analyze the parameters in the `curl` command and send a request via `Ajax` to the corresponding url. And output its request information to the `console` panel. Convenient for quick test and preview.
95+
96+
<Example>
97+
98+
<CURL>
99+
100+
```bash
101+
curl -X POST http://api.example.com/api/auth/login \
102+
-H 'Content-Type: application/json' \
103+
-H 'Authorization: Bearer <const name="MOCK_TOKEN" />' \
104+
--data '{
105+
"username": "my-username",
106+
"password": "my-password"
107+
}'
108+
```
109+
</CURL>
110+
111+
</Example>
112+
113+
e.g.：
114+
115+
````vue
116+
<CURL>
117+
```bash
118+
curl -X GET https://api.github.com/users/sqrthree
119+
```
120+
</CURL>
121+
````
122+
123+
<Example>
124+
125+
<Blank height="148px" />
126+
127+
<CURL>
128+
```bash
129+
curl -X GET https://api.github.com/users/sqrthree
130+
```
131+
</CURL>
132+
133+
</Example>
134+
135+
In addition, the content of `curl` on the right can be directly edited and then sent the request with changes. The modification will take effect immediately. This is very useful when you want to modify some parameters temporarily.
136+
137+
</Block>
138+
139+
<Block>
140+
141+
## Button Component
142+
143+
The `Button` component can be used anywhere on any page. You can use it to point to a link or some special content.
144+
145+
The supported parameters are as follows:
146+
147+
| Name | Type | Description | Default |
148+
| :---: | :-----: | :------------------------------------: | :-----: | :--: |
149+
| to | String | page link | `""` |
150+
| size | String | Set the size of button, values: `small | large` | `""` |
151+
| light | Boolean | Whether to use light theme | `false` |
152+
153+
Use the following code to render a button:
154+
155+
```vue
156+
<Button>Default state</Button>
157+
```
158+
159+
Rendered:
160+
161+
<Button>Default state</Button>
162+
163+
<br>
164+
<br>
165+
166+
Page link:
167+
168+
```vue
169+
<Button to="/">Homepage</Button>
170+
```
171+
172+
Rendered:
173+
174+
<Button to="/">Homepage</Button>
175+
176+
<Example>
177+
178+
More use cases:
179+
180+
```vue
181+
<Button light>Light theme</Button>
182+
```
183+
184+
<Button light>Light theme</Button>
185+
186+
```vue
187+
<Button to="https://github.com/sqrthree/vuepress-theme-api" light>Page link</Button>
188+
```
189+
190+
<Button to="https://github.com/sqrthree/vuepress-theme-api" light>Page Link</Button>
191+
192+
```vue
193+
<Button size="small" light>Other size</Button>
194+
```
195+
196+
<Button size="small" light>Other size</Button>
197+
198+
</Example>
199+
200+
</Block>
201+
202+
<Block>
203+
204+
## Section Component
205+
206+
The `Section` component is a special layout form, mainly used in [Homepage Layout](/#build-for-restful-api). Refer to [Homepage | Build for RESTful API](/#build-for-restful-api) to preview.
207+
208+
| Name | Type | Description | Default |
209+
| :---------: | :-----: | :------------------------------------------: | :------: |
210+
| theme | String | Set the theme `dark \| light` | `"dark"` |
211+
| center | Boolean | The specify which way that content is aligned | `true` |
212+
| enhanceMode | Boolean | Whether to enable enhanced mode | `true` |
213+
214+
::: tip Enhanced mode
215+
Enhanced mode means that the `Section` component breaks through the limit of the parent element width and achieves the same effect as the width of the browser window.
216+
:::
217+
218+
<Example>
219+
220+
The configuration used in the homepage:
221+
222+
```vue
223+
<Section>
224+
225+
## Build for RESTful API
226+
227+
A easy-to-use, minimalist theme for VuePress.
228+
229+
With out-of-the-box feature, all you need to do is install it and write something.
230+
231+
<br>
232+
233+
<Button type="light" to="/getting-started/">Getting Started</Button>
234+
235+
</Section>
236+
```
237+
238+
</Example>
239+
240+
</Block>

‎docs/1-configurations/2-template.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: File template
3+
---
4+
5+
<Block>
6+
7+
# File template
8+
9+
In most cases, the structure on the right can be used when writing a document:
10+
11+
In addition, we have also prepared a complete use case out of the box for you, which is convenient for you to quickly initialize a document project. You can get more information at [sqrthree/vuepress-theme-api-starter-kit](https://github.com/sqrthree/vuepress-theme-api-starter-kit)
12+
13+
<Example>
14+
15+
General document template:
16+
17+
```md
18+
---
19+
title: Page Title
20+
---
21+
22+
<Block>
23+
24+
## Title
25+
26+
Main content...
27+
28+
<Example>
29+
30+
Example...
31+
32+
</Example>
33+
34+
</Block>
35+
```
36+
37+
API document template:
38+
39+
```md
40+
---
41+
title: Page Title
42+
---
43+
44+
<Block>
45+
46+
## API name
47+
48+
API description...
49+
50+
### Endpoint
51+
52+
### Parameters
53+
54+
| Name | Type | Description | Required |
55+
| :-----------------: | :----: | :---------: | :----------------: |
56+
| Required parameters | String | | :heavy_check_mark: |
57+
| Optional parameters | String | | :heavy_minus_sign: |
58+
59+
### Response
60+
61+
Response case...
62+
63+
<Example>
64+
65+
<CURL>
66+
curl...
67+
</CURL>
68+
69+
</Example>
70+
71+
</Block>
72+
```
73+
74+
</Example>
75+
76+
</Block>

0 commit comments

Comments
 (0)