Vue 项目集成 Docsify 使用说明（1）

发布于：2025-07-04 ⋅ 阅读:(12) ⋅ 点赞:(0)

Vue 项目集成 Docsify 使用说明

操作步骤

1. 创建新的 Vue 页面承载 Docsify 模块

  • 在 src/views/frontend/ 下创建 DocsifyPage.vue
  • 用于 iframe 嵌入 Docsify 文档系统

2. 在 public 目录创建 Docsify 入口文件

public/
└── docs/
    ├── index.html
    ├── README.md
    ├── _sidebar.md
    ├── _navbar.md
    ├── _coverpage.md
    ├── guide/
    ├── api/
    ├── components/
    └── deploy/

3. 创建 README、侧栏、头部导航页面

📄 README.md

文档首页内容

📄 _sidebar.md

侧边栏导航

📄 _navbar.md

顶部导航栏

📄 _coverpage.md

封面页面（可不添加）

⚙️ 集成方案

方案一：iframe 嵌入（推荐）

简单、安全、与 Vue 主应用独立，避免依赖冲突。

DocsifyPage.vue 示例：

<!-- 
    文档管理
    功能：文档手册
    作者：自美新网
    更新时间：2025-07-01
-->

<template>
  <div class="docsify-page-container">
    <div class="docsify-wrapper">
      <iframe 
        ref="docsifyFrame"
        src="/docs/" 
        class="docsify-iframe"
        frameborder="0"
        scrolling="auto"
        @load="onIframeLoad">
      </iframe>
    </div>
    
    <!-- 加载状态 -->
    <div v-if="loading" class="loading-overlay">
      <div class="loading-spinner">
        <div class="spinner"></div>
        <p>正在加载文档...</p>
      </div>
    </div>
  </div>  
</template>

<script>
export default {
  name: 'DocsifyPage',
  data() {
    return {
      loading: true
    }
  },
  mounted() {
    console.log('Docsify page mounted');
    // 设置超时，防止加载过久
    setTimeout(() => {
      if (this.loading) {
        this.loading = false;
      }
    }, 5000);
  },
  methods: {
    // 文档加载完成
    onIframeLoad() {
      this.loading = false;
      console.log('Docsify iframe loaded successfully');
    },
    // 刷新文档
    refreshDocs() {
      // 检查iframe引用是否存在
      if (this.$refs.docsifyFrame) {
        // 显示加载状态
        this.loading = true;
        // 保存当前iframe的src地址
        const currentSrc = this.$refs.docsifyFrame.src;
        // 清空src以触发重新加载
        this.$refs.docsifyFrame.src = '';
        // 在下一个DOM更新周期中恢复src，实现刷新效果
        this.$nextTick(() => {
          this.$refs.docsifyFrame.src = currentSrc;
        });
      }
    }
  }
}
</script>

<style scoped>
.docsify-page-container {
  width: 100%;
  height: calc(100vh - 116px);
  display: flex;
  flex-direction: column;
  background-color: #f8f9fa;
}

.docsify-header {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  padding: 2rem;
  text-align: center;
  box-shadow: 0 2px 10px rgba(0,0,0,0.1);
}

.page-title {
  font-size: 2.5rem;
  font-weight: 700;
  margin: 0 0 0.5rem 0;
  text-shadow: 0 2px 4px rgba(0,0,0,0.3);
}

.page-description {
  font-size: 1.1rem;
  margin: 0;
  opacity: 0.9;
}

.docsify-wrapper {
  flex: 1;
  position: relative;
  overflow: hidden;
}

.docsify-iframe {
  width: 100%;
  height: 100%;
  border: none;
  background-color: white;
}

.loading-overlay {
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background-color: rgba(255, 255, 255, 0.9);
  display: flex;
  align-items: center;
  justify-content: center;
  z-index: 1000;
}

.loading-spinner {
  text-align: center;
  color: #667eea;
}

.spinner {
  width: 50px;
  height: 50px;
  border: 4px solid #f3f3f3;
  border-top: 4px solid #667eea;
  border-radius: 50%;
  animation: spin 1s linear infinite;
  margin: 0 auto 1rem auto;
}

@keyframes spin {
  0% { transform: rotate(0deg); }
  100% { transform: rotate(360deg); }
}

/* 响应式设计 */
@media (max-width: 768px) {
  .docsify-header {
    padding: 1.5rem 1rem;
  }
  
  .page-title {
    font-size: 2rem;
  }
  
  .page-description {
    font-size: 1rem;
  }
}
</style>

方案二：Vue 直接集成 Docsify

如果需要在 Vue 中动态加载 Docsify，可使用动态 script + window.$docsify 配置，但复杂度高，推荐 iframe 方式。

Docsify 目录配置

index.html 配置示例

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>文档手册 - 自美新网</title>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <meta name="description" content="自美新网技术文档与使用指南">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
  <style>
    /* 自定义样式（设置主题） */
    :root {
      --theme-color: #667eea;
      --theme-color-secondary: #764ba2;
    }
    
    /* 移动端优化 */
    @media screen and (max-width: 768px) {
      .github-corner {
        display: none;
      }
    }
  </style>
</head>
<body>
  <div id="app">加载中...</div>
  <script>
    window.$docsify = {
      name: '文档手册',
      repo: '',             // 如果有 GitHub 仓库，可以填写
      loadSidebar: true,    // 加载侧边栏
      loadNavbar: true,     // 加载导航栏
      subMaxLevel: 3,       // 侧边栏最大层级
      auto2top: true,       // 切换页面后自动跳转到页面顶部
      coverpage: false,     // 启用封面页
      onlyCover: false,     // 不仅显示封面页
      
      // 搜索配置
      search: {
        maxAge: 86400000, // 过期时间，单位毫秒，默认一天
        paths: 'auto',
        placeholder: '搜索文档...',
        noData: '未找到相关内容',
        depth: 3,
        hideOtherSidebarContent: false
      },
      
      // 分页导航
      pagination: {
        previousText: '上一页',
        nextText: '下一页',
        crossChapter: true,
        crossChapterText: true
      },
      
      // 代码复制
      copyCode: {
        buttonText: '复制',
        errorText: '复制失败',
        successText: '已复制'
      },
      
      // 字数统计
      count: {
        countable: true,
        fontsize: '0.9em',
        color: 'rgb(90,90,90)',
        language: 'chinese'
      },
      
      // 外链配置
      externalLinkTarget: '_blank'
    }
  </script>
  
  <!-- Docsify 核心 -->
  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
  
  <!-- 插件 -->
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/docsify-copy-code@2"></script>
  <script src="//cdn.jsdelivr.net/npm/docsify-count/dist/countable.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/docsify-pagination/dist/docsify-pagination.min.js"></script>
  
  <!-- 代码高亮 -->
  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-javascript.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-css.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-vue.min.js"></script>
</body>
</html>

设置“首页、侧边栏导航、顶部导航、封面（建议去掉）”

README.md / _sidebar.md / _navbar.md / _coverpage.md

README.md

# 欢迎使用文档手册

> 自美新网技术文档与使用指南

## 📚 文档简介

这里是自美新网的技术文档中心，包含了项目的使用指南、API 文档、开发规范等内容。

## 🚀 快速开始

- [安装指南](guide/installation.md)
- [快速上手](guide/quickstart.md)
- [配置说明](guide/configuration.md)

## 📖 主要内容

### 用户指南
- 基础功能介绍
- 高级功能使用
- 常见问题解答

### 开发文档
- API 接口文档
- 组件使用说明
- 开发规范

### 部署运维
- 环境配置
- 部署流程
- 监控告警

## 🔗 相关链接

- [项目主页](#)
- [GitHub 仓库](#)
- [问题反馈](#)

---

**更新时间：** 2025-01-01  
**版本：** v1.0.0

_sidebar.md

<!-- docs/_sidebar.md -->

* [首页](/)

* 用户指南
  * [安装指南](guide/installation.md)
  * [快速上手](guide/quickstart.md)
  * [配置说明](guide/configuration.md)

* API 文档
  * [用户接口](api/user.md)
  * [数据接口](api/data.md)
  * [文件接口](api/file.md)

* 组件文档
  * [基础组件](components/basic.md)
  * [表单组件](components/form.md)
  * [展示组件](components/display.md)

* 开发指南
  * [开发环境](dev/environment.md)
  * [代码规范](dev/standards.md)
  * [测试指南](dev/testing.md)

* 部署运维
  * [环境配置](deploy/environment.md)
  * [部署流程](deploy/process.md)
  * [监控告警](deploy/monitoring.md)

* [更新日志](changelog.md)
* [常见问题](faq.md)

_navbar.md

<!-- docs/_navbar.md -->

* 入门
  * [快速上手](guide/quickstart.md)
  * [安装指南](guide/installation.md)

* 配置
  * [基础配置](guide/configuration.md)
  * [高级配置](guide/advanced.md)

* [API](api/)
* [组件](components/)
* [更新日志](changelog.md)

_coverpage.md（封面页）

<!-- docs/_coverpage.md -->

![logo](https://via.placeholder.com/200x200/667eea/ffffff?text=LOGO)

# 自美新网 <small>1.0.0</small>

> 技术文档与使用指南

- 📚 完整的功能文档
- 🚀 简单易用的接口
- 💡 丰富的示例代码
- 🎨 优雅的界面设计

[GitHub](https://github.com/)
[开始阅读](README.md)

<!-- 背景色 -->
![color](#f0f0f0)

其他

  • 访问方式：
    在 Vue 路由中访问 /docsify 页面
    文档内容通过 iframe 加载 /docs/ 路径

  • 添加文档内容：
    在对应目录下创建 .md 文件
    更新 _sidebar.md 中的导航链接

  • 自定义配置：
    修改 index.html 中的 window.$docsify 配置
    调整 CSS 样式和主题颜色

实现效果

在这里插入图片描述

网站公告

今日签到

点亮在社区的每一天
去签到

热门文章

最新发布