Как написать элегантную документацию проекта с открытым исходным кодом

GitHub

Резюме

проект торгового центраЭто настоящий проект электронной коммерции SpringBoot, который я написал в прошлом году, и теперь он имеет более 18 тысяч звезд на Github. Еще в декабре прошлого года у проекта торгового центра была только необходимая документация и документация по развертыванию. Проект торгового центра включает в себя широкий спектр технологических стеков и сложный бизнес, но нет систематического учебного пособия. В мае этого года я начал улучшать весь набор учебных пособий и обновил более 30 статей. Недавно я использовал docsify для создания небольшого веб-сайта с документацией, надеюсь, каждый сможет получить больше удовольствия от чтения. В этой статье рассказывается, как использовать docsify для написания документации проекта с открытым исходным кодом.

Демонстрация проектной документации

展示图片

Используйте docsify для написания проектной документации

Введение в документацию

docsify — это инструмент для динамического создания веб-сайтов, он не будет загрязнять ваши коммиты Github путем преобразования файлов .md в файлы .html, все преобразования будут выполняться во время выполнения. Это полезно, если вам нужно быстро настроить небольшой веб-сайт с документацией.

Инициализировать проект

установить ноды

  • ссылка для скачивания:узел будет .org/day3/v8.9.4…
  • После завершения загрузки вы можете установить его напрямую.

Установите инструмент docsify-cli

  • Выполните следующую команду в командной строке:
npm i docsify-cli -g
  • После завершения установки вы можете легко просмотреть отредактированный документ локально в режиме реального времени.

Инициализировать структуру проекта

  • Создайте новую папку docs и выполните следующую команду:
docsify init ./docs
  • docsify создаст каталоги со следующей структурой:
  -| docs/
    -| .nojekyll
    -| index.html
    -| README.md

Предварительный просмотр в реальном времени

  • Введите следующую команду в командной строке:
docsify serve docs

пользовательская боковая панель

  • Добавьте конфигурацию боковой панели в index.html:
  <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 для настройки боковой панели:
  * 序章
    * [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:
  <script>
    window.$docsify = {
      loadNavbar: true,
      alias: {
        '/.*/_navbar.md': '/_navbar.md'//防止意外回退
      }
    }
  </script>
  • Добавьте файл _navbar.md для настройки панели навигации:
  * 演示
    * [后台管理](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:
  <script>
    window.$docsify = {
      coverpage: true
    }
  </script>
  • Добавьте файл _coverpage.md для настройки титульной страницы:
  ![logo](images/mall.svg)
  # mall-learning
  > mall学习教程，架构、业务、技术要点全方位解析。

  此处填写详细简介。
  [GitHub](https://github.com/macrozheng/mall-learning)
  [Get Started](README.md)
  • Посмотрите эффект обложки:

展示图片

Добавить полнотекстовый поиск

  • Добавьте конфигурацию для полнотекстового поиска в index.html:
  <script>
    window.$docsify = {
      search: {
        placeholder: '搜索',
        noData: '找不到结果!',
        depth: 3
      },
    }
  </script>
  <script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
  • Просмотр результатов полнотекстового поиска:

展示图片

Добавить подсветку кода

  • Добавьте конфигурацию подсветки кода в index.html:
  <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>

展示图片

Добавить код копирования в один клик

  • Добавьте конфигурацию копирования кода в один клик в index.html:
  <script src="//unpkg.com/docsify-copy-code"></script>
  • Просмотрите эффект копирования кода в один клик:

展示图片

Развернуть документацию на Github

  • Сначала отправьте свой код на Github;
  • Затем нажмите кнопку настроек проекта:

展示图片

  • Запустите службу GitHub Pages:

展示图片

адрес документа

macro-positive.GitHub.IO/Marylyn-A позволяет вам…

Адрес исходного кода проекта

GitHub.com/macro-positive/…

публика

проект торгового центраПолный набор учебных пособий сериализуется,Обратите внимание на общедоступный номерПолучите это прямо сейчас.

公众号图片

Категории