给自己的项目发布一个文档吧

2023年5月10日 136点热度 0人点赞 0条评论

给自己的项目发布一个文档

Github Page配置

在上一篇，我们搭建了一个脚手架，方便我们更快的开始一个项目。这篇我们将使用github page给这个项目发布一个文档

我们可以在 github 仓库的 Setting-Pages界面进行文档的设置，例如我这个仓库，把文档源设置成了当前仓库master分支的/docs目录，之后我们只需要往这个目录下添加静态文件就可以在对应的site展示文档了。

使用Docsify

使用Docsify能更方便地发布文档，只需要编辑md文件即可修改页面信息，因此我们使用docsify来构建文档

安装

首先你需要安装node.js，这里就不细说了

然后npm i docsify-cli -g 全局安装docsify-cli工具

docsify init ./docs初始化文档，我们设置的github page源是docs目录，所以初始化的是docs目录

初始化成功后会看到docs目录下会有几个文件

index.html 入口文件
README.md 会做为主页内容渲染
.nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件

直接编辑README.me 就能更新文档内容了

本地查看

docsify serve docs即可在本地查看页面

配置

另外如果要对页面进行详细配置可以看官方文档和这篇文章，docsify，Docsify使用指南（打造最快捷、最轻量级的个人&团队文档） - 追逐时光者 - 博客园 (cnblogs.com)。

这里是我的配置文件以及最终效果

配置文件：https://github.com/weloe/go-web-demo/tree/master/docs

index.html

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <title>go-web-demo</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <meta name="description" content="Description">
    <meta name="viewport"
        content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
        
    <!-- 默认主题 -->
    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>

<body>
    <!-- 定义加载时候的动作 -->
    <div id="app" class="loading">加载中...</div>
    <script>
        window.$docsify = {
            // 项目名称
            name: 'go-web-demo',
            // 仓库地址，点击右上角的Github章鱼猫头像会跳转到此地址
            repo: 'https://github.com/weloe',
            // 侧边栏支持，默认加载的是项目根目录下的_sidebar.md文件
            loadSidebar: true,
            // 导航栏支持，默认加载的是项目根目录下的_navbar.md文件
            loadNavbar: true,
            // 封面支持，默认加载的是项目根目录下的_coverpage.md文件
            coverpage: false,
            // 最大支持渲染的标题层级
            maxLevel: 5,
            // 自定义侧边栏后默认不会再生成目录，设置生成目录的最大层级（建议配置为2-4）
            subMaxLevel: 4,
            // 小屏设备下合并导航栏到侧边栏
            mergeNavbar: true,
            /*搜索相关设置*/
            search: {
                maxAge: 86400000,// 过期时间，单位毫秒，默认一天
                paths: 'auto',// 注意：仅适用于 paths: 'auto' 模式
                placeholder: '搜索',              
                // 支持本地化
                placeholder: {
                    '/zh-cn/': '搜索',
                    '/': 'Type to search'
                },
                noData: '找不到结果',
                depth: 4,
                hideOtherSidebarContent: false,
                namespace: 'Docsify-Guide',
            }
        }
    </script>
    <!-- docsify的js依赖 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
    <!-- emoji表情支持 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
    <!-- 图片放大缩小支持 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>
    <!-- 搜索功能支持 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
    <!--在所有的代码块上添加一个简单的Click to copy按钮来允许用户从你的文档中轻易地复制代码-->
    <script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>
</body>

</html>

<style>
    .loading {
      
      position: relative;
      width: 50px;
      perspective: 200px;
    }
    
    .loading:before,
    .loading:after {
      position: absolute;
      width: 20px;
      height: 20px;
      content: "";
      animation: jumping 0.5s infinite alternate;
      background: rgba(0, 0, 0, 0);
    }
    
    .loading:before {
      left: 0;
    }
    
    .loading:after {
      right: 0;
      animation-delay: 0.15s;
    }
    
    @keyframes jumping {
      0% {
        transform: scale(1) translateY(0px) rotateX(0deg);
        box-shadow: 0 0 0 rgba(0, 0, 0, 0);
      }
    
      100% {
        transform: scale(1.2) translateY(-25px) rotateX(45deg);
        background: #000;
        box-shadow: 0 25px 40px #000;
      }
    }
</style>

最终效果

https://weloe.github.io/go-web-demo/#/