Подробнее, какой файл

Обновлено: 21.11.2024

С недавним добавлением Actions в линейку продуктов GitHub у нас теперь есть возможность создать 100% Pure, Unfiltered™ JavaScript, альтернативу Jekyll (и Ruby) в GitHub Pages. Это большое дело. Действительно.

Страницы GitHub, для непосвященных, – общедоступные веб-страницы, автоматически созданные из исходных файлов GitHub и свободно размещенные на github.io или в вашем личном домене. Нет серверов, которые нужно выделять, и баз данных, которые нужно настраивать.

За автоматическую генерацию отвечает Jekyll, довольно удобный генератор статических сайтов. Он существует уже довольно давно, проверен в бою и поддерживается огромным сообществом. Он также достаточно прост для начинающих и достаточно мощен для опытных пользователей. К сожалению, для его настройки требуется запустить его локально, и здесь все становится затруднительным. Jekyll основан на Ruby. Для обычных пользователей Ruby представляет собой сложную задачу в настройке и обслуживании, особенно в Windows. Масштабирование также является проблемой для Jekyll/Ruby, поскольку большие сборки печально известны тем, что компиляция занимает много времени.

Несмотря на то, что существует множество конкурирующих генераторов статических сайтов, одной из них не хватало интеграции сборки и развертывания на веб-сервере GitHub. Pages+Jekyll позаботился об этой сборке и развертывании для вас автоматически, как по волшебству. Просто зафиксируйте ветку gh-pages и пуф, ваш сайт обновлен.

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

Если бы мы только могли запускать генератор статических сайтов на Pages со всеми функциями и привилегиями Jekyll, но с простотой настройки и производительностью, обеспечиваемыми более современными альтернативами.

Ну, теперь можно. Наконец-то все стало на свои места.

В этом кратком руководстве рассматриваются основы перехода с Jekyll на JavaScript. Для начала необходимо следующее:

Конечно, было бы целесообразно уже иметь репозиторий Jekyll. Если нет, создайте новый репозиторий GitHub (общедоступный или частный) с инициализированным файлом README. Следуйте дальнейшим инструкциям, чтобы клонировать и настроить его локально.

Потребовалось некоторое время, чтобы кто-то переложил суть Jekyll в JavaScript. С Eleventy Зак Лезерман (@zachleat) действительно дистиллировал, разливал по бутылкам и отправлял. О, и я упоминал, что это быстро? Я пропущу остальную часть коммерческого предложения и предоставлю слово экспертам.

Если вы еще не догадались, я в восторге от Eleventy. Этот универсальный нож идеально помещается в вашем кармане и заставляет вас улыбаться каждый раз, когда вы им пользуетесь.

Это также делает переход с Jekyll на JavaScript практически незаметным. Так что давайте с этим справимся.

Установить и настроить

Откройте терминал и перейдите к своему репозиторию.

Если у вас еще нет файла package.json в корневом каталоге, используйте этот момент для инициализации npm.

Установите Eleventy как devDependency.

В корень сайта добавьте пустой файл .nojekyll, чтобы отключить сборку Jekyll по умолчанию.

Для простоты мы будем использовать файловую структуру Jekyll по умолчанию.

В корень сайта добавьте файл конфигурации .eleventy.js со следующим содержимым. Дополнительные сведения см. в документации по конфигурации Eleventy.

Глядя на dir.output выше, обратите внимание, что мы поддерживаем паритет с развертыванием Jekyll, используя каталог ./_site для нашего скомпилированного кода.

В раздел сценариев package.json добавьте следующее. Позже нам понадобится скрипт сборки для нашего развертывания.

  • очистить: очищает каталог развертывания
  • сборка: очищает каталог развертывания и создает сайт с помощью Eleventy
  • запуск: запуск Eleventy в режиме разработчика с обновлением браузера в реальном времени.

Теперь настоящий волшебный соус в стиле GitHub Actions.

Откройте в браузере репозиторий GitHub и выберите вкладку "Действия".

Нажмите кнопку "Новый рабочий процесс".

Нажмите кнопку Настроить рабочий процесс самостоятельно.

В поле /.github/workflows/main.yml введите одиннадцати_билд.yml.

В текстовом поле "Редактировать новый файл" вырежьте и вставьте следующее:

Нажмите кнопку «Начать фиксацию».

Заполните форму Зафиксировать новый файл и выберите Зафиксировать непосредственно в основной ветке.

Сценарий рабочего процесса должен быть достаточно информативным. Видите эту строку $> в конце рабочего процесса? Нам нужно добавить ключи развертывания на GitHub перед попыткой развертывания.

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

Создайте ключ SSH локально для использования в качестве ключа развертывания.

Откройте в браузере репозиторий и выберите вкладку "Настройки".

Выберите Развернуть ключи в меню слева.

  1. Нажмите кнопку "Добавить ключ развертывания".
  2. В поле "Название" введите "Открытый ключ ACTIONS_DEPLOY_KEY".
  3. В поле «Ключ» вырежьте и вставьте содержимое файла ключа SSH gh-pages.pub, созданного на шаге 1 выше.
  4. Установите флажок Разрешить доступ для записи.
  5. Нажмите кнопку "Добавить ключ".

Выберите Секреты в меню слева.

  1. Нажмите на ссылку "Добавить новый секрет".
  2. В поле «Имя» введите «ACTIONS_DEPLOY_KEY».
  3. В поле «Значение» вырежьте и вставьте содержимое файла ключа SSH gh-pages из шага 1 выше.
  4. Нажмите кнопку "Добавить секрет".

ВАЖНО: на этом этапе удалите локальные ключи gh-pages. Вы, конечно, не хотите добавлять их в свой контроль версий (у всех на виду).

Чтобы инициировать развертывание, зафиксируйте/объедините ветку master. Первое развертывание завершится ошибкой (поскольку ветка gh-pages еще не создана).

Вернитесь на вкладку "Настройки".

  1. Прокрутите страницу вниз до раздела GitHub Pages.
  2. В параметрах источника выберите ветку gh-pages .

Добавьте еще немного кода в мастер, чтобы инициировать другое развертывание.

Поздравляю. Готово! С этого момента вы сможете инициировать новую сборку и развертывание следующим образом:

Ваши обновления будут развернуты за считанные секунды. Все это происходит в экосистеме, в которой вы версионируете свой код. Никаких дополнительных зависимостей, никаких дополнительных учетных записей, нада. Насколько это круто?

Файл CNAME, созданный, когда вы указали свой домен в поле "Пользовательский домен" (выше), необходимо включить в наш каталог распространения.

Откройте ветку gh-pages и скопируйте файл CNAME.

Вернитесь к ветке master и добавьте этот файл CNAME в исходный каталог (в данном случае в корневой каталог).

Откройте файл конфигурации .eleventy.js и добавьте файл CNAME в список сквозных копий.

Сохранить, зафиксировать и отправить в источник.

В течение 12 лет GitHub дразнил нас продуктом веб-хостинга, который делал почти все, что нам было нужно. Мы были благодарны и сделали должное. Попутно мы придумали хаки и обходные пути, задействовав один или несколько сторонних сервисов для выполнения задачи. Но ничто не сочетало управление версиями исходного кода, гибкое создание сайтов и веб-хостинг в одном элегантном пакете.

Мы предполагаем, что вы будете публиковать на Github с помощью рабочего стола Github (а не напрямую из RStudio, что требует дополнительной настройки).

Создайте пустой текстовый файл .nojekyll и сохраните его в корне сайта (обычно это папка проекта). Игнорируйте любые предупреждения о типе файла. Потому что он начинается с . файл не будет отображаться в списке файлов. Однако это говорит Github не пытаться создавать сайт с помощью jekyll (по умолчанию для Github). Если вы разветвили и клонировали этот сайт из Github, это было сделано за вас.

В _site.yml добавьте строку с output_dir: "." . Если вы разветвили и клонировали этот сайт из Github, это было сделано за вас.

Файлы сайта отправляются на _site в папке вашего проекта. Переместите index.html в основную папку проекта (корневой каталог сайта), иначе он не будет создан, когда вы отправите его на Github. Если вы разветвили и клонировали этот сайт, то это было сделано за вас.

Если вы еще не видите папку своего проекта, добавьте папку проекта на рабочий стол github. Напишите быстрое сообщение в сводке, нажмите «Зафиксировать», а затем выполните синхронизацию. Это добавит сайт в ваши репозитории GitHub.

  1. Github позволит вам публиковать веб-сайты проектов для каждого репозитория (известные как страницы github или gh-pages ). В конечном итоге они будут опубликованы по адресу yourusername.github.io/repositoryname .

Но здесь нам нужно позаботиться. На изображении выше слева мы видим, что рядом с Branch написано master . Веб-сайты публикуются в ветке github pages ( gh-pages ) репозитория, чтобы держать их отдельно (поскольку данные вашего репозитория и веб-сайт вашего проекта могут быть совершенно разными вещами). Значит, ваш сайт еще не опубликован.

Чтобы опубликовать веб-сайт, нам нужно перейти в настройки в нашем репозитории, а затем прокрутить вниз. На изображении ниже, где вы видите master в своем репозитории, измените ветку на gh-pages. Ваш простой веб-сайт теперь будет создан по указанному адресу. Вы читаете это онлайн, так что это должно сработать.

Если вы разветвили и клонировали этот сайт, все должно быть хорошо, потому что основная ветка была удалена, осталась только ветка gh-pages. Однако, если вы начали с нуля, вам потребуется описанная выше процедура.

Если вы работаете в Windows, у вас может не быть команды touch, и вы можете создать файл в R, используя file.create('.nojekyll') .

Один из подходов — опубликовать свою книгу как сайт GitHub Pages из папки /docs в основной ветке, как описано в справке GitHub. Во-первых, установите выходной каталог вашей книги как /docs, добавив строку output_dir: «docs» в файл конфигурации _bookdown.yml. Затем, после отправки изменений в GitHub, перейдите в настройки своего репозитория и в разделе «Страницы GitHub» измените «Источник» на «Папка главной ветки/документов». В этом случае файл .nojekyll должен находиться в папке /docs.

Альтернативный подход заключается в создании ветки gh-pages в вашем репозитории, сборке книги, размещении вывода HTML (включая все внешние ресурсы, такие как изображения, файлы CSS и JavaScript) в эту ветку и отправке ветки в удаленный репозиторий. Если в вашем репозитории книг нет ветки gh-pages, вы можете создать ее с помощью следующих команд:

После того как вы настроили GIT, остальную работу можно автоматизировать с помощью сценария (Shell, R или Makefile, в зависимости от ваших предпочтений). По сути, вы компилируете книгу в HTML, затем запускаете команды git для отправки файлов на GitHub, но вы, вероятно, не хотите делать это снова и снова вручную и локально. Может быть очень удобно полностью автоматизировать процесс публикации в облаке, поэтому после правильной настройки все, что вам нужно сделать, это написать книгу и отправить исходные файлы Rmd на GitHub, и ваша книга всегда будет автоматически собрана. и публикуется со стороны сервера.

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

Предположим, что вы сейчас находитесь в ветке master (куда вы поместили исходные файлы Rmd) и скомпилировали книгу в каталог _book. Что вы можете сделать дальше с Трэвисом:

Имя переменной GITHUB_PAT и имя каталога book-output являются произвольными, и вы можете использовать любые имена по своему усмотрению, если они не конфликтуют с существующими именами переменных среды или именами каталогов. Этот сценарий вместе со сценарием сборки, о котором мы упоминали в Разделе 5.1, можно поместить в основную ветку как сценарии оболочки, например, вы можете назвать их как _build.sh и _deploy.sh. Тогда ваш .travis.yml может выглядеть так:

Языковой ключ указывает Трэвису использовать виртуальную машину с установленной R. Ключ безопасности — это ваш зашифрованный личный токен доступа. Если вы уже сохранили переменную GITHUB_PAT с помощью веб-интерфейса Travis вместо инструмента командной строки travis encrypt , вы можете не указывать этот ключ.

Поскольку этот сервис Travis в первую очередь предназначен для проверки пакетов R, вам также понадобится (поддельный) файл DESCRIPTION, как если бы репозиторий книг был пакетом R. Единственное, что действительно имеет значение в этом файле, — это спецификация зависимостей. Все зависимости будут установлены через пакет devtools. Если зависимость находится в CRAN или BioConductor, вы можете просто указать ее в поле «Импорт» файла DESCRIPTION. Если он находится на GitHub, вы можете использовать поле Remotes, чтобы указать имя его репозитория. Ниже приведен пример:

Если вы используете инфраструктуру на основе контейнеров в Travis, вы можете включить кэширование с помощью sudo: false в .travis.yml . Обычно вы должны кэшировать как минимум два типа каталогов: каталог рисунка (например, _main_files) и каталог кэша (например, _main_cache). Эти имена каталогов также могут быть другими, если вы указали параметры fig.path и cache.path для блока Knitr, но я настоятельно рекомендую вам не изменять эти параметры. Каталоги фигур и кэша хранятся в каталоге _bookdown_files корневого каталога книги. Файл .travis.yml, в котором включено кэширование каталогов фигур и кеша, может иметь дополнительные настройки sudo и cache, например:

Если создание вашей книги требует очень много времени, вы можете использовать описанные выше конфигурации в Travis, чтобы сэкономить время. Обратите внимание, что packages: yes означает, что пакеты R, установленные на Travis, также кэшируются.

GitHub и Travis CI — не единственные варианты для создания и публикации вашей книги. Вы можете хранить и публиковать книгу на своем собственном сервере.

Если вы предпочитаете использовать реструктурированный текст вместо Markdown для своей технической документации, вы в хорошей компании. Использование расширений Sphinx, Python, RST и Sphinx дает ряд преимуществ, поскольку эти инструменты создаются с учетом документации для разработчиков.

Еще одно отличное предложение — GitHub Pages с автоматической публикацией при обновлении известной ветки, например ветки master или gh-pages.

Итак, как насчет лучшего из обоих?Давайте углубимся в ключевые конфигурации, которые позволяют публиковать страницы Python Sphinx на страницах GitHub.

Название репозитория GitHub может повлиять на результирующий URL

Если вам нужен URL-адрес, например .github.io или .github.io , назовите репозиторий .github.io или .github.io . Затем по умолчанию страницы GitHub публикуются по URL-адресу, соответствующему имени репозитория.

Включить страницы GitHub для репозитория GitHub

Примечание. У вас должны быть права администратора в репозитории, чтобы видеть вкладку «Настройки».

  1. Перейдите в репозиторий на веб-сайте GitHub и убедитесь, что вы вошли в систему.
  2. Добавьте каталог /docs в главную ветвь. В противном случае вы не получите основную папку /docs для параметра «Источник» в раскрывающемся списке.
  3. Перейдите на вкладку "Настройки". Сначала перейдите в раздел «Параметры».
  4. Прокрутите вниз до раздела "Страницы GitHub" и выберите раскрывающийся список в разделе "Источник".

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

Затем вы настраиваете файл .nojekyll, чтобы указать, что вы не используете Jekyll в качестве генератора статических сайтов в этом репозитории.

Добавьте файл .nojekyll в каталог /docs

Когда GitHub видит файл .nojekyll, он использует корневой файл index.html. Подробнее об этой функции читайте в исходном сообщении в блоге.

Примечание. Я бы рекомендовал использовать каталог /docs в основной ветке, чтобы вы были уверены, что исходный и выходной HTML-код разделены. Вы также можете использовать каталог _build в корне репозитория в качестве обслуживаемого HTML.

Читайте также: