简体中文 | English
Demo address:
Library Complete Template
This is a javascript library project development template with a complete infrastructure developed in typescript to help you quickly build a javascript library that automatically generates documents.
Features
- Out of the box, complete infrastructure, no complex configuration
- Developing with typescript, we all like type
- Super fast, built with vite, enjoy the super fast experience brought by vite
- Comments are documents, Output markdown documents automatically using typedoc and typedoc-plugin-markdown. And give it to vitepress to drive
- Use vitest for unit testing, a friendlier testing experience, and support for ui mode
Example
Here is a template for the project:
-live2d Kanban girl oh-my-live2d
Use templates
Create the template locally
- you can use [vitepress - SSG] (https://github.com/hacxy/vitepress-ssg) project creation to your local rapidly
When executing the create command, you can specify the project name and template name through the options
sh
# npm 7+, requires additional double dashes:
npm i vitepress-ssg@latest
# yarn:
yarn add vitepress-ssg my-utils
# pnpm:
pnpm i vitepress-ssg my-utils --template library-complete
### Install dependencies
```sh
cd my-utils
npm install
` ` `
### Development
- Development mode:
This will turn on the listening mode to package the ts file into the dist directory
```sh
npm run dev
` ` `
- Package the production environment code
```sh
npm run build
` ` `
- Run unit tests
```sh
npm run test
` ` `
- Run unit tests with a visual interface
```sh
npm run test:ui
` ` `
- Run the browser environment demo
```sh
npm run demo:web
` ` `
- Run the node environment demo
```sh
npm run demo:node
` ` `
- Development documentation
```sh
npm run docs:dev
` ` `
- Package document
```sh
npm run docs:build
` ` `
### Release
Execute command, will use [release - it] (https://github.com/release-it/release-it) tools
```sh
npm run release |
npm publish
` ` `
## How is the document generated
When executing 'npm run docs:dev',typedoc turns on listening mode and generates markdown documents to the 'docs/src' directory based on all exported methods, while vitepress development mode starts. You can preview your document at <http://localhost>
Document content can also be added in the method of annotation, but need to pay attention to, the comment should be in accordance with the [typedoc] (https://typedoc.org/guides/overview/) to write the specification. Here's an example:
````ts
/ * *
* @name This is a way to say hello
* @group utility function
* @param name Indicates the name
* @returns
* @example
* ```ts
* console.log(sayHello('hacxy')); // Hello, hacxy!
* ' '
* /
export const sayHello = (name: string): string => {
return `Hello, ${name}! `;
};
` ` ` `
In this example, we have enriched the method in the title, grouping, parameter description, and code sample of the document, which should be familiar to you if you have written jsdoc comments before, but if you are new to it, Please refer to the [typedoc] (https://typedoc.org/guides/overview/) to learn how to write.
You can also use the markdown syntax in your comments. When you use the markdown syntax, the markdown content is rendered directly into the document.
The tag role used in the above example:
- @name Method name
The group to which the @group method belongs. This property has additional effects on the side navigation bar of the document
- @param Parameter description
- @returns Indicates the return value
- @example Indicates a code example
You should not modify any files in the docs/src directory because these files are generated by typedoc. They will all eventually be driven by vitepress.
## Development specification
All modules should be exported in src/index.ts, so that vite can find this portal to build the correct js code for you, and typedoc can also generate documentation for modules through this portal.
typedoc: https://typedoc.org/ automatically generates documents based on code comments
typedoc-plugin-markdown: https://typedoc-plugin-markdown.org/docs outputs the document in markdown format
vite: https://vitejs.dev/
vitepress: https://vitepress.dev/ markdown document drive
vitest: https://vitest.dev/ unit testing tool
Release-it Indicates the code release tool