Загляните в раздел Issues нашего репозитория, чтобы ознакомиться со списком актуальных задач. Мы будем рады, если вы поможете закрыть задачи с метками «хороший старт» — с ними можно справиться, даже если вы только начинаете.
Также мы будем постепенно выкладывать задачи посложнее, связанные с допиливанием сайта Доки. Дизайн и описание фичи — всё, как во взрослых опенсорсных проектах.
Если вы уже трудитесь в разработке и хотите присоединиться к команде авторов, напишите нам на [email protected], мы всегда рады обсудить новые идеи, познакомиться и подумать, как сделать самую бодрую Доку в интернете.
В каждой статье у нас есть форма обратной связи, которая помогает нам делать Доку лучше. Если вы прочитали статью, и она вам понравилась, смело жмите «лайк». Это не Инстаграм и не Юра Дудь, мы не будем спамить в ваши соцсети — вся обратная связь отправится только во внутреннюю форму фидбека для команды.
Если вы считаете тему нераскрытой или вам не понравился текст, жмите «дизлайк» и напишите в форме, чего вам не хватило. Команда авторов будет регулярно просматривать фидбек — это ляжет в основу нашей работы в следующем году. Мы делаем Доку для вас, поэтому давайте улучшать её вместе!
Авторы Доки работают в командах по вёрстке (HTML и CSS), и JavaScript (плюс инструменты). У каждой команды есть свой тимлид, который организует работу и составляет план статей.
Автор выбирает статью из списка задач, пишет текст, создаёт примеры кода, после чего статья отдаётся тимлиду, который её проверяет. Другие авторы могут заглянуть в статью и дополнить раздел «В работе» — поделиться опытом о том, как эта штука используется в реальной жизни.
Создать новую статью
Чтобы создать новый материал, сделайте несколько шагов:
-
Форкните репозиторий.
-
Откройте форк в терминале и введите
./new.sh. Ответьте на вопросы скрипта, он создаст необходимые папки и файлы и переключит ветку. Найдите созданный скриптом файлили создайте статью вручную без скрипта
-
Напишите статью в новом файле (не забывайте сверяться с руководством по стилю). Всё, что хорошо выглядит в маркдауне, будет хорошо выглядеть на сайте. Если вы хотите предпросматривать статью локально, почитайте инструкцию по предпросмотру.
-
Дополнительные материалы: картинки, блок «В работе» сохраняйте в ту же папку, в подпапки images, demos, practice и так далее.
-
Если вы хотите создать интерактивный пример, почитайте инструкцию по демкам.
-
Запустите автоматическую проверку орфографии командой
npx yaspeller --only-errors --file-extensions ".md,.html" *(вы можете отредактировать это выражение, чтобы протестировать только те файлы, которые вы меняли). -
Закоммитьте изменения и запушьте ветку в ваш форк. Описание коммита делаем на русском языке в формате «Добавляет что-то».
-
Создайте пул-реквест из вашего форка, его название и/или описание должны быть понятными. Дождитесь проверки и внесите исправления, если они потребуются по итогам ревью. Самостоятельно закрывайте ветки комментариев после внесения правок.
Все правки, которые может потребоваться внести, делайте в той же ветке — они появятся в пул-реквесте.
Изменить существующую статью
Чтобы изменить материал, который уже есть в репозитории, следуйте процессу:
- Форкните репозиторий.
- Создайте новую ветку от
main. Назовите ветку по правилам:- доработки —
update/название-статьи; - редакторские правки —
edit/название-статьи; - исправления —
fix/название-бага; - новая фича —
feature/название-фичи.
- доработки —
- Внесите изменения. Описание коммита делаем на русском языке в формате «Добавляет что-то».
- Сделайте пуш ветки.
- Создайте пул-реквест. Его название и/или описание должны быть понятными. Дождитесь проверки и внесите исправления, если они потребуются по итогам ревью. Самостоятельно закрывайте ветки комментариев после внесения правок.
Если статья принята, она направляется команде дизайнеров, которые готовят иллюстрации, схемы и оформление для примеров кода. Параллельно с этим статья публикуется на GitHub и впоследствии проверяется редактором.
Это мощный раздел, до конца дойдут не многие, но после — гарантируем вам базовое понимание того, на чём сделана Дока, и возможность действовать.
Дока состоит из двух репозиториев:
Контент Доки — это текстовые файлы в маркдауне и картинки. Если вы хотите сделать быструю правку, то можно сделать это прямо на GitHub — он поможет вам предложить их в пул-реквесте. Если вы пишете новую статью или делаете обширные правки, то лучше форкните репозиторий, склонируйте его себе локально и откройте в любимом редакторе кода.
Если вы хотите посмотреть, как ваша статья или правки выглядят и собираются в полноценный сайт, то вам поможет инструкция. Спойлер: вам потребуется Docker.
Если вы хотите посмотреть всю Доку локально без Docker, в инструкции рассказано, как запустить платформу с симлинками.
У каждой статьи есть своя папка с подпапками для картинок, демок, видео, аудио и практик (блок «В работе»).
В контентном репозитории мы пишем относительные пути. Например, так выглядит ссылка на демку из блока «В работе», которая лежит на уровень выше:
<iframe title="Блок с рваным краем, но без пробела" src="../demos/shadow/"></iframe>Каждый тип контента кладётся в свою папку. Если вам нужна папка с видео, которой ещё нет, создайте её.
Разберём это на примере гайда по flexbox.
---
title: "Гайд по flexbox"
<!-- Описание для соцсетей и поисковиков, не больше 200 символов -->
description: "Всё, что нужно знать, чтобы верстать флексбоксами как боженька"
cover:
<!-- имя автора -->
author: nick_name
<!-- адрес широкой картинки для десктопной обложки -->
desktop: 'images/covers/desktop.svg'
<!-- адрес узкой картинки для мобильной обложки -->
mobile: 'images/covers/mobile.svg'
<!-- альтернативное описание для обложки -->
alt: 'Умная собака подозрительно смотрит'
<!-- ники авторов основного текста -->
authors:
- solarrust
<!-- ники всех соавторов и тех, кто работал над текстом (дописали «В работе»? Переписали блок? Вам сюда) -->
contributors:
- furtivite
- skorobaeus
<!-- отмечаем, кто из редакторов уже прочитал, если вы видите такую отметку, добавьте редактора в новый PR -->
editors:
- tachisis
<!-- ключевые слова для SEO -->
keywords:
- флексбокс
- flexbox
tags:
<!-- тип материала: article или doka -->
- article
---
<!-- далее обычная статья в markdown -->
## Что это?
Долгое время веб существовал в статичном виде. Сайты разрабатывались и просматривались только на экранах мониторов стационарных компьютеров. В масштабах истории совсем недавно у нас появилось огромное разнообразие различных экранов — от мобильных телефонов, до телевизоров — на которых мы можем взаимодействовать с сайтами. Отсюда появилась необходимость в гибких системах раскладки.
Идея флексбоксов появилась ещё в 2009 году и по сей день этот стандарт развивается и прорабатывается. Основная идея флексов — гибкое распределение места между элементами, гибкая расстановка, выравнивание, гибкое управление. Ключевое слово **гибкое**, что и отражено в названии (_flex — англ. гибко_).Какого-то из полей в шапке может не хватать, потому что оно пока не используется. Если поле пустое: мы его не пишем, если нужно добавить новое, добавляем.
Используйте поля только там, где это необходимо. Если вам нечем заполнить поле — удалите его, не оставляйте его пустым.
К статье можно добавить обложку (хиро-картинку), которая предваряет контент:
Если вы хотите добавить обложку, позовите кого-нибудь из мейнтейнеров, мы закажем картинку у дизайнера. Картинки должны быть в формате SVG и с прозрачным фоном. Они размещаются в директории images/covers и называются: desktop.svg или mobile.svg.
Перед добавлением SVG-обложки в статью мы уменьшаем её вес вручную при помощи сервиса SVGOMG.
Также в статье используется ссылка на авторов раздела «В работе» и подписи статьи:
Создайте папку practice, если её ещё нет, и положите туда файл с вашим ником на гитхабе. Например solarrust.md.
Чтобы читатели могли узнать больше о наших авторах, мы храним их описания в папке people. Создайте собственную директорию и расскажите о себе, читайте подробнее в документации.
В статьях мы используем интерактивные примеры, они встраиваются через <iframe>. Например:
<iframe title="Блок с рваным краем, но без пробела" src="../demos/shadow/"></iframe>Встроенные в страницу демки позволяют плавнее вести повествование и демонстрировать концепции.
Визуально такие демки — интерактивная часть в стандартной вёрстке, не выделенная явно. Это главное отличие инлайновых демок от интеграций с CodePen.
Подробнее про демки читайте в отдельном документе.