Правила и рекомендации по наполнению сайта

19.01.2014 - Alexey Nurgaliev

Загрузка из репозитория и запуск

Этот сайт находится в репозитории GitHub

Для работы с репозиториями рекомендую пользоваться Atlassian SourceTree или ПО от GitHub. Также можно пользоваться консольной программой git.

В Unix-совместимых ОС (например Linux и macOS) можно воспользоваться решением от GitHub. Сначала нужно установить ruby и gem - в macOS они уже поставляются с системой, в Linux установка зависит от дистрибутива. Затем нужно выполнить в терминале sudo gem install github-pages. После этого в системе станет доступна программа jekyll и запустить сайт для тестирования можно будет командой jekyll serve (из каталога с кодом сайта). Сайт будет доступен по адресу http://localhost:4000.

Добавление статей

Новые статьи добавляются в папку _posts Имя файла статьи должно соответствовать шаблону: ГГГГ-ММ-ДД-название-статьи. Расширение файла зависит от того, какой язык разметки используется:

.html - HTML
.textile - Textile
.md или .markdown - Markdown

Все файлы проходят предварительную обработку процессором шаблонов Liquid.

Для обработки markdown используется процессор kramdown. Описание расширенного им синтаксиса markdown можно прочитать на официальном сайте.

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

Файлы с разметкой HTML дополнительно не обрабатываются.

В начале файла должен находиться текст с описанием статьи:

---
layout: post
title: Как здесь работать
author: Alexey Nurgaliev
---

Назначение полей:

layout - имя шаблона (рекомендуется post)
title - заголовок
author - автор (необязательное)

Также дополнительно можно указать поле section: чтобы поместить статью в специальный раздел сайта.

section: pskov - Олимпиадное программирование в Псков ГУ
section: programming - Изучение языков программирования, дополнительно можно указать language: название языка программирования
section: experimental - Эксперименты
section: mathematiques - Международный Чемпионат Математических и Логических Игр
section: mc - Микроконтроллеры

Далее может располагаться любой текст.

Для оформления страниц можно пользоваться библиотекой Bootstrap.

Подсветка синтаксиса

Для вставки кода с подсвеченным синтаксисом можно воспользоваться специальным тегом:

{% highlight [язык] [linenos] %}
код
{% endhighlight %}

язык - язык из списка (указывать “Short name”)
linenos - добавляется для отображения номеров строк

Пример кода с подсветкой синтаксиса:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
class PollViewTest(TestCase):

    def test_indexview_with_no_polls(self):
        response = self.client.get(reverse('polls:index'))
        self.assertEqual(response.status_code, 200)
        self.assertContains(response, "No polls are available")
        self.assertQuerysetEqual(response.context['latest_poll_list'], [])

    def test_index_view_with_a_past_poll(self):
        create_poll(question='Past poll', days=-30)
        response = self.client.get(reverse('polls:index'))
        self.assertQuerysetEqual(response.context['latest_poll_list'],
                                 ['<Poll: Past poll>'])

Математические формулы

Для вставки математических формул можно использовать MathJax.

Формулы должны быть записаны в формате LaTeX. Справочних по LaTeX

Для вставки формулы внутрь строки ее нужно заключить в $ формула $

Если формула вставляется в отдельную строку, она заключается в $$ формула $$

Замечания по языкам разметки:

HTML - формулы можно добавлять прямо в код, без дополнительной обработки
Markdown - формулы можно добавлять без обработки. Но для вставки и внутрь строки и в отдельную строку используется только блок $$ формула $$
Textile - формулы рекомендуется заключать внутрь конструкции ==блок с формулой==

Редактирование сайта

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

Назначение каталогов сайта:

_drafts - черновики статей
_includes - включаемые файлы (добавляются тегом {% include [имя_файла] %}
_layouts - шаблоны страниц
_posts - файлы статей (см. выше)
css - стили CSS
js - файлы JavaScript
img - каталог для изображений (место размещения изображений не принципиально, но рекомендуется помещать их сюда, в отдельный каталог для статьи)
docs - прочие файлы
vendor - сторонние библиотеки

Редактирование каталога ссылок

Шаблон для новой группы ссылок:

### Название группы
{: #divN }

|-|-|
[заголовок](ссылка)|описание
{: .table }

[В начало](#)