Skip to content

Commit 8a6da67

Browse files
author
kongjing
committed
feat: 文档支持i18n
1 parent 49520a4 commit 8a6da67

17 files changed

Lines changed: 595 additions & 81 deletions

File tree

‎packages/doc/antm.config.ts‎

Lines changed: 39 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@ export default defineConfig({
3939
type: 'text',
4040
},
4141
],
42+
i18n: {
43+
langs: ['EN', 'CN'],
44+
},
4245
menu: createMenu(),
4346
// simulator: {
4447
// url: {
@@ -52,40 +55,67 @@ export default defineConfig({
5255
function createMenu(): IDocMenuNavs {
5356
return [
5457
{
55-
name: '使用指南',
58+
name: {
59+
CN: '使用指南',
60+
EN: 'Guide',
61+
},
5662
items: [
5763
{
58-
title: '介绍',
64+
title: {
65+
CN: '介绍',
66+
EN: 'introduce',
67+
},
5968
path: 'introduce',
6069
},
6170
{
62-
title: '快速开始',
71+
title: {
72+
CN: '快速开始',
73+
EN: 'quick',
74+
},
6375
path: 'quick',
6476
},
6577
],
6678
},
6779
{
68-
name: '基础功能',
80+
name: {
81+
CN: '基础功能',
82+
EN: 'Base Feature',
83+
},
6984
items: [
7085
{
71-
title: '基本配置',
86+
title: {
87+
CN: '基本配置',
88+
EN: 'base config ',
89+
},
7290
path: 'base',
7391
},
7492
{
75-
title: '约定式路由',
93+
title: {
94+
EN: 'convention route',
95+
CN: '约定式路由',
96+
},
7697
path: 'route',
7798
},
7899
{
79-
title: '全局样式',
100+
title: {
101+
CN: '全局样式',
102+
EN: 'globale style',
103+
},
80104
path: 'style',
81105
},
82106
],
83107
},
84108
{
85-
name: '高级功能',
109+
name: {
110+
CN: '高级功能',
111+
EN: 'Senior Feature',
112+
},
86113
items: [
87114
{
88-
title: 'markdown语法扩展',
115+
title: {
116+
CN: 'markdown语法扩展',
117+
EN: 'markdown expand',
118+
},
89119
path: 'markdown-expand',
90120
},
91121
],

‎packages/doc/docs/advanced/markdown-expand-EN.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Markdown Syntax Extension
2+
3+
### Based on markdown-it
4+
5+
antmjs Doc is based on markdown-it to parse markdown content. We can use the plugin mechanism of `markdown-it` to extend the syntax, such as:
6+
7+
- [Subscript (markdown-it-sub)](https://github.com/markdown-it/markdown-it-sub)
8+
- [Superscript (markdown-it-sup)](https://github.com/markdown-it/markdown-it-sup)
9+
- [Footnote (markdown-it-footnote)](https://github.com/markdown-it/markdown-it-footnote)
10+
- [Definition list (markdown-it-deflist)](https://github.com/markdown-it/markdown-it-deflist)
11+
- [Abbreviation (markdown-it-abbr)](https://github.com/markdown-it/markdown-it-abbr)
12+
- [Emoji (markdown-it-emoji)](https://github.com/markdown-it/markdown-it-emoji)
13+
- [Custom container (markdown-it-container)](https://github.com/markdown-it/markdown-it-container)
14+
- [Insert (markdown-it-ins)](https://github.com/markdown-it/markdown-it-ins)
15+
- [Mark (markdown-it-mark)](https://github.com/markdown-it/markdown-it-mark)
16+
- ... and [others](https://www.npmjs.com/search?q=markdown-it%20plugin)
17+
18+
### Usage
19+
20+
In antmjs.config, use it as follows:
21+
22+
```ts
23+
import markdownItSub from 'markdown-it-sub'
24+
import type { IDocsConfig } from '@antmjs/doc'
25+
26+
const docs: IDocsConfig = {
27+
markdownPlugins: [markdownItSub],
28+
}
29+
// ...
30+
```

‎packages/doc/docs/base/base__EN.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Basic Configuration
2+
3+
### Basic Information
4+
5+
Page title and logo
6+
7+
```ts
8+
export default defineConfig({
9+
docs: {
10+
title: 'antmjs Doc',
11+
logo: 'xxxxx',
12+
},
13+
})
14+
```
15+
16+
### Document Source and Output
17+
18+
The document source file path `src` is set to `./docs` by default, relative to the root directory where the command is executed.
19+
20+
```ts
21+
export default defineConfig({
22+
docs: {
23+
src: join(CWD, './docs'),
24+
output: 'doc_build',
25+
},
26+
})
27+
```
28+
29+
### Top Navigation Links
30+
31+
Use `headerLinks` to set the top navigation of the page.
32+
33+
- Regular icon navigation `type:image`
34+
35+
```ts
36+
export default defineConfig({
37+
docs: {
38+
headerLinks: [
39+
{
40+
type: 'image',
41+
title: 'https://b.yzcdn.cn/vant/logo/github.svg',
42+
url: 'https://github.com',
43+
},
44+
],
45+
},
46+
})
47+
```
48+
49+
- Regular icon navigation `type:text`
50+
51+
```ts
52+
export default defineConfig({
53+
docs: {
54+
headerLinks: [
55+
{
56+
type: 'text',
57+
title: 'github',
58+
url: 'https://github.com',
59+
},
60+
],
61+
},
62+
})
63+
```
64+
65+
- Regular icon navigation `type:select`
66+
67+
```ts
68+
export default defineConfig({
69+
docs: {
70+
headerLinks: [
71+
{
72+
type: 'select',
73+
title: 'More',
74+
options: [
75+
{
76+
title: 'antmjs',
77+
github: 'https://github.com/AntmJS/antm',
78+
},
79+
],
80+
},
81+
],
82+
},
83+
})
84+
```
85+
86+
### Menu Configuration
87+
88+
The menu currently only supports two-level menus. Due to `require cache`, the menu configuration is stored separately, which may not support hot updates.
89+
90+
```ts
91+
import type { IMenuNavs } from '@antmjs/types'
92+
93+
const menu: IMenuNavs = [
94+
{
95+
name: 'User Guide',
96+
items: [
97+
{
98+
title: 'Introduction',
99+
path: 'introduce',
100+
},
101+
],
102+
},
103+
]
104+
105+
export default defineConfig({
106+
docs: {
107+
menu: menu,
108+
},
109+
})
110+
```
111+
112+
### Mobile Display
113+
114+
The main configuration is as follows:
115+
116+
- `url`: divided into development and production environments
117+
- `noMate`: set redirection when there is no mapping relationship for the URL
118+
- `transform`: define mapping rules
119+
120+
```ts
121+
export default defineConfig({
122+
docs: {
123+
simulator: {
124+
url: {
125+
development: 'http://10.254.9.214:10086',
126+
production: '/vantui/main/mobile.html',
127+
},
128+
transform: (url) => `#/pages/${url}/index`,
129+
noMate: {
130+
urls: [
131+
'quickstart',
132+
'custom-style',
133+
'home',
134+
'theme',
135+
'use-in-react',
136+
'contributing',
137+
'v2-to-v3',
138+
'comments',
139+
'premium',
140+
],
141+
redirect: '#/pages/dashboard/index',
142+
},
143+
},
144+
},
145+
})
146+
```

‎packages/doc/docs/base/route__EN.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Convention-based Routing
2+
3+
### What is Convention-based Routing
4+
5+
Antm.js Doc uses file system routing, where the file path of a page is simply mapped to its routing path. This makes the routing of the entire project very intuitive.
6+
7+
For example, if there is a file named `foo.md` in the `docs` directory, its routing path would be `/foo`.
8+
9+
> The browser console will print `DOC_ROUTERS` by default, which shows all generated routing pages.
10+
11+
### Mapping Rules
12+
13+
Antm.js Doc will automatically scan the root directory and all subdirectories and map the file path to its routing path. For example, if you have the following file structure:
14+
15+
```markdown
16+
docs
17+
├── foo
18+
│ └── bar.md
19+
└── foo.md
20+
```
21+
22+
The mapping rules are as follows:
23+
24+
| File Path | Routing Path |
25+
| -------------------- | ------------ |
26+
| `docs/foo.md` | `/foo` |
27+
| `docs/foo/bar.md` | `/foo/bar` |
28+
| `docs/abc/README.md` | `/abc` |
29+
30+
### Custom Rules
31+
32+
Custom routing rules can be defined through configuration.
33+
34+
`src` configuration specifies the root path of the documentation files, which can be a string or number.
35+
36+
`route` configuration includes:
37+
38+
- `exclude`: markdown files that do not need to be converted into documentation, supports `/abc/*.md` syntax, please use full path matching.
39+
- `redirect`: the path to redirect to when there is no matching route or for the root route `/`.
40+
- `type`: type of routing, either `hash` or `history`.
41+
- `level`: controls the length of the routing path. For example, when level is set to 1, `docs/foo/bar.md` is mapped to `/bar`. There may be **routing conflicts**, so use with caution.
42+
43+
```js
44+
import { defineConfig } from '@antmjs/types'
45+
46+
export default defineConfig({
47+
docs: {
48+
src: ['./doc'],
49+
route: {
50+
level: 1,
51+
exclude: [join(CWD, '/a/*.md')],
52+
redirect: '/introduce',
53+
type: 'hash',
54+
},
55+
},
56+
})
57+
```

‎packages/doc/docs/base/style__EN.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Custom Global Styles
2+
3+
In some cases, you may need to add some global styles on top of the theme UI. The framework provides a configuration item `globalStyles` to achieve this function.
4+
5+
### Usage
6+
7+
Add the following configuration to `antm.config.ts`:
8+
9+
```ts
10+
import { defineConfig } from '@antmjs/types'
11+
import path from 'path'
12+
13+
export default defineConfig({
14+
doc: {
15+
globalStyles: [join(CWD, './styles/index.css')],
16+
},
17+
})
18+
```
19+
20+
Currently, only a small number of CSS variables are supported. An example of the style code is as follows:
21+
22+
```less
23+
:root {
24+
--primary-color: rgb(78, 78, 200);
25+
--primary-back-color: #e5e4f8;
26+
--header-back-color: rgb(78, 78, 200);
27+
}
28+
29+
.antm-docs-menu {
30+
width: 200px;
31+
}
32+
```

‎packages/doc/docs/start/introduce__EN.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Introduction
2+
3+
### Overview
4+
5+
Antm.js Doc is a framework for building technical documentation in the simplest and most efficient way for front-end technologies. It supports the `h1` and `h3` tags in Markdown format, as shown below:
6+
7+
```markdown
8+
# Main Title
9+
10+
### Subtitle
11+
```
12+
13+
It supports common documentation building requirements, including:
14+
15+
- Markdown syntax extension
16+
- Custom global styles
17+
- Full-text search
18+
19+
In the future, it will support:
20+
21+
- Custom themes
22+
- Header navigation menu
23+
- Resolution adaptation
24+
25+
### Features
26+
27+
#### Support for Markdown syntax extension
28+
29+
Antm.js Doc extends Markdown syntax based on `MarkdownItPlugin`.
30+
31+
For more information, please refer to [Markdown Syntax Extension](/#/markdown-expand).

0 commit comments

Comments
 (0)