定制化 Docsify 文档框架实战分享

🌟 定制化 Docsify 文档框架实战分享

在构建前端文档平台时,我们希望拥有更友好的用户界面、便捷的搜索、清晰的目录导航以及实用的代码复制功能。借助 Docsify,我实现了以下几个方面的定制优化,分享给大家 🙌

📌 本文基于 Docsify + 插件实现,包括自定义 JavaScript 功能注入与样式优化。

🎨 UI 界面改造

仿 CSDN 布局模式及 UI,去除左侧菜单收展,左侧菜单只展示文档目录,右侧增加搜索及文档内容目录,整体看上去更简洁点,当然你可以随意改你喜欢的样式;

原始 UI

改造后 UI

🎫 版本控制

通过动态更改文档资源根路径实现文档版本切换;

配置:

javascript 复制代码
 basePath: sessionStorage.getItem("version") || "/docs/v1",

HTML 实现:

html 复制代码
<div class="versionBox">
  <label for="version">版本:</label>
  <select id="version" name="version" onchange="changeBasePath(this)">
    <option value="a">v1</option>
    <option value="b">v2</option>
  </select>
</div>

JS :

javascript 复制代码
function changeBasePath(select) {
  var selectedValue = select.value;
  if (selectedValue === "a") {
    sessionStorage.setItem("version", "/docs/v1");
    sessionStorage.setItem("ver", "a");
  } else if (selectedValue === "b") {
    sessionStorage.setItem("version", "/docs/v2");
    sessionStorage.setItem("ver", "b");
  }

  window.location.reload();
}

🔍 搜索功能配置

通过引入 search.min.js 插件,并配置如下,实现了全文搜索功能,支持关键词高亮匹配与模糊查询。

配置代码:

javascript 复制代码
search: {
  maxAge: 86400000, // 一天缓存
  paths: "auto",
  placeholder: "请输入关键词",
  noData: "未检索到相关内容!",
  depth: 2,
  hideOtherSidebarContent: false
}

📚 自定义浮动目录(锚点导航)

Docsify 默认只提供左侧文档目录,现需要实现一个右侧的文档内容导航目录,通过自定义插件读取文档内容生成目录。

实现逻辑包括:

  • 获取 .content 中所有 h1 ~ h3

  • 动态生成目录列表并缩进

  • 自动隐藏无标题页面目录

  • 修复锚点跳转偏移问题(插入空的

核心插件代码:

javascript 复制代码
hook.doneEach(function () {
  var floatingToc = document.querySelector(".floating-toc");
  if (!floatingToc) {
    floatingToc = document.createElement("div");
    floatingToc.className = "floating-toc";
    document.body.appendChild(floatingToc);
    var tocHeader = document.createElement("h2");
    tocHeader.textContent = "目录";
    floatingToc.appendChild(tocHeader);
  }

  floatingToc.innerHTML = "<h2>目录</h2>";
  var currentUrl = window.location.href.split("?")[0];
  var content = document.querySelector(".content");

  if (content) {
    var headers = content.querySelectorAll("h1, h2, h3");
    if (headers.length > 1) {
      floatingToc.style.display = "block";
      var tocList = document.createElement("ul");
      floatingToc.appendChild(tocList);
      headers.forEach(function (header) {
        var li = document.createElement("li");
        var level = parseInt(header.tagName.substring(1)) - 1;
        li.style.marginLeft = level * 20 + "px";

        var anchorLink = document.createElement("a");
        anchorLink.href = currentUrl + "#" + header.id;
        anchorLink.textContent = header.textContent;
        li.appendChild(anchorLink);
        tocList.appendChild(li);
      });
    } else {
      floatingToc.style.display = "none";
    }

    var anchors = document.querySelectorAll("h2[id],h3[id],h4[id]");
    anchors.forEach(function (anchor) {
      var fixAnchorDiv = document.createElement("div");
      fixAnchorDiv.className = "fix-anchor";
      fixAnchorDiv.id = anchor.id;
      anchor.parentNode.insertBefore(fixAnchorDiv, anchor);
      anchor.id = "";
    });
  } else {
    floatingToc.style.display = "none";
  }
});

📋 代码复制功能

我们使用了 docsify-copy-code 插件,给所有代码块添加"点击复制"按钮。

引入插件:

javascript 复制代码
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>

配置:

vbnet 复制代码
copyCode: {
buttonText: "点击复制",
errorText: "Error",
successText: "复制成功"
}

✅ 总结

通过简单的 HTML + JS + 插件组合,我们在原始 Docsify 的基础上实现了以下功能:

  • 多版本切换支持

  • 搜索功能优化

  • 浮动目录导航

  • 一键复制代码

  • UI 更加美观清晰

🧑‍💻 后续计划

  • 🌐 支持多语言国际化(i18n)

  • 🌗 主题切换(深色 / 浅色模式)

  • 🚀 与 GitHub Actions 等 CI/CD 集成自动部署

源码地址

github.com/Bing-b/docs

相关推荐
我在北京coding40 分钟前
TypeError: Cannot read properties of undefined (reading ‘queryComponents‘)
前端·javascript·vue.js
前端开发与ui设计的老司机1 小时前
UI前端与数字孪生结合实践探索:智慧物流的货物追踪与配送优化
前端·ui
全能打工人1 小时前
前端查询条件加密传输方案(SM2加解密)
前端·sm2前端加密
翻滚吧键盘2 小时前
vue绑定一个返回对象的计算属性
前端·javascript·vue.js
秃了也弱了。2 小时前
Chrome谷歌浏览器插件ModHeader,修改请求头,开发神器
前端·chrome
乆夨(jiuze)2 小时前
记录H5内嵌到flutter App的一个问题,引发后面使用fastClick,引发后面input输入框单击无效问题。。。
前端·javascript·vue.js
忧郁的蛋~3 小时前
HTML表格导出为Excel文件的实现方案
前端·html·excel
小彭努力中3 小时前
141.在 Vue 3 中使用 OpenLayers Link 交互:把地图中心点 / 缩放级别 / 旋转角度实时写进 URL,并同步解析显示
前端·javascript·vue.js·交互
然我3 小时前
别再只用 base64!HTML5 的 Blob 才是二进制处理的王者,面试常考
前端·面试·html
NanLing3 小时前
【纯前端推理】纯端侧 AI 对象检测:用浏览器就能跑的深度学习模型
前端