Как добавлять и редактировать статьи

Неполные гайдлайны, которые постепенно будут пополняться.

Если есть какие-либо вопросы, даже глупые, напишите мне.

#Как начать

#Если у меня маленькая правка

На любой странице сайта можно нажать кнопку с карандашом сверху справа. Откроется интерфейс prose.io, в котором нужно залогиниться через GitHub, после чего можно редактировать markdown-исходник страницы. При первом сохранении автоматически создастся ветка и pull request от вашего имени, и при дальнейших он будет обновляться. Когда закончили, оставьте как есть — кто-нибудь придет и апрувнет.

Полного preview там нет — осторожнее с правкой сложных формул, если не уверены в корректности.

Иногда редактор немного меняет формат блока мета-информации в начале статьи (о нём ниже). Это нормально — только проверьте, что published / draft / date стоят такие, какие нужно.

#Если у меня большая правка

Для чего-либо серьёзного рекомендуется счекаутить репозиторий и поднять сайт локально. Это можно сделать так (предполагается, что вы знакомы с работой в терминале):

1. Поставить Hugo: скорее всего одно из sudo apt-get install hugo, sudo pacman -Syu hugo, brew install hugo или choco install hugo -confirm в зависимости от системы.
2. Форкнуть репозиторий и сделать git clone https://github.com/$USERNAME/algorithmica.git.
3. Выполнить hugo serve в корне репозитория и зайти на localhost:1313 для английской или localhost:1314 для русской версии (порты могут быть другие).
4. Найти или создать нужную статью, внести правки (в любом текстовом редакторе; они автоматически отрендерятся в браузере), запушить изменения и создать pull request в master.

Если хотите отредактировать какую-то статью, помеченную как draft (неопубликованную), нужно добавить флаг -D. Рекомендуется перед созданием PR пройтись спеллчекером (например, hunspell-ом).

Если кому-то нужна помощь с любым из этих пунктов, опять же, пишите.

#Если хочу написать новую статью

Условно готовыми считаются статьи, в которых:

• алгоритм описан и доказан,
• есть реализация,
• в реализации нет багов,
• есть хотя бы один пример задачи.

Для минимизации бесполезной работы рекомендуется сначала спросить (в telegram или в issue на гитхабе), есть ли где-то уже статья на эту тему, начал ли её уже кто-нибудь писать, нужна ли она вообще, и в какой раздел её тогда следует положить.

Многие статьи помечены как draft — это означает, что статья запланирована, но ещё только готовится. Если в них не указан автор, или указан, но последнее изменение было очень давно, то смело берите.

#Технические возможности

#Markdown

Гайд по синтаксису.

Помимо основного синтаксиса, поддерживаются ещё таблицы, блоки кода, strikethrough, latex-формулы (через один или два $) и tikz-диаграммы (через две @).

#Front matter

В начале каждой статьи есть отделяемый через --- блок метаинформации, среди которой из важной есть:

• title: название статьи
• authors: список авторов (поддерживает markdown: можете вставлять там ссылки, например)
• editors: такой же список редакторов
• date: время последнего изменения (записывать в формате 2021-08-19)
• created: когда статья была изначально опубликована (в любом формате)
• prerequisites: список ссылок (лучше относительных) на статьи-пререквизиты; лучше не указывать слишком много и избегать циклов (это не техническое ограничение, а здравый смысл)

Пример заполненной метаинформации.

#Правила русского языка

Ревьюер всё равно поправит, но, пожалуйста, имейте в виду:

1. Кавычки: « и ».
2. Дефисы, минусы и тире: -, $a-b$ (через latex) и —.
3. Предложения с формулами должны читаться как нормальные предложения (если идёт display-style формула, параграф перед ней скорее всего не заканчивается знаком препинания, а параграф после начинается со строчной, если он не является отдельным предложением).
4. Списки с перечислениями тоже должны читаться либо как отдельные предложения, либо как часть одного предложения.
5. Хеш, стек, дек — все через «е».

Удобно научиться набирать кавычки и прочие особые символы без копирования. В Linux это делается через Compose Key.

Также мы игнорируем правило про тире вместо дефиса в названиях алгоритмов с более чем одним автором («Ахо-Корасик» вместо «Ахо — Корасик») и не очень строго относимся к правилам пунктуации.

#Частые ошибки и конвенции

Небольшие технические тонкости и гайдлайны:

• Используйте только заголовки второго (##) и третьего (###) уровней. Если это очень маленькая секция, имеет смысл её выделить просто параграфом, начинающимся с bold-словом.
• Используйте либо относительные ссылки, либо абсолютные от корня сайта: /cs/tree-structures/treap/.
• Картинки вставляются через ![описание](../img/picture.png) и заливаются в локальную директорию img. Старайтесь по возможности использовать .svg вместо .png и .png вместо .jpg.
• Не используйте html, если это не какой-то исключительный случай.
• Помечайте блоки кода тегом языка, на котором они были написаны (cpp / python), иначе подсветка синтаксиса работать не будет.
• Комментарии можно и нужно использовать. Комментарии в духе общего “todo” можно указать в front matter через #, а контекстные комментарии или секции-черновики можно сделать через html-комментарии: <!-- ... -->.

#Кодстайл

Везде используются пробелы, если это не Makefile или Go.

Python. В полном соответствии с PEP.

C++:

1. Лучше использовать конкретные типы вместо метапрограммирования.
2. Абсолютно точно никаких #define forn.
3. Если в статье была однобуквенная переменная, её можно и нужно использовать в реализации. В противном случае у неё должно быть самоочевидное название.
4. Решение конкретной задачи должно быть функцией или методом. Предподсчет можно указывать либо отдельной функцией, либо как в main без самого main. Ввод-вывод никому не интересен.
5. Оставляйте комментарии на русском языке, но переменные и функции называйте на английском.

Кодстайл проще описать примерами:

template <typename T>
void f(T a, T *b, T &c) {
    // ...
}

// однострочные форы предпочтительнее
for (/* ... */)
    // ...

for (/* ... */)
    for (/* ... */)
        for (/* ... */)

// однострочные ифы тоже предпочтительнее
if (cond)
    // ...

// но не так:
if (cond) // ...

// при этом однострочные функции ок
int sum(Node *v) { return v ? v->sum : 0; }

if (cond) {
    // ...
} else if {
    // ...
} else {
    // ...
}

// иногда:
if (cond)
    // ...
else {
    // ...
}

// бесконечный цикл делается так
while (true) {
    // ...
}

sort(a.begin(), a.end(), [](int x, int y){
    return x < y;
});

int a[5] = {1, 2, 3, 4, 5};
int a[n] = {0}; // заполнить нулями

Если не указано обратного, во всех реализациях неявно предполагается, что компилятор GCC, стандарт не старше C++17, и перед блоком кода идут импорты:

#include <bits/stdc++.h>
using namespace std;

Если ваш привычный кодстайл отличается, рекомендуется воспользоваться clang-format или другими форматерами.