just the docs

Просто документы

Современная, легко настраиваемая и отзывчивая тема Jekyll для документации со встроенным поиском.
Легко размещается на страницах GitHub с небольшим количеством зависимостей.

Посмотрите это в действии!

Видеообзор различных функций Just the Docs

просто-документация-функции-прохождение.mp4

Установка

Используйте шаблон

Шаблон Just the Docs предоставляет самый простой, быстрый и легкий способ создать новый веб-сайт, использующий тему Just the Docs. Чтобы приступить к созданию сайта, просто нажмите «использовать шаблон»!

Примечание. Чтобы использовать тему, вам не нужно клонировать или разветвлять репозиторий Just the Docs! Вам следует делать это только в том случае, если вы собираетесь просматривать документацию темы локально, внести свой вклад в разработку темы или разработать новую тему на основе Just the Docs.

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

Если на вашем компьютере установлен Jekyll, вы также можете создать и просмотреть созданный сайт локально . Это позволяет тестировать изменения перед их фиксацией и позволяет избежать ожидания страниц GitHub. ^1. И вы сможете развернуть свою локальную сборку на платформе, отличной от GitHub Pages.

Точнее, созданный сайт:

• использует подход на основе драгоценных камней, т. е. использует Gemfile и загружает драгоценный камень just-the-docs
• использует рабочий процесс GitHub Pages/Actions для создания и публикации сайта на GitHub Pages.

Помимо этого, вы можете настраивать сайты, созданные с помощью шаблона, по своему усмотрению. Вы можете легко изменить версии just-the-docs и Jekyll, которые он использует, а также добавить дополнительные плагины.

Используйте RubyGems

Альтернативно вы можете установить тему как Ruby Gem, не создавая новый сайт.

Добавьте эту строку в Gemfile вашего сайта Jekyll:

 gem "just-the-docs"

И добавьте эту строку в _config.yml вашего сайта Jekyll:

 theme : just-the-docs

И затем выполните:

 $ bundle

Или установите его самостоятельно как:

 $ gem install just-the-docs

Альтернативно вы можете запустить его внутри Docker во время разработки вашего сайта.

 $ docker-compose up

Использование

Просмотрите документацию для получения информации об использовании.

Содействие

Сообщения об ошибках, предложения новых функций и запросы на включение приветствуются на GitHub по адресу https://github.com/just-the-docs/just-the-docs. Этот проект призван стать безопасным и гостеприимным пространством для сотрудничества, и ожидается, что участники будут соблюдать Кодекс поведения участников.

Отправка изменений кода:

• Отправьте проблему, которая мотивирует изменения, используя соответствующий шаблон.
• Обсудите предлагаемые изменения с другими пользователями и сопровождающими.
• Открыть запрос на включение
• Убедитесь, что все тесты CI пройдены
• Предоставьте инструкции по проверке эффекта изменений.
• Ожидайте проверки кода

Принципы проектирования и разработки этой темы:

1. Как можно меньше зависимостей
2. Скрипт сборки не требуется
3. Первоклассный мобильный опыт
4. Сделайте контент ярким

Разработка

Чтобы настроить среду для разработки этой темы: создайте форк этого репозитория, запустите bundle install из корневого каталога.

Включена современная конфигурация контейнера разработки для VSCode.

Ваша тема настроена так же, как обычный сайт Jekyll! Чтобы протестировать свою тему, запустите bundle exec jekyll serve и откройте браузер по адресу http://localhost:4000 . Это запустит сервер Jekyll, использующий вашу тему. Добавляйте страницы, документы, данные и т. д., как обычно, чтобы протестировать содержимое вашей темы. Когда вы вносите изменения в свою тему и свой контент, ваш сайт будет обновляться, и после обновления вы должны увидеть изменения в браузере, как обычно.

Когда эта тема будет выпущена, в гем будут включены только файлы в _layouts , _includes и _sass отслеживаемые с помощью Git.

Лицензия

Тема доступна с открытым исходным кодом в соответствии с условиями лицензии MIT.

Сноски

1. Публикация изменений на вашем сайте после отправки изменений на GitHub может занять до 10 минут. ↩