Skip to content

Commit 3338341

Browse files
sslotinsslotin
committed
update guidelines
1 parent 7e6b99b commit 3338341

2 files changed

Lines changed: 38 additions & 5 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
public
22
resources
3+
.vscode

‎content/russian/contributing.md‎

Lines changed: 37 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,25 +2,29 @@
22
title: Как добавлять и редактировать статьи
33
authors:
44
- Сергей Слотин
5-
date: 2021-09-24
5+
date: 2021-09-30
66
hideSidebar: true
77
---
88

9-
Очень неполные гайдлайны, которые будут постепенно пополняться.
9+
Неполные гайдлайны, которые постепенно будут пополняться.
10+
11+
Если есть какие-либо вопросы, даже глупые, [напишите мне](https://t.me/bydlokoder).
1012

1113
## Как начать
1214

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

1517
Нужно нажать на кнопку с карандашом сверху справа. Откроется интерфейс prose.io, в котором нужно залогиниться через github, после чего можно редактировать markdown-исходник страницы.
1618

17-
При первом сохранении создастся автоматически создастся ветка и pull request от вашего имени, при дальнейших он будет обновляться. Когда закончили, оставьте как есть — кто-нибудь придет и аппрувнет.
19+
При первом сохранении автоматически создастся ветка и pull request от вашего имени, и при дальнейших он будет обновляться. Когда закончили, оставьте как есть — кто-нибудь придет и апрувнет.
1820

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

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

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

2529
1. [Поставить Hugo](https://gohugo.io/getting-started/installing/): скорее всего одно из `sudo apt-get install hugo`, `sudo pacman -Syu hugo`, `brew install hugo` или `choco install hugo -confirm` в зависимости от системы.
2630
2. `git clone https://github.com/algorithmica-org/algorithmica.git`.
@@ -29,6 +33,21 @@ hideSidebar: true
2933

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

36+
Если кому-то нужна помощь с любым из этих пунктов, опять же, пишите.
37+
38+
### Если хочу написать новую статью
39+
40+
Условно готовыми считаются статьи, в которых:
41+
42+
- алгоритм описан и доказан,
43+
- есть реализация,
44+
- в реализации нет багов,
45+
- есть хотя бы один пример задачи.
46+
47+
Для минимизации бесполезной работы рекомендуется сначала спросить (в telegram или в issue на гитхабе), есть ли где-то уже статья на эту тему, начал ли её уже кто-нибудь писать, нужна ли она вообще, и в какой раздел её тогда следует положить.
48+
49+
Многие статьи помечены как draft — это означает, что статья запланирована, но ещё только готовится. Если в них не указан автор, или указан, но последнее изменение было очень давно, то смело берите.
50+
3251
## Технические возможности
3352

3453
### Markdown
@@ -37,7 +56,7 @@ hideSidebar: true
3756

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

40-
### Frontmatter
59+
### Front matter
4160

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

@@ -52,6 +71,8 @@ hideSidebar: true
5271

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

74+
Ревьюер всё равно поправит, но пожалуйста, имейте в виду:
75+
5576
1. Кавычки: « и ».
5677
2. [Дефисы, минусы и тире](https://www.artlebedev.ru/kovodstvo/sections/97/): -, $a-b$ (через latex) и —.
5778
3. Предложения с формулами должны читаться как нормальные предложения (если идёт display-style формула, параграф перед ней скорее всего не заканчивается знаком препинания, а параграф после начинается со строчной, если он не является отдельным предложением).
@@ -62,6 +83,17 @@ hideSidebar: true
6283

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

86+
## Частые ошибки и конвенции
87+
88+
Небольшие технические тонкости и гайдлайны:
89+
90+
- Используйте только заголовки второго (`##`) и третьего (`###`) уровней. Если это очень маленькая секция, имеет смысл её выделить просто параграфом, начинающимся с **bold**-словом.
91+
- Используйте либо относительные ссылки, либо абсолютные от корня сайта: `/cs/tree-structures/treap/`.
92+
- Картинки вставляются через `![описание](../img/picture.png)` и заливаются в локальную директорию `img`.
93+
- Не используйте html, если это не какой-то исключительный случай.
94+
- Помечайте блоки кода тегом языка, на котором они были написаны (`cpp` / `python`), иначе подсветка синтаксиса работать не будет.
95+
- Комментарии можно и нужно использовать. Комментарии в духе общего "todo" можно указать в front matter через `#`, а контекстные комментарии или секции-черновики можно сделать через html-комментарии: `<!-- ... -->`.
96+
6597
## Кодстайл
6698

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

0 commit comments

Comments
 (0)