Мы все можем оценить силу, которую дает нам Ruby on Rails для быстрой разработки отличных веб-приложений. Мы также можем оценить удивительную способность Джекилла превратить Markdown и шаблоны в красивый статичный сайт.
Что если бы мы могли объединить эти два? В этой статье я собираюсь сделать именно это.
Почему?
Наиболее практичный сценарий объединения Jekyll и Rails — это когда вы не хотите отделять основное приложение от блога. Вам не следует делать это, если вы просто хотите добавить динамичности на свой сайт ( Middleman лучше подходит для этого). Но какой бы ни была причина, давайте начнем!
Шаг 1: приложение
В наиболее вероятном сценарии у вас, вероятно, уже есть приложение, и вы хотите добавить блог. Однако для единообразия давайте сгенерируем его для наших целей:
$ rails new jekyll-on-rails $ cd jekyll-on-rails Теперь, когда мы в приложении, нам нужно настроить его для нашего блога Jekyll. Во-первых, мы должны добавить Jekyll в приложение:
# 'Gemfile' gem 'jekyll', '2.5.3' # Terminal $ bundle install
Как только эта команда будет выполнена, мы можем начать добавлять наш блог в Jekyll.
Шаг 2: Блог
Гипотетически все, что нужно Jekyll для запуска — это файл шаблона и файл Markdown. Но у нас есть блоги, которые сложнее, чем это. Каждый блог уникален (и должен быть), но для демонстрации нам нужен единый блог, так что давайте используем по умолчанию.
Во-первых, давайте сделаем так, чтобы Джекилл создал наш блог.
$ bundle exec jekyll new blog
Это создает простой пример блога с этой файловой структурой:
. ├── _config.yml ├── _includes │ ├── footer.html │ ├── head.html │ └── header.html ├── _layouts │ ├── default.html │ ├── page.html │ └── post.html ├── _posts │ └── 2015-03-27-welcome-to-jekyll.markdown ├── _sass │ ├── _base.scss │ ├── _layout.scss │ └── _syntax-highlighting.scss ├── about.md ├── css │ └── main.scss ├── feed.xml └── index.html
Мы оставим большинство из них там, где они есть, но мы собираемся переместить _config.yml в config каталог Rails и переименовать его в нечто более конкретное:
$ cd blog $ mv _config.yml ../config/jekyll.yml $ cd ..
Вот тут-то и начинается самое интересное, настраивая блог!
Шаг 3: Настройка блога
Если вы попытаетесь jekyll serve в блог прямо сейчас и запустить jekyll serve , он все равно будет работать, но вы получите ошибку, что файл конфигурации отсутствует. Это, очевидно, потому что мы только что переместили его, поэтому нам придется использовать специальную конфигурацию при создании нашего блога.
Мы хотим, чтобы сайт Jekyll создавался при каждой регенерации нашего приложения Rails, поэтому нам нужно добавить инициализатор в наше приложение:
#config/initializers/blog.rb Rails.application.config.after_initialize do Rails.logger = Logger.new(STDOUT) begin # make a spot for the site dest = Rails.root.join('public/blog') # generate the site Jekyll::Site.new( Jekyll.configuration({ "config" => Rails.root.join('config', 'jekyll.yml').to_s, "source" => Rails.root.join('blog').to_s, "destination" => dest.to_s }) ).process # the strange codes give the output color Rails.logger.info "\e[0;32;49mJekyll site built!\e[0m]]" rescue => e Rails.logger.error "\e[0;31;49mJekyll site build failed.\e[0m\n\e[0;33;49mError:\e[0m #{e}" end end
Этот код делает несколько вещей для нас:
* Он генерирует сайт Jekyll при запуске приложения Rails
* Определяет путь для сайта ( http://localhost:3000/blog/ ) — чтобы изменить этот путь, измените переменную dest
* Он использует интеллектуальную обработку ошибок, чтобы гарантировать, что мы знаем, когда сборка сайта успешна и когда она терпит неудачу. Это также гарантирует, что, даже если сборка сайта завершится неудачно, приложение не выйдет из строя, что позволит разделить ошибки кода между Jekyll и Rails
Этот файл говорит Джекиллу взять наш сайт (в blog/ ) и переместить его в ( public/blog/ ). Это работает только потому, что Rails размещает статические файлы в своем каталоге public/ .
Теперь мы можем наконец запустить наше приложение Rails и посмотреть, как это работает!
$ bundle exec rails server => Booting WEBrick => Rails 4.2.0 application starting in development on http://localhost:3000 => Run `rails server -h` for more startup options => Ctrl-C to shutdown server Configuration file: /Users/jesseherrick/Dropbox/Drafts/jekyll-on-rails/config/jekyll.yml I, [2015-03-27T16:08:02.591221 #56341] INFO -- : Jekyll site built! [2015-03-27 16:08:02] INFO WEBrick 1.3.1 [2015-03-27 16:08:02] INFO ruby 2.2.0 (2014-12-25) [x86_64-darwin14] [2015-03-27 16:08:02] INFO WEBrick::HTTPServer#start: pid=56341 port=3000
Но есть проблема, CSS не был загружен должным образом!
Немного изучив, вы заметите, что HTML использует абсолютные пути (т.е. /css/main.css ). Это означает, что любой запрашиваемый ресурс вернет 404, потому что наш блог находится в подкаталоге. К счастью, шаблон сайта Jekyll достаточно умен, чтобы иметь в конфигурации опцию baseurl , которая позволяет определить подкаталог для загрузки ресурсов. Чтобы быстро решить эту проблему, мы можем изменить наш конфиг так:
# ... other config not shown ... baseurl: "/blog" # ... other config not shown ...
Мы используем /blog потому что это каталог, где генерируется наш сайт. После перезапуска сервера все работает нормально.
И вот, приложение Rails и сайт Jekyll работают без сбоев. Вы можете перестать читать сейчас, если хотите, но есть еще более интересные вещи.
Дополнительно: использование Rails-подобных активов
К сожалению, в настоящее время нет способа легко связать ресурсы Rails с Jekyll. Но если вам все еще нравится конвейер ресурсов Rails (ну, а кто нет?), Для этого есть плагин!
Jekyll-Assets — это фантастический плагин Jekyll, который может многое для вас сделать, например:
* Компиляция CoffeeScript, SCSS / Sass, Less и ERB
* Требовать зависимости изнутри активов (используя звездочки)
* Жесткий и мягкий main-bbd8a1c8b716f90cfaf9493cbb3868dc.css кеша ( main-bbd8a1c8b716f90cfaf9493cbb3868dc.css vs main.css?cb=bbd8a1c8b716f90cfaf9493cbb3868dc )
* Сжатие ваших активов
* И несколько других вещей
Это довольно круто, верно? Давайте добавим это на наш сайт Jekyll.
Сначала мы добавляем gem 'jekyll-assets' в наш Gemfile и bundle install . Далее, мы должны убедиться, что Jekyll включает этот плагин при создании сайта. Для этого мы просто добавляем jekyll-assets в наш список плагинов в config/jekyll.yml , вот так:
# 'config/jekyll.yml` plugins: - jekyll-assets # ... other config ...
Теперь, когда плагин добавлен в Jekyll, мы можем начать его использовать. Но сначала мы должны настроить его для тех функций, которые нам нужны. Итак, снова откройте config/jekyll.yml и вставьте:
# 'config/jekyll.yml' # assets assets: dirname: assets # _assets baseurl: /blog/assets/ sources: # asset subdirectories - _assets/stylesheets - _assets/javascripts - _assets/images cachebust: hard js_compressor: uglifier # included by rails css_compressor: sass # included by rails # ... other config ...
Отлично, но теперь мы должны использовать этот плагин. Для этого нам нужно передвигаться по нашим активам:
# make a place for the assets $ cd blog $ mkdir _assets $ mkdir _assets/stylesheets $ mkdir _assets/javascripts $ mkdir _assets/images # move around assets $ mv _sass/* _assets/stylesheets/ && rmdir _sass $ mv css/* _assets/stylesheets/ && rmdir css
Если бы у нас были какие-либо файлы JavaScript / CoffeeScript и / или изображения, мы бы также переместили их в соответствующие папки.
Как и в Rails, Jekyll-Assets использует двойные (а иногда и тройные) расширения файлов для преобразования файлов. Для наших целей мы должны переименовать main.scss в main.css.scss потому что мы хотим, чтобы наши файлы были проанализированы как SCSS, а затем преобразованы в CSS. Вы должны делать это с любыми файлами, которые вы хотите конвертировать Jekyll-Assets ( например, main.js.coffee ).
Если мы посмотрим на наш блог снова, вы заметите проблему. Таблицы стилей снова 404ing. Чтобы это исправить, нам просто нужно реализовать способ связывания таблиц стилей (и скриптов) в HTML в Jekyll-Assets.
Jekyll-Assets предоставляет несколько ликвидных тегов и генераторов для правильной реализации очистки кэша и обработки пути к ресурсам. Мы не будем освещать их все здесь, так что посмотрите на эту страницу, если вам интересно.
Чтобы связать нашу таблицу стилей, нам просто нужно добавить это в наш HTML :
<!-- 'blog/_includes/head.html' --> {% stylesheet main %}
Теперь мы можем удалить любой старый теги, так как они просто выбросят 404 с. И если мы перезапустим приложение, вы увидите, что таблицы стилей снова загружаются.
Почему мы просто прошли через все эти трудности, чтобы получить тот же результат?
Хотя это казалось излишним, мы на самом деле настроили очень хорошую систему для себя. Давайте добавим немного CoffeeScript, чтобы продемонстрировать это.
Допустим, я хочу добавить FitText.js на мой сайт Jekyll, чтобы заголовок был очень отзывчивым с использованием JavaScript. Проблема в том, что этот скрипт использует jQuery для своей функциональности, и я не хочу делать много вызовов script в моем HTML по соображениям производительности. Jekyll-Assets делает это действительно легко сделать.
Сначала нам нужно открыть конфигурацию Jekyll и добавить новый подкаталог в папку ресурсов JavaScript:
# 'config/jekyll.yml' assets: # ... other config not shown ... sources: - _assets/stylesheets - _assets/javascripts - _assets/javascripts/vendor # added - _assets/images # ... other config not shown ...
Теперь нам нужно создать каталог этого поставщика и загрузить в него jQuery и FitText.js:
# create the directory $ cd blog/_assets/javascripts $ mkdir vendor $ cd vendor # download the assets $ wget https://raw.githubusercontent.com/davatron5000/FitText.js/master/jquery.fittext.js -O fittext.js $ wget http://code.jquery.com/jquery-2.1.3.min.js -O jquery.js
Объедините файлы, чтобы не было нескольких запросов на JavaScript:
# 'blog/_assets/javascripts/main.js.coffee #= require vendor/jquery #= require vendor/fittext # and then actually use the plugin $('h1.page-heading').fitText()
Наконец, запросите один скрипт в HTML:
<!-- bottom of '_layout/default.html' --> {% javascript main %}
Теперь, если мы перезагрузим страницу, мы получим хороший большой отзывчивый заголовок:
Это только начало того, что вы можете сделать с Jekyll-Assets.
У Jekyll есть фантастическое сообщество, которое делает отличные плагины, но если вы хотите создать свой собственный, у Jekyll также есть документы для этого.
Дополнительно: Автоматизация
Вы, наверное, заметили, что мы должны продолжать перезапускать Rails каждый раз, когда мы хотим предварительно просмотреть сайт. Это хорошо, если мы просто вносим несколько изменений в сайт Jekyll, но если мы занимаемся веб-дизайном, это может стать довольно раздражающим. К счастью, мы можем автоматизировать это!
Сначала создайте новую задачу Rake для Rails.
$ rails generate task jekyll
Эта команда создает файл с именем lib/tasks/jekyll.rake . Используя API Jekyll, мы можем программно построить сайт и обслуживать его одновременно (используя потоки).
namespace :jekyll do dest = Rails.root.join('public/blog') options = { 'baseurl' => '/blog', 'config' => Rails.root.join('config', 'jekyll.yml').to_s, 'watch' => true, 'port' => 3000, 'source' => Rails.root.join('blog').to_s, 'destination' => dest.to_s } build = Thread.new { Jekyll::Commands::Build.process(options) } serve = Thread.new { Jekyll::Commands::Serve.process(options) } commands = [build, serve] commands.each { |c| c.join } end
Теперь, rake jekyll , запустит сервер по адресу http://localhost:3000/blog/ и перезагрузится при обнаружении изменений файла.
Вывод
Возможности с Jekyll и Rails безграничны. Эта, казалось бы, противоположная пара может работать вместе в идеальном унисон для создания великолепного, разностороннего веб-сайта. Вы можете найти источник этого проекта на GitHub . Я хотел бы услышать ваш вклад ниже, если у вас есть какие-либо вопросы или предложения о том, как этот метод может быть улучшен.