Дока — это справочный материал, кратко и формально описывающий некое понятие, например, свойство или тег. Как спецификация, только по-русски и понятным языком.
Мы помечаем доку тегом doka в шапке.
Структура доки примерно такова:
Код шапки
---
title: "Название доки"
description: "Описание для соцсетей, 160-200 символов"
cover:
author: nick_name
desktop: 'images/desktop.png'
mobile: 'images/mobile.png'
alt: 'Альтернативное описание для обложки'
authors:
- Никнейм основного автора
contributors:
- Никнеймы всех соавторов и контрибьюторов
editors:
- Никнеймы всех редакторов
keywords:
- Альтернативные теги для работы поиска
related:
- Ссылка на материал Доки по теме
tags:
- doka
---
<!--
1. В description есть описание для соцсетей и поисковиков, не больше 200 символов
2. В authors есть ники авторов основного текста
3. В contributors перечислены ники всех соавторов и тех, кто работал над текстом (дописали «На практике»? Переписали блок? Вам сюда)
4. В keywords записаны ключевые слова для SEO: пишем сюда слова или фразы, которых нет в тексте статьи, но по ним могут искать этот материал
5. Удалены все пустые теги в шапке
6. Подпапка автора есть в папке _people/_
7. Демки лежат в подпапке _demos/_
8. В related добавлено три ссылки на материалы, которые будут предлагаться в конце доки. Не добавляем следующий или предыдущий материал в разделе
-->
Кратко даём основное определение.
Приводим наглядный пример с кодом и визуализацией.
<div class="element"></div>
.element {
height: 100vh;
background-color: #a91517;
background-image: url("https://l.imgt.es/resource-preview-imgs/1d9806ec-7ef9-49ea-b60c-f1c9ca956b0a%2Fbaymax.crop_316x237_0%252C26.preview.png?profile=max500x190");
background-repeat: no-repeat;
}
<iframe title="Описание того, что происходит в демке" src="demos/legend-align/" height="150"></iframe>
👆 Файл index.html
с демкой кладём в папку demos, в подпапку с названием демки. Обязательно указываем высоту демки в атрибуте height
. В атрибуте title
пишем, что в демке происходит, что она иллюстрирует.
Рассказываем о синтаксисе.
Объясняем, как лучше понять этот термин, и в чём его нюансы.
💡 Делимся лайфхаками, которые помогают понять те или иные нюансы.
Мнения, рецепты и советы из личной практики разработчика, часто с примерами кода или демками. Если вы просто хотите добавить подсказку или дополнительную информацию в материал — лучше добавьте её в тело статьи в соответствующий раздел.
Чтобы написать что-то в раздел «На практике», создайте в папке статьи подпапку practice, а в ней файл в формате Markdown, поименованный вашим ником.