По просьбе знакомого выкладываю инструкцию по установке и настройке Octopress. Octopress - это простой и удобный генератор статичных сайтов. Он поддерживает выгрузку на GitHub, Bitbucket, Heroku или на ваш сервер с помощью Rsync.

Формирование рабочей среды для Octopress.

В документации на официальном сайте указано, что для корректной работы Octopress требуется Ruby версии 1.9.3. Но у абсолютного большинства, в репозиториях предлагается версия от 2.1 и выше. В той же документации для того, чтобы установить версию 1.9.3 предлагается использовать rbenv или RVM. Для себя я выбрал RVM (Ruby Version Manager). На его примере мы и рассмотрим установку Octopress.

Для начала установим в систему необходимые пакеты:

1

# apt-get install nodejs git curl

ПРИМЕЧАНИЕ! Для наглядности, перед каждой командой будет указан определенный символ, если это # - значит команда выполняется от имени суперпользователя root, если символ $ - то команда выполняется от имени текущего пользователя.

После чего установим RVM:

1

$ curl -L https://get.rvm.io | bash -s stable

Подскажем системе, где искать RVM:

1

$ source "$HOME/.rvm/scripts/rvm"

Чтобы в дальнейшем каждый раз не указывать путь до каталога с RVM, добавим путь до него в .bashrc:

1

$ echo '[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm"' >> ~/.bashrc

Установим необходимую версию Ruby:

1

$ rvm install 1.9.3

Перезапускаем RVM, и выбираем версию 1.9.3. С помощью ключа --default мы указываем, что будем использовать эту версию по умолчанию:

1
2
3
4

$ rvm reload
RVM reloaded!
$ rvm use --default 1.9.3
Using /home/nihi1ist/.rvm/gems/ruby-1.9.3-p551

Смотрим какая версия Ruby используется в данный момент:

1
2

$ ruby -v
Using /home/nihi1ist/.rvm/gems/ruby-1.9.3-p551

Отлично! Нужная версия Ruby установна и готова к использованию. Можно приступить к установке Octopress. Скачиваем с GitHub необходимые файлы:

ПРИМЕЧАНИЕ! Установщик может в процессе установки может затребовать пароль, для того чтобы установить в систему необходимые зависимости.

Установка Octopress.

1
2

$ git clone git://github.com/imathis/octopress.git octopress
$ cd octopress

Установим gem с названием bundler:

1

$ gem install bundler

Вышеупомянутый gem позволит нам установить другие gem'ы, указанные в файле Gemfile. Запустим команду установки:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

$ bundle install
Fetching gem metadata from https://rubygems.org/.........
Fetching version metadata from https://rubygems.org/..
Fetching dependency metadata from https://rubygems.org/.
Installing rake 10.4.2
Installing RedCloth 4.2.9 with native extensions
Installing blankslate 2.1.2.4
Installing chunky_png 1.3.5
...
Installing listen 3.0.5
Installing sinatra 1.4.6
Installing jekyll-watch 1.3.0
Installing jekyll 2.5.3
Installing octopress-hooks 2.6.1
Installing octopress-date-format 2.0.2
Bundle complete! 14 Gemfile dependencies, 48 gems now installed.
Use `bundle show [gemname]` to see where a bundled gem is installed.
Post-install message from compass:
    Compass is charityware. If you love it, please donate on our behalf at http://umdf.org/compass Thanks!
Post-install message from haml:

HEADS UP! Haml 4.0 has many improvements, but also has changes that may break
your application:

* Support for Ruby 1.8.6 dropped
* Support for Rails 2 dropped
* Sass filter now always outputs <style> tags
* Data attributes are now hyphenated, not underscored
* html2haml utility moved to the html2haml gem
* Textile and Maruku filters moved to the haml-contrib gem

For more info see:

http://rubydoc.info/github/haml/haml/file/CHANGELOG.md

Выхлоп сокращен.

Установим стандартную тему:

1

$ rake install

Если вас не устраивает стандартная тема, то вы можете выбрать тему по вкусу здесь. Процесс установки альтернативной темы несложен. Переходим в каталог Octopress:

1

$ cd octopress

Скачиваем нужную тему:

1

$ git submodule add GIT_URL .themes/THEME_NAME

Где GIT_URL - имя репозитория темы, а THEME_NAME - имя темы. Теперь тема доступна для установки:

1

$ rake install['THEME_NAME']

После чего заново генерируем сайт:

1

$ rake generate

Подготовка к развертыванию сайта на базе GitHub.

В качестве платформы для сайта я решил выбрать GitHub, тому есть два аргумента, которые оказались лично для меня важными:
- бесплатный,
- поддерживает CNAME*

* Поддежка CNAME позволяет прикреплять произвольный домен к репозиторию.

Описывать регистрацию на GitHub я не буду. Но опишу процесс создания репозитория. После того как вы зарегистрируетесь, создайте репозиторий (рис. 1):

Хочу обратить ваше внимание, что имя сайта должно быть идентично имени пользователя.

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

Для выгрузки в репозиторий используется публичный SSH-ключ. Его можно добавить как в настройках репозитория (рис. 3, рис. 4), так и в настроках профиля. Если вы добавите ключ только для репозитория, он будет использоватся лишь для работы с указанным репозиторием.

Если у вас ещё нет публичного SSH-ключа, самое время создать его. Как это сделать, вы можете посмотреть здесь.

Теперь свяжем созданный выше репозиторий с каталогом Octopress. Для этого запустим команду setup_github_pages. В процессе команда запросит адрес репозитория, пример адреса показан на рис. 3.

1
2
3
4
5

$ rake setup_github_pages
Enter the read/write url for your repository
(For example, 'git@github.com:your_username/your_username.github.io.git)
           or 'https://github.com/your_username/your_username.github.io')
Repository url: git@github.com:nihi1ist/nihi1ist.github.io.git

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

Настройка блога.

Основные настройки хранятся в файле _config.yml. Сам файл расположен в корневой папке Octopress. Ниже приведу содержимое этого файла с комментариями.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# ----------------------- #
#      Main Configs       #
# ----------------------- #

url: http://yoursite.com
title: Название вашего блога
subtitle: Описание вашего блога
author: Ваш Ник/Имя
simple_search: https://www.google.com/search            # Поисковая система блога
description:

# Формат даты по умолчанию "ordinal" (Пример: "July 22nd 2007")
# Как настроить формат даты показано на странице 
# http://www.ruby-doc.org/core-1.9.2/Time.html#method-i-strftime
# Кроме того, %o даст вам порядковый номер дня
date_format: "ordinal"

# RSS / Email (необязательно) ссылки для подписки
# (изменится если использовать что нибудь вроде Feedburner)
subscribe_rss: /atom.xml
subscribe_email:
# RSS feeds can list your email address if you like
email:

# ----------------------- #
#    Jekyll & Plugins     #
# ----------------------- #

# Если вы хотите публиковать контент в подкаталог, например http://site.com/project
# тогда установите параметре корня сайта - 'root: /project'
root: /
# С помощью параметра ниже можно задать формат пути для статьи
# можно так же использовать переменные :category 
permalink: /blog/:year/:month/:day/:title/
source: source
destination: public
plugins: plugins
code_dir: downloads/code
category_dir: blog/categories
markdown: rdiscount
rdiscount:
  extensions:
    - autolink
    - footnotes
    - smart
highlighter: pygments # default python pygments have been replaced by pygments.rb

paginate: 10                    # Количество сообщений на главной странице
paginate_path: "posts/:num"     # Directory base for pagination URLs eg. /posts/2/
recent_posts: 5                 # Количество сообщений в разделе Recent Posts
excerpt_link: "Read on →"  # "Continue reading" Текст ссылки 
excerpt_separator: "<!--more-->"# Разделитель для статьи

titlecase: true                 # Converts page and post titles to titlecase

# Перечислите модули которые вы хотите добавить на боковую панель, в том порядке который вам нужен
# Для того чтобы добавить свой asides, создайте файл в директории /source/_includes/custom/asides/
# И добавьте их к списку ниже как 'asides/custom_aside_name.html'
default_asides: [asides/recent_posts.html, asides/github.html, asides/delicious.html, asides/pinboard.html, asides/googleplus.html]

# Each layout uses the default asides, but they can have their own asides instead. Simply uncomment the lines below
# and add an array with the asides you want to use.
# blog_index_asides:
# post_asides:
# page_asides:

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

Создание страниц и сообщений.

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

Новые сообщения создаются в каталоге octopress/source/_posts и имеют формат имени YYYY-MM-DD-post-name.markdown:

1
2
3

$ rake new_post["Новое сообщение"]
mkdir -p source/_posts
Creating new post: source/_posts/2016-11-02-novoie-soobshchieniie.markdown

Созданный файл имеет следующую структуру:

1
2
3
4
5
6
7

---
layout: post
title: "Новое сообщение"
date: 2016-11-02 12:58:46 +0600
comments: true
categories:
---

Это каркас сообщения. Настройки интуитивно понятны, можно разрешить/запретить комментарии, указать категорию (можно указать несколько категорий), функционал аналогичен функционалу тегов. Для разделения короткого и полного текста используется тег <!-- more -->.

Для новых страниц создается новый каталог с именем создаваемой страницы. К примеру создаем новую страницу:

1
2
3

$ rake new_page["Новая страниц"]
mkdir -p source/novaia-stranitsa
Creating new page: source/novaia-stranitsa/index.markdown

В результате будет создан каталог, а уже в этом каталоге будет создан файл index.markdown со следующим содержимым:

1
2
3
4
5
6
7
8

---
layout: page
title: "Новая страница"
date: 2016-11-02 12:55
comments: true
sharing: true
footer: true
---

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

Справка по rake.

В документации Octopress на сайте разработчиков перечислены лишь несколько команд для rake: generate, deploy, new_post, new_page и др. На самом деле у rake для Octopress команд больше, посмотреть их список можно с помощью - rake list, а получить список с описанием команд можно вот так - rake -T:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

$ rake -T
rake clean                     # Очищает кэши: .pygments-cache, .gist-cache, .sass-cache
rake copydot[source,dest]      # Копирует dot-файлы для развертывания
rake deploy                    # Развертывает сгенерированный сайт на вашу платформу
rake gen_deploy                # Генерирует и развертывает сайт
rake generate                  # Генерирует сайт
rake install[theme_name]       # Устанавливает тему для сайта
rake integrate                 # Перемещает все посты, помещенные в stash командой isolate, обратно в
                               # posts-директорию, сайт при этом готов к генерации 
rake isolate[filename]         # Перемещает все посты, кроме того, над которым сейчас ведется работа,
                               # во временную директорию stash, что приводит к существенному ускорению
                               # генерации сайта
rake list                      # Показывает список доступных задач
rake new_page[filename]        # Создает новую страницу сайта в source/[filename]/index.markdown
rake new_post[title]           # Создает новый пост для сайта в source/_posts
rake preview                   # Предпросмотр сайта в браузере на локальной машине
rake push                      # Развертывает public-директорию через Git
rake rsync                     # Развертывает сайт через Rsync
rake set_root_dir[dir]         # Обновляет настройки для поддержки публикации в root или вложенную директорию
rake setup_github_pages[repo]  # Настраивает директорию _deploy и развертывает ветвь в Github Pages
rake update_source[theme]      # Перемещает source в source.old, устанавливает source theme updates,
                               # замещает source/_includes/navigation.html навигацией из source.old
rake update_style[theme]       # Перемещает sass в sass.old, устанавливает sass theme updates, заменяет
                               # sass/custom файлом sass.old/custom
rake watch                     # Предпросмотр сайта и автоматическая генерация при изменении файлов
                               # (не работает, хотя может я неправильно использую...)

Перевел в меру своих сил, если встретите неточность, пишите в комментариях.

Локализация на русский язык

К сожалению, Octopress не имеет локализации на русском языке. Но этот недостаток легко можно исправить вручную. Я ищу текст который нужно перевести с помощью команды grep.

1

$ grep -irl "comments" source

Где comments - слово которое надо перевести, а source - каталог поиска. Поиск должен проводиться в каталоге с файлами Octopress. Вы так же можете переделать саму тему. И при последующей установке темы у вас уже будет сайт на русском языке.

Для локализации дат, надо заменить содержимое файла:

1

octopress/plugin/date.rb

на это. А содержимое файла:

1

octopress/source/_includes/post/date.html

на это.