Как создать простую внутреннюю вики с помощью GitBook

Разберитесь в своей документации с помощью возможностей управления изменениями, подобных git.

GitBook — это платформа, позволяющая создавать сайты документации или вики компаний. Вы можете использовать его для документирования самых разных вещей, от кода до API и способов использования программного продукта.

GitBook использует тот же процесс, что и репозитории GitHub. Основной экземпляр документации действует как «мастерский» экземпляр. Затем вы можете создавать «черновики», похожие на «ветви».

Этот процесс позволяет многим пользователям работать на одном сайте документации, одновременно обрабатывая или предотвращая конфликты. Это также позволяет изменениям из разных веток проходить процесс проверки перед их объединением.

Как начать использовать GitBook

Вы можете выбрать один из нескольких тарифных планов GitBook. Цены будут зависеть от того, используете ли вы GitBook для проектов с открытым исходным кодом, для личного использования или для совместной работы в частной команде. GitBook можно использовать бесплатно, если вы используете его для проектов с открытым исходным кодом.

GitBook поддерживает Markdown, популярный язык разметки со множеством преимуществ для написания или документирования в Интернете.

GitBook также интегрируется с GitHub — платформой для размещения, хранения и редактирования кода. Вы можете связать свою учетную запись GitBook напрямую со своей учетной записью GitHub, войдя в систему, используя свои учетные данные GitHub.

1. Зарегистрируйтесь на GitBook. Если у вас есть собственная учетная запись GitHub, вы можете нажать Зарегистрироваться на GitHub.

   

2. После входа в систему GitBook перенаправит вас на новую внутреннюю вики. Он также предварительно заполнит вашу вики образцами контента.

   

Обзор интерфейса GitBook

GitBook имеет несколько функций, которые позволяют вам создавать и вносить изменения в ваш сайт документации.

1. Верхняя панель позволяет создавать новые черновики, просматривать историю изменений или просматривать любые другие обсуждения или вложения.

   

2. Самая левая боковая панель позволяет создавать несколько пространств. Вы можете использовать отдельные пространства для разных проектов, чтобы разделить и организовать области документации. Вы можете развернуть или закрыть боковую панель.

   

3. Левая панель выполняет роль меню сайта документации. Вы можете просматривать страницы вашего сайта документации и использовать его для создания групп и вложенных страниц. Вы также можете перемещаться по сайту, используя предоставленные ссылки.

   

4. На нижней панели расположены кнопки, необходимые для процесса контроля версий. Вы можете добавить название для своего черновика, объединить изменение или отправить его на рассмотрение.

   

Как создать новый черновик

Вы можете создать новый черновик, создав новый запрос на изменение и внеся в него изменения.

1. На верхней панели нажмите Запросы на изменение.

   

2. На новой панели, которая появится справа, нажмите вкладку Черновик . Это покажет вам все ваши активные черновики.

   

3. Отсюда вы можете нажать на существующий черновик, чтобы открыть его. Чтобы создать новый черновик, нажмите Новый запрос на изменение и дождитесь завершения загрузки страницы.
4. На нижней панели нажмите Ввести тему. Откроется окно, в котором вы можете дать новому черновику имя. Например, Новая страница – Как настроить кодовую базу.

   

Как создавать страницы и группы

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

1. Создайте новую страницу, нажав ссылку Новая страница в нижней части боковой панели и выбрав Новая страница документа в раскрывающемся списке. Альтернативно вы можете навести курсор на существующую страницу и нажать синюю кнопку плюс.

   

2. Чтобы создать новую группу страниц, нажмите Новая страница и выберите в раскрывающемся списке параметр Новая группа.

   

3. Вы можете переименовать страницу, нажав на три точки рядом со страницей или группой и выбрав Переименовать.

   

4. Начните добавлять контент для заполнения вашей новой страницы. Вы можете добавить простой контент, например текст или заголовки. GitBook также позволяет добавлять другие блоки контента, такие как изображения, вложения файлов, таблицы, вкладки или фрагменты кода. Также есть возможность добавить другие интеграции, такие как встраивание YouTube или контент Google Docs.

   

5. Нажмите кнопку Просмотр различий на нижней панели, чтобы просмотреть различия между вашим черновиком и исходной копией основной документации.

   

6. Закончив написание контента, вы можете нажать Объединить, Отправить и объединить или Отправить на рассмотрение.

   

Как создать ссылку на сайт документации

Вы можете получить доступ к ссылке общего доступа на верхней панели GitBook. Чтобы просмотреть ссылку, вам нужно будет выйти из черновика и просмотреть копию основной документации.

1. По умолчанию видимость вашего сайта документации не указана в списке. Это означает, что вы можете получить доступ к сайту документации по частной ссылке, а не через поисковые системы. На верхней панели нажмите кнопку Не в списке.

2. Выберите нужные настройки видимости из раскрывающегося списка. Обратите внимание, что GitBook может заблокировать определенные настройки видимости, и вам может потребоваться обновить их, чтобы получить к ним доступ.

   

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

4. Под ссылкой нажмите Настройки ссылки и домена. Здесь вы можете связать собственное доменное имя или изменить часть URL-адреса. Если вы используете собственный домен, вы можете просмотреть документацию Gitbook о том, как правильно настроить DNS.

   

Создание документации с помощью GitBook

GitBook позволяет вам совместно создавать и работать над сайтами документации или вики компаний. GitBook заимствует такие концепции из GitHub, как ветки и слияние, для управления основной копией и управления любыми конфликтами.

Вы можете создать новый черновик, чтобы внести в документацию свои индивидуальные изменения. В черновике вы можете вносить изменения в контент, а также добавлять новые страницы или группы страниц. Закончив внесение изменений, вы можете либо объединить их, либо отправить на проверку.

Если вы создаете внутреннюю документацию для своего Java-кода, возможно, вам захочется изучить Javadoc. Javadoc позволяет автоматически документировать ваш Java-код.