docsify, инструмент для создания документации!

внешний интерфейс Docker Markdown

передовой

Думаю, у многих есть такой опыт: после написания проекта, особенно библиотеки компонентов, если у вас нет документа, кто может его понять? Поэтому хороший проект должен иметь понятную документацию. Конечно, уценка в эти годы была в самом разгаре, да и страница на гитхабе тоже позволяет быстро сгенерировать простое описание документа — пишите все в один файл! Как бы серьезно вы ни писали, честно говоря, никто не хочет это читать.

причина

Если вы были партнером по внешнему интерфейсу, вы должны быть знакомы с элементом пользовательского интерфейса, Библиотека компонентов довольно хороша, и пользователям легко начать работу. Почему? Потому что у него есть полная, понятная документация.

Начало

О docsify я узнал случайно, и после дня возни я почувствовал, что надо что-то написать, чтобы в будущем не допустить, чтобы я это проверил.

установить документацию
npm i docsify-cli -g
инициализация

Инициализация должна идти в корневой каталог проекта.Конечно, если вы похожи на меня и пишете документ только для того, чтобы написать документ, просто создайте новую пустую папку. Однако здесь я хочу немного усложнить, потому что документы, которые мы пишем, не всегда пишутся для нас самих, а должны быть выложены на github, чтобы больше людей могли проконсультироваться. Итак, мы начнем с создания пустого репозитория github. Конечно, этот процесс не изнурительный, каждый создает его сам. После создания клонируйте репозиторий локально.

Затем выполните следующую команду в текущем каталоге:

docsify init ./docs

Новый каталог документов будет создан в текущем каталоге.

Он содержит эти три файла.Независимо от того, для чего они используются, я могу только сказать вам, что, скорее всего, вы изменилиindex.htmlИ можно добавить неограниченное количество новых файлов уценки. Не беспокойтесь об этом, просто запустите и посмотрите страницу.

docsify serve docs

Снова откройте браузер:http://localhost:3000Вы можете увидеть инициализированную страницу.

Конечно, вам может показаться, что этот длинный список инструкций невозможно запомнить, поэтому давайте составим простой.

Открытьpackage.json, добавьте один в скрипт, если нет, добавьте его сами:npm init -y

"doc": 'docsify serve docs'

непосредственно позжеnpm run docВот и все. На этом этапе выходит простая модель документа.Далее давайте сосредоточимся на его связанной конфигурации:

настроить

Слишком простая конфигурация не утомительно описывать, дайте адрес, каждый кликнет и увидит самdocsify, а затем сосредоточьтесь на следующих элементах конфигурации.

loadSidebar

Загрузите пользовательскую панель навигации, установитеtrueВот и все, он автоматически загрузит файлы по указанному пути_navbar.md, но мы всегда думаем, что все должны контролировать сами, здесь я просто назову это码控Бар! очень просто, мы./docsновый каталог_navbar.md, чтобы мы могли настроить нашу боковую панель в этом файле.

window.$docsify = {
  // 加载 _navbar.md
  loadSidebar: true,

  // 加载 nav.md
  loadSidebar: 'summary.md'
};

новыйsetup.md, Как показано на фиг.1:
Мы можем видеть, как это выглядит выше, в основном это самый простой вид документа. Но функция далека от желаемого эффекта, давайте поиграем вместе с несколькими плагинами!

плагин

copy to clipboard

Добавьте следующие js вindex.htmlвнизу.

<script src="//unpkg.com/docsify-copy-code"></script>

затем вREADME.mdПросто напишите небольшой код в

Есть и другие плагины, которые относительно просты в настройке, далее мы представим немного громоздкий.

Gittalk

Глядя на название, можно предположить, что некоторые мелкие партнеры знают, для чего он нужен.Это плагин для комментариев, разработанный на основе Github Issue и Preact. Узнайте, как использовать его ниже!

<link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">

<script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
<script src="//unpkg.com/gitalk/dist/gitalk.min.js"></script>
<script>
  const gitalk = new Gitalk({
    clientID: 'Github Application Client ID',
    clientSecret: 'Github Application Client Secret',
    repo: 'Github repo',
    owner: 'Github repo owner',
    admin: ['Github repo collaborators, only these guys can initialize github issues'],
    // facebook-like distraction free mode
    distractionFreeMode: false
  })
</script>

Файлы конфигурации указаны выше, но есть еще некоторые вещи, которые нам нужно заполнить самостоятельно. То есть некоторые конфигурации, связанные с приложением github. Не говори глупостей, откройGitHub.com/settings/…

После добавления мы можем получить соответствующие элементы конфигурации:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Document</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="//unpkg.com/docsify/lib/themes/vue.css">
  <link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: '',
      themeColor: '#19BE6B',
      repo: '',
      loadSidebar: true
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
  <script src="//unpkg.com/docsify-copy-code"></script>
  <script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
  <script src="//unpkg.com/gitalk/dist/gitalk.min.js"></script>
  <script>
    const gitalk = new Gitalk({
      clientID: '9b4355e11242485017da',
      clientSecret: 'fe82f322d0571768a6bf838b515105318397e274',
      repo: 'docsify-starter',
      owner: 'swimly',
      admin: ['swimly'],
      // facebook-like distraction free mode
      distractionFreeMode: true
    })
  </script>
</body>
</html>

наконецindex.htmlКонфигурация в основном такая же, как и выше, инструкция, у меня здесьclientID,clientSecretЭто неправильно, не копируйте это напрямую!

Наконец, давайте сделаем несколько снимков, чтобы насладиться плодами труда!

Базовый документ здесь завершен, и следующим шагом является его улучшение!

Развернуть на гитхабе

Поскольку мы создали новый github ранее, мы можем отправить его непосредственно в основную ветку github! Это еще не конец. Синхронизация с github — это ключ к тому, как его увидят другие. Далее мы сделаем наш последний шаг, откроем проект github, который мы создали в начале, и переключимся наsetting

Найдите страницы GitHub и измените источник наmaster branch /docs folder.
Вот адрес нашего документа, просто нажмите на него, чтобы увидеть окончательный результат! Что ж, на этом полный процесс завершен, и вас ждут новые игровые процессы, которые вы откроете вместе!

некоторые ссылки

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

Спасибо за просмотр, добро пожаловать, чтобы оставить сообщение и обсудить вместе!

Категории