Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/logicspark/vitepress-theme-api
Simple Vitepress Theme for API Documentation
https://github.com/logicspark/vitepress-theme-api
vite vitepress vitepress-blog vitepress-doc vitepress-theme vuejs3 vuepress vuepress-theme
Last synced: 11 days ago
JSON representation
Simple Vitepress Theme for API Documentation
- Host: GitHub
- URL: https://github.com/logicspark/vitepress-theme-api
- Owner: logicspark
- License: mit
- Created: 2023-07-14T09:05:54.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-10-11T09:05:01.000Z (about 1 year ago)
- Last Synced: 2024-10-28T16:45:06.818Z (17 days ago)
- Topics: vite, vitepress, vitepress-blog, vitepress-doc, vitepress-theme, vuejs3, vuepress, vuepress-theme
- Language: CSS
- Homepage:
- Size: 29.9 MB
- Stars: 32
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-vitepress-v1 - vitepress-theme-api - An API document theme for Vitepress (:art: Themes / Community Themes)
README
Vitepress Theme API
Developed by [Logic Spark](https://logicspark.com) team
[][package-url]
[][vue-url]
[](https://github.com/logicspark/awesome-social-button/blob/main/LICENSE)
## :sunglasses: Video Demo
DividePage Component Demo
https://github.com/logicspark/vitepress-api-document-theme/assets/135820109/643060a0-94d9-43a6-91f0-bcea95f74bff
Here is the link to the live [demo](https://docs.logicspark.com). Have fun exploring!
## :building_construction: Built With
1. [![Typescript][typescript]][typescript-url]
2. [![Vue][vue]][vue-url]
3. [![HTML][html]][html-url]
4. [![CSS][css]][css-url]
5. [![Vite][vite]][vite-url]
## :rocket: Getting Started
Learn what is required before using Vitepress API Document theme and how to install it quickly. Let's get started!
### Prerequisite
This library is created with Vite + Vue3 + TypeScript. To start using this library, please make sure to install the following external libraries first:
- [Node.js](https://nodejs.org/en)
- [Vitepress](https://vitepress.dev/)
_Support Node.js 18.12.0 (LTS) and above_
### Installation
There are a few ways you can install Vitepress API Document theme, namely npm, yarn and pnpm. If you install via npm, here is a single cmd to install this library
```sh
npm install vitepress-theme-api
```
#### Other options
- yarn
```sh
yarn add vitepress-theme-api
```
- pnpm
```sh
pnpm add vitepress-theme-api
```
## :fire: Usage
You will need to import component tags and CSS. Without the CSS import, the API Document theme will not display correctly.
### Import Component from Theme
You will need to import `DividePage` component to divide the main content into left and right so that the API document theme can be rendered.
```js
import {DividePage} from 'vitepress-theme-api';
```
### Import CSS from Theme
Per Vitepress's [Setup Wizard](https://vitepress.dev/guide/getting-started#setup-wizard), there are three options
1. Default Theme
2. Default Theme + Customization
3. Custom Theme
#### Option 1: Default Theme
You can import the file within `` of each .md file that you plan to use the imported component.
```js
<style>@import './node_modules/vitepress-theme-api/dist/style.css';
```
_Note_: Do not add `scoped` in `` because the css will not work.
<div align="right">
([See example](example/default-theme/index.md))
</div>
#### Option2: Default Theme + Customization
You must import the style in the CSS file from the theme directory.
```css
@import "../../node_modules/vitepress-theme-api/theme/style.css";
```
<div align="right">
([See example](example/default-theme-and-custom/))
</div>
#### Option 3: Custom Theme
Please follow Option 2's instruction
<div align="right">
([See example](example/custom-theme/))
</div>
### Implementation of Tags
There are two tags, namely:
- `<template #left>` - For the left side of the main content, you can write API descriptions like query parameters or return properties.
- `<template #right>` - For the right side of the main content, you can add sample codes like API request and response.
```js
<DividePage>
<template #left>
// Add content here. Both html and markdown are supported.
</template>
<template #right>
// Add content here. Both html and markdown are supported.
</template>
</DividePage>
```
_Note_: When writing markdown, please leave a line so that it displays a markdown instead of text like the example above.
### Component Attribute
| Prop | Type | Required | Description |
| --------- | -------- | -------- | ----------------------------------------------------------- |
| **`top`** | `number` | Optional | Set vertical position of `<template #right>` Default is `0` |
## Implementation of Styled Ordered Number List
If you would like to style ordered number list to make your document easier to read, here is a code example:
Class name is order-list-I.
```md
1. First Item
1. First Item
1. First Item
{.order-list-I} // if you omit this, it will display default md style
```
## Implementation of Styled Container of Markdown Extension
If you would like to style custom containers so that users can review your document quickly and easily, here is the selection of unicode representations
> i , ⓘ , ⚠ ,❕ and ▶
Add an attribute to customize the container’s color, icon and border
```md
::: warning {icon-type=warning} //add an icon
test
:::
::: warning {icon-type=warning-bordered} //add an icon, color and border
test
:::
```
_Note_: If you want to adjust these class, you can can change it in <a href="#import-css-from-theme">Import css from theme</a>.
For the full sample .md file in accordance with the live demo, please see our [example](example/default-theme-and-custom/index.md) directory.
## :books: License
Distributed under the MIT License. See [`LICENSE`](https://github.com/logicspark/vitpress-theme-api/blob/main/LICENSE) for more information.
Vitepress is licensed under MIT License. Click [here](https://github.com/vuejs/vitepress/blob/main/LICENSE) for more information.
## :pray: Acknowledgement
- [Vitepress](https://vitepress.dev/)
- [Img Shields](https://shields.io)
[Vitepress-url]: https://vitepress.dev/
[TypeScript]: https://img.shields.io/badge/typescript-007ACC?style=for-the-badge&logo=typescript&logoColor=white
[typescript-url]: https://www.typescriptlang.org/
[Html]: https://img.shields.io/badge/html5-%23E34F26.svg?style=for-the-badge&logo=html5&logoColor=white
[html-url]: https://www.w3schools.com/html/
[Css]: https://img.shields.io/badge/css3-%231572B6.svg?style=for-the-badge&logo=css3&logoColor=white
[css-url]: https://www.w3schools.com/css/
[Vue]: https://img.shields.io/badge/vue.js-42B883?style=for-the-badge&logo=vuedotjs&logoColor=white
[Vue-url]: https://vuejs.org/
[Vite]: https://img.shields.io/badge/vite-%23646CFF.svg?style=for-the-badge&logo=vite&logoColor=white
[vite-url]: https://vitejs.dev/
[package-url]: https://www.npmjs.com/package/vitepress-theme-api