Дока — это добрая энциклопедия для веб-разработчиков. Наша цель — сделать документацию по веб-разработке практичной, понятной и не унылой.
Дока состоит из двух репозиториев: платформа на базе Eleventy собирает статьи из репозитория с контентом (мы сейчас в нём), и на выходе получается наш красивый сайт.
📘 Этот репозиторий содержит только тексты статей и материалов проекта «Дока»!
У Доки есть два основных формата материалов: «дока» и «статья».
Дока — это справочный материал, кратко и формально описывающий некое понятие, например, свойство или тег. Как спецификация, только по-русски и понятным языком.
Статья — это расширенный материал, посвящённый определённому вопросу, с авторским мнением, примерами и рассуждениями.
Например, «Руководство по флексбоксам» не только познакомит вас со спецификацией флексбокса, но и расскажет о раскладке в целом, научит делать её при помощи флексбоксов и покажет примеры из жизни — для этого у нас есть специальный раздел «В работе», где разработчики делятся своим личным опытом по теме.
Дока постоянно развивается. Вы можете писать статьи, помогать с разработкой или редактированием. Вы можете всё! Прекрасный мир опенсорса 🧚♀️
Почитайте, чем можно помочь Доке.
Вам помогут два важных руководства:
- Клонируйте к себе репозиторий с контентом.
- Определитесь с форматом материала (дока или статья) и в соответствующем разделе (html, js, css, tools) создайте новую папку с названием статьи.
- Создайте в ней файл index.md по шаблону: дока или статья.
- Напишите статью (не забывайте сверяться с руководствами 👆). Всё, что хорошо выглядит в маркдауне, будет хорошо выглядеть на сайте. Если вы хотите предпросматривать статью локально, почитайте инструкцию по предпросмотру.
- Дополнительные материалы: картинки, демки, блок «В работе» сохраняйте в ту же папку, в подпапки images, demos, practice и так далее.
- Запустите автоматическую проверку орфографии командой
npx yaspeller **/*.{md,html}(вы можете отредактировать это выражение, чтобы протестировать только те файлы, которые вы меняли). - Закончили? Создайте пул-реквест. Вот и всё! После небольшой проверки ваш материал появится на сайте Доки!
Распространяется под лицензиями CC BY-NC-SA 4.0 и CC BY-NC-ND 4.0, подробнее читайте в документации.