前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >如何写出优雅的开源项目文档

如何写出优雅的开源项目文档

作者头像
macrozheng
发布2019-07-30 15:14:17
1.3K0
发布2019-07-30 15:14:17
举报
文章被收录于专栏:mall学习教程

摘要

mall项目是我去年写的SpringBoot实战电商项目,现在在Github上面已经有18k+star。去年12月份的时候,mall项目只有一些必要的说明文档和部署文档。mall项目涉及到的技术栈比较广泛,业务也比较复杂,却没有系统的学习教程。今年5月份的时候,我开始完善整套学习教程,目前已经更新了三十余篇。最近使用docsify搭建了一个小型的文档网站,希望大家能有更好的阅读体验。本文将介绍如何使用docsify来写开源项目文档。

项目文档演示

展示图片

使用docsify来写项目文档

docsify简介

docsify是一个动态生成网站的工具,它不会将.md文件转化为.html文件从而污染你的Github提交记录,所有转化都将在运行时完成。如果你需要快速搭建一个小型文档网站,这将非常实用。

初始化项目

安装nodejs
  • 下载地址:https://nodejs.org/dist/v8.9.4/node-v8.9.4-x64.msi
  • 下载完成后直接安装即可。
安装docsify-cli工具
  • 在命令行中执行如下命令:
代码语言:javascript
复制
npm i docsify-cli -g
  • 安装完成后可以方便地在本地实时预览所编辑的文档。
初始化项目结构
  • 新建一个docs文件夹,然后执行如下命令:
代码语言:javascript
复制
docsify init ./docs
  • docsify会创建如下结构的目录:
代码语言:javascript
复制
  -| docs/
    -| .nojekyll
    -| index.html
    -| README.md
实时预览
  • 在命令行中输入如下命令:
代码语言:javascript
复制
docsify serve docs
  • 访问该地址即可查看效果:http://localhost:3000/

定制侧边栏

  • 在index.html中添加侧边栏的配置:
代码语言:javascript
复制
  <script>
    window.$docsify = {
      loadSidebar: true,
      maxLevel: 2,
      subMaxLevel: 4,
      alias: {
        '/.*/_sidebar.md': '/_sidebar.md'//防止意外回退
      }
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
  • 添加_sidebar.md文件来配置侧边栏:
代码语言:javascript
复制
  * 序章
    * [mall架构及功能概览](foreword/mall_foreword_01.md)
    * [mall学习所需知识点](foreword/mall_foreword_02.md)
  * 架构篇
    * [mall整合SpringBoot+MyBatis搭建基本骨架](architect/mall_arch_01.md)
    * [mall整合Swagger-UI实现在线API文档](architect/mall_arch_02.md)
  • 这样就可以生成一个二级的侧边栏:

展示图片

定制导航栏

  • 在index.html中添加导航栏的配置:
代码语言:javascript
复制
  <script>
    window.$docsify = {
      loadNavbar: true,
      alias: {
        '/.*/_navbar.md': '/_navbar.md'//防止意外回退
      }
    }
  </script>
  • 添加_navbar.md文件来配置导航栏:
代码语言:javascript
复制
  * 演示
    * [后台管理](http://39.98.190.128/index.html)
    * [移动端](http://39.98.190.128/mall-app/mainpage.html)
  * 项目地址
    * [后台项目](https://github.com/macrozheng/mall)
    * [前端项目](https://github.com/macrozheng/mall-admin-web)
    * [学习教程](https://github.com/macrozheng/mall-learning)
  • 这样就可以在右上角生成两个导航栏:

展示图片

定制封面页

  • 在index.html中添加封面页的配置:
代码语言:javascript
复制
  <script>
    window.$docsify = {
      coverpage: true
    }
  </script>
  • 添加_coverpage.md文件来配置封面页:
代码语言:javascript
复制
  ![logo](images/mall.svg)
  # mall-learning
  > mall学习教程,架构、业务、技术要点全方位解析。

  此处填写详细简介。
  [GitHub](https://github.com/macrozheng/mall-learning)
  [Get Started](README.md)
  • 查看封面页效果:

展示图片

添加全文搜索

  • 在index.html中添加全文搜索的配置:
代码语言:javascript
复制
  <script>
    window.$docsify = {
      search: {
        placeholder: '搜索',
        noData: '找不到结果!',
        depth: 3
      },
    }
  </script>
  <script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
  • 查看全文搜索效果:

展示图片

添加代码高亮

  • 在index.html中添加代码高亮的配置:
代码语言:javascript
复制
  <script src="//unpkg.com/prismjs/components/prism-bash.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-java.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-sql.js"></script>
  • 其他支持高亮语言请参考:https://github.com/PrismJS/prism/tree/gh-pages/components
  • 查看代码高亮效果:

展示图片

添加一键拷贝代码

  • 在index.html中添加一键拷贝代码的配置:
代码语言:javascript
复制
  <script src="//unpkg.com/docsify-copy-code"></script>
  • 查看一键拷贝代码效果:

展示图片

在Github上部署文档

  • 首先将你的代码提交到Github上去;
  • 然后点击项目的Settings按钮:

展示图片

  • 开启GitHub Pages服务:
本文参与 腾讯云自媒体同步曝光计划,分享自微信公众号。
原始发表:2019-07-29,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 macrozheng 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 摘要
  • 项目文档演示
  • 使用docsify来写项目文档
    • docsify简介
      • 初始化项目
        • 安装nodejs
        • 安装docsify-cli工具
        • 初始化项目结构
        • 实时预览
      • 定制侧边栏
        • 定制导航栏
          • 定制封面页
            • 添加全文搜索
              • 添加代码高亮
                • 添加一键拷贝代码
                  • 在Github上部署文档
                  相关产品与服务
                  Elasticsearch Service
                  腾讯云 Elasticsearch Service(ES)是云端全托管海量数据检索分析服务,拥有高性能自研内核,集成X-Pack。ES 支持通过自治索引、存算分离、集群巡检等特性轻松管理集群,也支持免运维、自动弹性、按需使用的 Serverless 模式。使用 ES 您可以高效构建信息检索、日志分析、运维监控等服务,它独特的向量检索还可助您构建基于语义、图像的AI深度应用。
                  领券
                  问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档