doka-guide / content

Контент Доки: статьи, картинки, демки и документация для авторов

Контент Доки

⚠️ Если сайт Доки медленно загружается или не работает совсем

Дока — это добрая энциклопедия для веб-разработчиков. Наша цель — сделать документацию по веб-разработке практичной, понятной и не унылой.

Как устроена Дока

Дока состоит из двух репозиториев: платформа на базе Eleventy собирает статьи из репозитория с контентом (мы сейчас в нём), и на выходе получается наш красивый сайт.

📘 Этот репозиторий содержит только тексты статей и материалов проекта «Дока»!

Внесите свой вклад

Дока постоянно развивается. Вы можете писать статьи, помогать с разработкой или редактированием. Вы можете всё! Прекрасный мир опенсорса 🧚‍♀️

Почитайте, чем можно помочь Доке.

Присоединяйтесь к нашему сообществу в Телеграм, чтобы быть в курсе последних новостей, или к чату, чтобы пообщаться, задать вопрос и просто хорошо провести время.

Станьте автором

Хотите писать для Доки? Вам поможет руководство по стилю.

Прочитали и готовы?

1. Форкните репозиторий с контентом и склонируйте его к себе.
2. Определитесь с форматом материала (дока или статья) и,
   • если такой статьи ещё нет, откройте форк в терминале и введите ./new.sh. Когда вы ответите на несколько вопросов, останется открыть созданный файл index.md и начать писать. Также можно создать статью вручную по инструкции.
   • если статья уже есть, откройте её, и можете работать с текстом: вносить изменения, добавлять что-то полезное.
3. Напишите статью (не забывайте сверяться с руководством по стилю). Всё, что хорошо выглядит в маркдауне, будет хорошо выглядеть на сайте. Если вы хотите предпросматривать статью локально, почитайте инструкцию по предпросмотру.
4. Дополнительные материалы: картинки, демки, блок «На практике» сохраняйте в ту же папку, в подпапки images, demos, practice и так далее.
5. Запустите автоматическую проверку орфографии командой npx yaspeller --only-errors --file-extensions ".md,.html" * (вы можете отредактировать это выражение, чтобы протестировать только те файлы, которые вы меняли).
6. Закончили? Создайте пулреквест. Вот и всё! После небольшой проверки ваш материал появится на сайте Доки!

---

Распространяется под лицензиями CC BY-NC-SA 4.0 и CC BY-NC-ND 4.0, подробнее читайте в документации.

content's Issues

Псевдокласс :default

Скринридеры (с примерами)

Особенности стилей таблицы...

Особенности стилей таблицы и почему таблицу надо верстать только таблицей и больше ничего так не верстать

блочная модель

@media

Краткая история CSS

Свойство column-gap

Псевдокласс :first-letter

Тег `<object>`

Атрибуты `defer`, `async` и разница между ними

Переменные в CSS

Свойство user-select

Рассказать, что это за свойство, когда надо использовать, какие проблемы решает. Показать в демо работу свойства. Про экспериментальные или устаревшие значения можно не рассказывать.

Референсы:

• https://developer.mozilla.org/en-US/docs/Web/CSS/user-select
• https://css-tricks.com/almanac/properties/u/user-select/

Псевдокласс :indeterminate

Таблица с дефолтными стилями

Стилизация аудио-плеера

Свойство object-position

Препроцессоры HTML

Свойство columns

Стилизация видео-плеера

Тег `<optgroup>`

Уже есть плейсхолдер.
Нужно расширить доку.
Дать подробности синтаксиса, наглядные примеры, уместные ситуации для использования и особенности стилизации.
Важно сказать про атрибуты для этого тега.
Как отдельный случай можно рассмотреть выбор всех опций в конкретной группе.

Основы цифровой гигиены и безопасности

Тег `<output>`

Псевдокласс :read-only

Описание подходов и решений к сбросу стандартных стилей

Тег embed

role-атрибуты

Псевдокласс :root

@supports

Псевдокласс :read-write

Зачем думать о доступности?

Тема

В статье можно раскрыть следующее:

• кому помогает доступность;
• как доступность помогает компания;
• как убедить коллег, что доступность важна и нужна.

Ссылки для старта

• https://mosaicofminds.medium.com/the-curb-cut-effect-how-making-public-spaces-accessible-to-people-with-disabilities-helps-everyone-d69f24c58785
• https://www.w3.org/WAI/business-case/
• https://web.dev/learn/accessibility/why/
• https://www.boia.org/blog/6-unexpected-benefits-of-web-accessibility
• https://www.essentialaccessibility.com/blog/how-to-champion-digital-accessibility-conversation-starters

Полезные ссылки по тексту и демкам в Доке

• Руководство по стилю.
• Демки.
• Про стиль демок.
• Подпись автора.

Псевдокласс :optional

Псевдоэлемент ::selection

Препроцессоры CSS

Свойство word-wrap

Рассказать подробно про это чудо-свойство. Какие значения может принимать, к каким элементам применяется.
Как можно сочетать с другими свойствами?
Показать в демо работу свойства.

Референсы:

• https://sebhastian.com/css-word-wrap/
• https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Text/Wrapping_Text

Как правильно верстать фавикон

Тема

Самые дикие примеры типа игры или анимированного фавикона.

У рецептов в Доке особая структура. В подразделе «Задача» описываем, что надо сверстать, в «Готовое решение» — добавляем финальный код и демку, в «Разбор решения» подробно рассказываем про решение.

Можете заглянуть в рецепт «Разноцветный текст» для вдохновения.

Ссылки для старта

За основу можно взять https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs.

Полезные ссылки по тексту и демкам в Доке

• Руководство по стилю.
• Демки.
• Про стиль демок.
• Подпись автора.

Поисковая оптимизация для начинающих

Свойство resize

Рассказать к каким элементам можно применять это свойство, какие значения принимает. В демках показать работу этого свойства.

Референс:

• https://developer.mozilla.org/en-US/docs/Web/CSS/resize

Псевдокласс :first-line

Создаём нормальный range

Свойство column-count

Псевдокласс :lang

Вендорные префиксы

Свойство `clip`

aria-атрибуты

Лонгрид Errors

Взять старую статью из ноушена и переделать.

Что нужно рассказать:

• типы ошибок, которые выплевывает JS
• как создавать свои ошибки

Краткая история HTML

Что такое семантика и почему нельзя всё верстать на div'ах?

Псевдокласс :target

Свойство column-width

Свойство font-smoothing