Skip to content

Commit

Permalink
docs: ✏️ update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@huyikai
huyikai committed Dec 21, 2023
1 parent 92e69e9 commit 7c346ff
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 218 deletions.
118 changes: 15 additions & 103 deletions README-zh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,22 @@

在 [vitepress](https://vitepress.vuejs.org) 基础上优化使用体验。

## 功能
## 特性

- 导航：根据文件目录自动生成导航栏。
- 侧边栏：根据文件目录自动生成侧边栏。
- 脚手架：指导完成初始化操作。
- 本地 CMS: 运行本地 CMS 以简化内容管理。
- 导航栏：根据文件目录自动生成导航栏。
- 侧边栏：根据文件目录自动生成侧边栏。
- CMS: 运行本地 CMS 以简化内容管理。
- 首页：可以自定义的首页。
- 国际化：根据国际化配置自动生成对应的导航栏、侧边栏。

## 使用

请参阅 [vitepress-helper](https://huyikai.github.io/vitepress-helper/) 文档进行操作。

## 待办
## 短期计划

- 国际化兼容：修改边栏和导航栏生成方法以适应国际化设置。
- 文档：更详细的使用说明、适当的使用示例。
- CMS：
- Markdown 编辑器使用体验优化。
- 文件、目录移动以及拖拽移动。
Expand All @@ -27,103 +32,10 @@

## 长期计划

- 代码：增加单测以保证代码质量。
- 使用体验：优化 UI、使用逻辑、性能优化。
- 文档：提供双语文档、更详细的使用说明、适当的使用示例。
- 探究：
- 关注 vitepress 的更新，以保持功能和体验的同步。
- 对开发及使用过程中新的灵感进行规划。

## 使用

目前规划了两种使用方式： 1.使用脚手架初始化（推荐），开箱即用。 2.在已有的 vitepress 项目中添加依赖 `@huyikai/vitepress-helper`，并手动修改设置(config.js)和主题(theme)。

### 1. CLI

```shell
npx @huyikai/vitepress-helper init
```

将会被问到一些简单的问题：

```shell
# 项目名称 | Project Name
# 作者 | Author
# 版本号 | Version
# 是否需要本地 CMS ? | Do you need local CMS?
```

初始化完成后，您可以运行 `npm run dev` 进行预览，或者运行 `npm run cms` 进行内容管理。

### 2. 添加依赖

```shell
npm @huyikai/vitepress-helper
```

```javascript
// 修改 config.js
import vitepressHelper from '@huyikai/vitepress-helper';
export default async () => {
const instance: any = await vitepressHelper({
directory: 'docs',
collapsible: true
});
return {
...,
themeConfig:{
...,
nav:instance.nav,// 可以自行继续扩展。例：[...instance.nav,...otherNavArray]
sidebar:instance.sidebar // 可以自行继续扩展。例：[...instance.sidebar,...otherSidebarArray]
}
}
}
```

新建目录 `.vitepress/theme` ，新建文件 `home.vue`、`index.js`

#### home.vue

```vue
<script setup lang="ts">
import VPDoc from 'vitepress/dist/client/theme-default/components/VPDoc.vue';
import VPButton from 'vitepress/dist/client/theme-default/components/VPButton.vue';
</script>
<template>
<!-- 可以自定义任意内容，例： -->
<div>不积跬步无以至千里</div>
<!-- 此处的 VPDoc 组件将会渲染显示 docs 根目录中 index.md 中的内容。 -->
<VPDoc />
</template>
<style></style>
```

#### index.js

```javascript
import 'vitepress/dist/client/theme-default/styles/vars.css';
import 'vitepress/dist/client/theme-default/styles/base.css';
import 'vitepress/dist/client/theme-default/styles/utils.css';
import 'vitepress/dist/client/theme-default/styles/components/custom-block.css';
import 'vitepress/dist/client/theme-default/styles/components/vp-code.css';
import 'vitepress/dist/client/theme-default/styles/components/vp-code-group.css';
import 'vitepress/dist/client/theme-default/styles/components/vp-doc.css';
import 'vitepress/dist/client/theme-default/styles/components/vp-sponsor.css';

import Home from './home.vue';
import Layout from '@huyikai/vitepress-helper/theme/Theme.vue';
import VPBadge from 'vitepress/dist/client/theme-default/components/VPBadge.vue';

const theme = {
Layout,
enhanceApp: ({ app }) => {
app.component('Home', Home);
app.component('Badge', VPBadge);
}
};
export default theme;
```
- 测试：增加单测以保证代码质量。
- 体验：优化 UI、使用逻辑、性能优化。
- 维护：关注 vitepress 的更新，保持功能和体验的同步。
- 探究：对开发及使用过程中新的灵感进行规划。

## License

Expand Down
139 changes: 24 additions & 115 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,133 +2,42 @@

![npm-version](https://flat.badgen.net/npm/v/@huyikai/vitepress-helper) ![node-version](https://flat.badgen.net/npm/node/@huyikai/vitepress-helper) ![npm-downloads](https://flat.badgen.net/npm/dw/@huyikai/vitepress-helper) ![license](https://flat.badgen.net/npm/license/@huyikai/vitepress-helper)

[简体中文](./README-zh.md)
English | [简体中文](./README-zh.md)

## Brief
## Introduction

On the basis of [vitepress](https://vitepress.vuejs.org), optimize the user experience.
Optimized user experience based on [vitepress](https://vitepress.vuejs.org).

## Features

- Nav：Automatic generate the navigation bar based on the file directory
- Sidebar：Automatic generate the sidebar based on the file directory
- Cli：Guide to complete the initialization operation
- Integration CMS: Run a local CMS to make content management easier
- Home: Customizable home page

## ToDo

- Internationalization compatibility: Modify the methods for generating sidebar and navigation bar to adapt to internationalization settings.
- CMS:
- Optimize the experience of using Markdown editor.
- Move files and directories, and drag and drop.
- Import local files and batch processing.
- Import linked content.
- Version control.
- Management of static resources (images).

## Long-term Plan

- Code: Add unit tests to ensure code quality
- User Experience: Optimize UI, usage logic, and performance
- Documentation: Provide bilingual documentation, more detailed usage instructions, and appropriate usage examples
- Exploration:
- Pay attention to the updates of vitepress to keep the functions and experience synchronized.
- Plan for new inspirations during the development and usage process.
- CLI: Guide to complete the initialization operation.
- Nav: Automatically generate the navigation bar according to the file directory.
- Sidebar: Automatically generate the sidebar according to the file directory.
- CMS: Run local CMS to simplify content management.
- Homepage: Customizable homepage.
- Internationalization: Automatically generate corresponding navigation bar and sidebar according to internationalization configuration.

## Usage

Currently, two usage methods are planned:

1. Using the scaffolding initialization (recommended), you can get started directly.
2. Add the dependency `@huyikai/vitepress-helper` to an existing vitepress project and manually modify the config and theme.

### Cli Init

```shell
npx @huyikai/vitepress-helper init
```

You will be greeted with a few simple questions:

```shell
# Project Name
# Author
# Version
# Do you need local CMS?
```
Please refer to the [vitepress-helper](https://huyikai.github.io/vitepress-helper/) document for operation.

After the initialization is complete, you can run `npm run dev` to preview or run `npm run cms` to manage content.
## Short-term Plan

### 2. Add Dependency

```shell
npm @huyikai/vitepress-helper
```

```javascript
// Modify config.js
import vitepressHelper from '@huyikai/vitepress-helper';
export default async () => {
const instance: any = await vitepressHelper({
directory: 'docs',
collapsible: true
});
return {
...,
themeConfig:{
...,
nav:instance.nav,// You can continue to expand. Example: [...instance.nav,...otherNavArray]
sidebar:instance.sidebar // You can continue to expand. Example: [...instance.sidebar,...otherSidebarArray]
}
}
}
```

Create directory `.vitepress/theme`, and create files `home.vue` and `index.js`

#### home.vue

```vue
<script setup lang="ts">
import VPDoc from 'vitepress/dist/client/theme-default/components/VPDoc.vue';
import VPButton from 'vitepress/dist/client/theme-default/components/VPButton.vue';
</script>
<template>
<!-- You can customize any content, for example: -->
<div>A journey of a thousand miles begins with a single step</div>
<!-- The VPDoc component here will render the content of index.md in the docs root directory. -->
<VPDoc />
</template>
<style></style>
```

#### index.js

```javascript
import 'vitepress/dist/client/theme-default/styles/vars.css';
import 'vitepress/dist/client/theme-default/styles/base.css';
import 'vitepress/dist/client/theme-default/styles/utils.css';
import 'vitepress/dist/client/theme-default/styles/components/custom-block.css';
import 'vitepress/dist/client/theme-default/styles/components/vp-code.css';
import 'vitepress/dist/client/theme-default/styles/components/vp-code-group.css';
import 'vitepress/dist/client/theme-default/styles/components/vp-doc.css';
import 'vitepress/dist/client/theme-default/styles/components/vp-sponsor.css';
- Documentation: More detailed usage instructions, appropriate usage examples.
- CMS：
- Optimize the user experience of the Markdown editor.
- File and directory movement and drag-and-drop movement.
- Local file import, batch processing.
- Link content import.
- Version control.
- Static resource (image) management.

import Home from './home.vue';
import Layout from '@huyikai/vitepress-helper/theme/Theme.vue';
import VPBadge from 'vitepress/dist/client/theme-default/components/VPBadge.vue';
## Long-term Plan

const theme = {
Layout,
enhanceApp: ({ app }) => {
app.component('Home', Home);
app.component('Badge', VPBadge);
}
};
export default theme;
```
- Testing: Increase unit tests to ensure code quality.
- Experience: Optimize UI, usage logic, performance optimization.
- Maintenance: Pay attention to the updates of vitepress, keep the functions and experience synchronized.
- Exploration: Plan for new inspirations during the development and usage process.

## License

Expand Down

0 comments on commit 7c346ff

Please sign in to comment.