@oiij/markdown-it 0.0.11 → 0.0.13

package/README.md

@@ -1,12 +1,90 @@
-# Use Markdown-it
+# Use Markdown-it 🚀
 
 [![NPM version](https://img.shields.io/npm/v/@oiij/markdown-it)](https://www.npmjs.com/package/@oiij/markdown-it)
-[![MIT-license](https://img.shields.io/npm/l/@oiij/markdown-it)](https://github.com/Eiog/@oiij/markdown-it/blob/main/LICENSE)
+[![MIT-license](https://img.shields.io/npm/l/@oiij/markdown-it)](https://github.com/oiij/use/blob/main/packages/markdown-it/LICENSE)
 
-## Usage
+## 项目简介 📦
+
+Use Markdown-it 是基于 markdown-it 的 Vue 3 封装，提供便捷的 Markdown 渲染功能，帮助开发者在应用中快速渲染 Markdown 内容。
+
+## 功能特点 ✨
+
+### Markdown 渲染 📝
+
+- ✨ 支持 CommonMark 和 GitHub Flavored Markdown
+- 🎨 提供丰富的插件生态
+- ⚡ 高性能渲染引擎
+
+### 模块化设计 🧩
+
+- 📁 采用模块化架构，组件独立封装
+- 📦 支持按需导入，减小打包体积
+- 🔧 清晰的文件结构，易于维护和扩展
+
+### 类型安全 🔒
+
+- 📝 完整的 TypeScript 类型定义
+- 💡 提供准确的类型推断和代码提示
+- 🎯 支持 Vue 3 的 Composition API 类型系统
+
+### 轻量高效 ⚡
+
+- 🚀 核心代码精简，无额外依赖
+- 🏃 优化的性能表现，最小化运行时开销
+- 📦 支持 Tree Shaking，进一步减小打包体积
+
+## 安装 📥
+
+### 使用 pnpm 🐱
 
 ```bash
 pnpm add @oiij/markdown-it
 ```
 
-[在线文档](https://oiij-use.vercel.app/examples/markdown-it/started)
+### 使用 npm 📦
+
+```bash
+npm install @oiij/markdown-it
+```
+
+### 使用 yarn 🧶
+
+```bash
+yarn add @oiij/markdown-it
+```
+
+## 快速开始 🌟
+
+### 基础使用
+
+```vue
+<script setup>
+import { UseMarkdownIt } from '@oiij/markdown-it'
+</script>
+
+<template>
+  <UseMarkdownIt content="# Hello World" />
+</template>
+```
+
+## 在线文档 📚
+
+[在线文档](https://oiij-use.vercel.app/markdown-it/markdown-it) 📖
+
+## 贡献指南 🤝
+
+欢迎贡献代码、报告问题或提出新功能建议！
+
+1. Fork 本仓库 🍴
+2. 创建您的特性分支 (`git checkout -b feature/amazing-feature`) 🌿
+3. 提交您的更改 (`git commit -m 'Add some amazing feature'`) 💾
+4. 推送到分支 (`git push origin feature/amazing-feature`) 🚀
+5. 打开一个 Pull Request 📥
+
+## 许可证 📄
+
+本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情 📑
+
+## 联系方式 📞
+
+- GitHub: [https://github.com/Eiog/@oiij/markdown-it](https://github.com/Eiog/@oiij/markdown-it) 🌟

package/dist/index.d.mts

@@ -3,19 +3,63 @@ import * as vue0 from "vue";
 import { MaybeRefOrGetter, TemplateRef } from "vue";
 
 //#region src/index.d.ts
+/**
+ * 使用 MarkdownIt 选项类型
+ */
 type UseMarkDownItOptions = {
+  /**
+   * Markdown 内容
+   */
   value?: MaybeRefOrGetter<string>;
+  /**
+   * 是否手动渲染
+   * @default false
+   */
   manual?: boolean;
+  /**
+   * 是否使用 DOM 净化
+   * @default true
+   */
   domPurify?: boolean;
+  /**
+   * MarkdownIt 选项
+   */
   markdownItOptions?: Options;
 };
+/**
+ * 使用 MarkdownIt
+ *
+ * @param templateRef - 渲染容器的模板引用
+ * @param options - MarkdownIt 选项
+ * @returns MarkdownIt 实例和工具方法
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { ref } from 'vue'
+ * import { useMarkdownIt } from '@oiij/markdown-it'
+ *
+ * const content = ref('# 标题\n\n这是一段 **Markdown** 内容')
+ * const { html, render } = useMarkdownIt({
+ *   value: content
+ * })
+ * </script>
+ *
+ * <template>
+ *   <div v-html="html"></div>
+ * </template>
+ * ```
+ */
 declare function useMarkdownIt(templateRef?: TemplateRef<HTMLElement>, options?: UseMarkDownItOptions): {
   templateRef: Readonly<vue0.ShallowRef<HTMLElement | null>> | undefined;
-  valueRef: vue0.Ref<string | undefined, string | undefined>;
-  htmlRef: vue0.Ref<string, string>;
+  value: vue0.Ref<string | undefined, string | undefined>;
+  html: vue0.Ref<string, string>;
   markdownItInst: markdownIt;
   render: (value?: string) => string;
 };
+/**
+ * MarkdownIt 返回值类型
+ */
 type MarkdownItReturns = ReturnType<typeof useMarkdownIt>;
 //#endregion
 export { MarkdownItReturns, UseMarkDownItOptions, useMarkdownIt };

package/dist/index.mjs

@@ -17,6 +17,30 @@ function watchRefOrGetter(value, callback) {
 
 //#endregion
 //#region src/index.ts
+/**
+* 使用 MarkdownIt
+*
+* @param templateRef - 渲染容器的模板引用
+* @param options - MarkdownIt 选项
+* @returns MarkdownIt 实例和工具方法
+*
+* @example
+* ```vue
+* <script setup>
+* import { ref } from 'vue'
+* import { useMarkdownIt } from '@oiij/markdown-it'
+*
+* const content = ref('# 标题\n\n这是一段 **Markdown** 内容')
+* const { html, render } = useMarkdownIt({
+*   value: content
+* })
+* <\/script>
+*
+* <template>
+*   <div v-html="html"></div>
+* </template>
+* ```
+*/
 function useMarkdownIt(templateRef, options) {
 	const { value, manual = false, domPurify = true, markdownItOptions } = options ?? {};
 	const valueRef = watchRefOrGetter(value, () => {
@@ -24,8 +48,23 @@ function useMarkdownIt(templateRef, options) {
 	});
 	const htmlRef = ref("");
 	const markdownItInst = markdownIt({ ...markdownItOptions });
+	/**
+	* 渲染 Markdown 内容
+	*
+	* @param value - Markdown 内容
+	* @returns 渲染后的 HTML 内容
+	*
+	* @example
+	* ```ts
+	* import { useMarkdownIt } from '@oiij/markdown-it'
+	*
+	* const { render } = useMarkdownIt()
+	* const html = render('# 标题')
+	* console.log(html) // <h1>标题</h1>
+	* ```
+	*/
 	function render(value) {
-		if (value) valueRef.value = value;
+		if (value !== void 0 && value !== valueRef.value) valueRef.value = value;
 		const mdValue = markdownItInst.render(valueRef.value ?? "");
 		htmlRef.value = domPurify ? DOMPurify.sanitize(mdValue) : mdValue;
 		if (templateRef?.value) templateRef.value.innerHTML = htmlRef.value;
@@ -39,8 +78,8 @@ function useMarkdownIt(templateRef, options) {
 	});
 	return {
 		templateRef,
-		valueRef,
-		htmlRef,
+		value: valueRef,
+		html: htmlRef,
 		markdownItInst,
 		render
 	};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oiij/markdown-it",
   "type": "module",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "A Vue Composable for markdown-it",
   "author": "oiij",
   "license": "MIT",