В статьях мы приводим много сниппетов кода. Было бы круто дать возможность одной кнопкой скопировать этот код чтобы вставить потом куда-то в другое место: текстовы йредактор или песочницу.

1. Кнопка должна появляться при наведении курсора на блок кода.
2. Код должен копироваться с соблюдением форматирования.

Для уменьшения веса и большей поддержки картинок, а так же для оборачивания их в тег <figure> (чтобы иметь возможность добавить подпись при необходимости), предлагается использовать плагин Image из eleventy.

Пример работы плагина можно посмотреть в репозитории.

Возможные проблемы, которые надо исследовать:

• приём src при сборке из другого репозитория
• работа с *.gif и *.svg без преобразования в *.webp и *.jpeg
• работа с *.png там где необходим прозрачный фон

P.S. Я помню, что от *.gif планировали отказаться.

У нас есть страницы-сборщики (пример) - надо научить платформу создавать такие

Было:

• Архитектура «матрёшка», где было много зависимых слоёв, которые встраивались друг в друга.
• Из-за наличия множества встраиваний через {{ content | safe }} происходила деформация контента и было невозможно встроить необходимые плагины (например Images #3)
• Если необходимо создать страницу с боковой панелью, нужно дописывать недостающие модули в *.njk-файлах для каждой конкретной страницы.

Сделать:

• Упрощённую систему слоёв, где при создании нового контента выбираются нужные независимые элементы.
• Организовать реиспользуемые блоки в качестве инклюдов.

Сейчас трудно понять, что «Бесшовность» или «Быстродействие» — это заголовки, а это нужно для быстрого «сканирования» содержания по заголовкам, особенно в лонгридах.

Я бы предложил как минимум выделить их жирным, но нужно мнение дизайнеров.

P.S. Технически мы можем в лонгридах убрать заголовок «Как понять» второго уровня и поднять всю иерарихю подзаголовков повыше, но это несистемное решение 🙂

Сделать вывод 404 страницы

В репозитории появился htmllint (#433). Сейчас он показывает 243 ошибки (96 в шаблонах и 147 в статьях). Нужно их исправить.

Запустить скрипт проверки можно командой:

• npm run linthtml:templates для проверки шаблонов
• npm run linthtml:content для статей

Возможно, что часть ошибок не получиться исправить из-за того, что мы валидируем html у шаблонов. Это может вводить линтер в ступор. Такие ошибки обсуждаем отдельно и принимаем решение разово игнорировать ошибку или отключать правило.

О чем это?

Необходимо дать возможность при помощи makdown добавлять новые источники изображений

Сейчас картинка вставляется так

![Дока](/assets/images/logo/logo.png)

результат получаем такой

<img src="/assets/images/logo/logo.png" alt="Дока">

Что должно получиться

1. Автоматически добавлять обёртку в виде <picture>

<picture>
    <img src="/assets/images/logo/logo.png" alt="Дока">
</picture>

2. Добавлять внутрь тега <picture> нужные источники изображений

пишем:

![Дока](/assets/images/logo/logo.png|(/assets/images/logo/logo.svg|type:image/svg+xml))

получаем:

<picture>
    <source srcset="/assets/images/logo/logo.svg" type="image/svg+xml">
    <img src="/assets/images/logo/logo.png" alt="Дока">
</picture>

3. Добавлять внутрь тега размеры для retina

пишем:

![Дока](/assets/images/logo/logo.png|:(/assets/images/logo/logo.png|2x)|(/assets/images/logo/logo.svg|type:image/svg+xml))

получаем:

<picture>
    <source srcset="/assets/images/logo/logo.svg" type="image/svg+xml">
    <img srcset="/assets/images/logo/[email protected] 2x, /assets/images/logo/logo.png" src="/assets/images/logo/logo.png" alt="Дока">
</picture>

4. Добавлять media-источники

пишем:

![Дока](/assets/images/logo/logo.png|:(/assets/images/logo/logo.png|2x)|(https://y-doka.site/assets/images/logo/logo.svg|type:image/svg+xml)|(/assets/images/logo/logo.png|2x)|(/assets/images/logo/logo-small.png|media:max-width:600px))

получаем:

<picture>
    <source srcset="/assets/images/logo/logo.svg" type="image/svg+xml">
    <source srcset="/assets/images/logo/logo-small.png" media="(max-width: 600px)">
    <img srcset="/assets/images/logo/[email protected] 2x, /assets/images/logo/logo.png" src="/assets/images/logo/logo.png" alt="Дока">
</picture>

Необходимо создать файл, в котором прокинуть переменные окружения для использования внутри eleventy.

Строки для примеров из терминала традиционно начинают с символа $, чтобы показать, что это именно команда терминала.

Пример вывода:

$ git add .
$ git commit -m 'Добавляет коммит'

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

Применяться в тексте должно стандартно с указанием языка

Наш пример

    ```bash
    git add .
    git commit -m 'Добавляет коммит'
    ```

Необходимо придумать решение на CSS, как этот функционал реализовать.

Для подсветки кода используется prism (существующая настройка плагина scss, js).

В текущей версии доки реализован базовый поиск:

• при сборке собирается json с метаданными, доступный по https://y-doka.site/search-data.json
• когда пользователь начинает печатать, платформа запрашивает файл и ищет совпадение простым case-insensitive вхождением

В новой модной платформе хочется вариант покруче. Проработан вариант работы с помощью ElasticSearch, но хочется поискать другие варианты.

Требования:

• полнотекстовый нечёткий поиск или что-то сравнимое
• толерантность к опечаткам
• возможность использовать синонимы (например, promise, промис)
• быстрый ответ и нерастущие со временем runtime расходы на запрос (с двухкратным увеличением количества контента, поиск не должен стать в два раза медленнее)

Предлагается использовать для поддержки большего количества браузеров и для сборки JS-модулей Babel.

Его поддержка есть в eleventy (вот тут ссылка), устанавливается в виде зависимости eleventy-plugin-babel.

Можно не тянуть целый webpack, если он нам не нужен, и использовать только на deploy- или build-сборках.

Пока у нас JS пишется как попало и приходится руками его приводить к стилю.

• Оглавление должно быть разбито на статьи и доку
• Оглавление должно подключаться на страницу с оглавлением

Если в практике находится демка, в контентном репозитории пишется относительный адрес для контентного репозитория, платформа должна сама править адрес.

Всё работало нормально, но сегодня я сделала git pull :) И вот что происходит:

$ npm start

> start
> eleventy --serve --quiet

Eleventy fatal error: (more in DEBUG output)
> Error in your Eleventy config file 'T:/Doka/new-site/platform/.eleventy.js'. You may need to run `npm install`.

`EleventyConfigError` was thrown
> Cannot find module 'markdown-it-anchor'
Require stack:
- T:\Doka\new-site\platform\.eleventy.js
- T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\TemplateConfig.js
- T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\Config.js
- T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\TemplateEngineManager.js
- T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\EleventyExtensionMap.js
- T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\TemplateRender.js
- T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\TemplateData.js
- T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\Eleventy.js
- T:\Doka\new-site\platform\node_modules\@11ty\eleventy\cmd.js

`Error` was thrown:
    Error: Cannot find module 'markdown-it-anchor'
    Require stack:
    - T:\Doka\new-site\platform\.eleventy.js
    - T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\TemplateConfig.js
    - T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\Config.js
    - T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\TemplateEngineManager.js
    - T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\EleventyExtensionMap.js
    - T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\TemplateRender.js
    - T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\TemplateData.js
    - T:\Doka\new-site\platform\node_modules\@11ty\eleventy\src\Eleventy.js
    - T:\Doka\new-site\platform\node_modules\@11ty\eleventy\cmd.js
        at Function.Module._resolveFilename (internal/modules/cjs/loader.js:885:15)
        at Function.Module._load (internal/modules/cjs/loader.js:730:27)
        at Module.require (internal/modules/cjs/loader.js:957:19)
        at require (internal/modules/cjs/helpers.js:88:18)
        at Object.<anonymous> (T:\Doka\new-site\platform\.eleventy.js:10:26)
        at Module._compile (internal/modules/cjs/loader.js:1068:30)
        at Object.Module._extensions..js (internal/modules/cjs/loader.js:1097:10)
        at Module.load (internal/modules/cjs/loader.js:933:32)
        at Function.Module._load (internal/modules/cjs/loader.js:774:14)
        at Module.require (internal/modules/cjs/loader.js:957:19)

Делаю npm install, как он и предлагает:

$ npm install
npm ERR! code EBADENGINE
npm ERR! engine Unsupported engine
npm ERR! engine Not compatible with your version of node/npm: undefined
npm ERR! notsup Not compatible with your version of node/npm: undefined
npm ERR! notsup Required: {"node":"14.x","npm":"6.x"}
npm ERR! notsup Actual:   {"npm":"7.14.0","node":"v14.17.0"}

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\wizzz\AppData\Local\npm-cache\_logs\2021-05-21T09_35_32_972Z-debug.log

Версии такие:

$ node -v
v14.17.0

$ npm -v
7.14.0

Ось вин 10.

Мнения подключаются по алфавиту в конце статьи

1. Клонирую репо https://github.com/Y-Doka/platform.git через GitHub Desktop.
2. Получаю ошибку
   

Перелогин, перезагрузка не помогают. Прав хватает.

1. Клонирую его же через терминал — всё проходит без проблем.

Предположение: виноваты сабмодули.

Нужно подключить якоря для подзаголовков статей, нужно использовать латиницу в генерируемых адресах.

Не запускается сборка командой npm run build. Выводится ошибка:

Error: Cannot find module 'esbuild'

Ниже логи:

0 verbose cli [ '/usr/local/bin/node', '/usr/local/bin/npm', 'run', 'build' ]
1 info using [email protected]
2 info using [email protected]
3 timing npm:load:whichnode Completed in 1ms
4 timing config:load:defaults Completed in 3ms
5 timing config:load:file:/usr/local/lib/node_modules/npm/npmrc Completed in 2ms
6 timing config:load:builtin Completed in 2ms
7 timing config:load:cli Completed in 1ms
8 timing config:load:env Completed in 0ms
9 timing config:load:file:/Users/furtivite/Developer/platform/.npmrc Completed in 0ms
10 timing config:load:project Completed in 1ms
11 timing config:load:file:/Users/furtivite/.npmrc Completed in 0ms
12 timing config:load:user Completed in 0ms
13 timing config:load:file:/usr/local/etc/npmrc Completed in 0ms
14 timing config:load:global Completed in 0ms
15 timing config:load:validate Completed in 0ms
16 timing config:load:setEnvs Completed in 1ms
17 timing config:load Completed in 8ms
18 timing npm:load:configload Completed in 8ms
19 timing npm:load:setTitle Completed in 0ms
20 timing npm:load:setupLog Completed in 1ms
21 timing npm:load:cleanupLog Completed in 2ms
22 timing npm:load:configScope Completed in 0ms
23 timing npm:load:projectScope Completed in 1ms
24 timing npm:load Completed in 13ms
25 timing config:load:flatten Completed in 2ms
26 timing command:run Completed in 5011ms
27 verbose stack Error: command failed
27 verbose stack     at ChildProcess.<anonymous> (/usr/local/lib/node_modules/npm/node_modules/@npmcli/promise-spawn/index.js:64:27)
27 verbose stack     at ChildProcess.emit (events.js:315:20)
27 verbose stack     at maybeClose (internal/child_process.js:1048:16)
27 verbose stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:288:5)
28 verbose cwd /Users/furtivite/Developer/platform
29 verbose Darwin 20.3.0
30 verbose argv "/usr/local/bin/node" "/usr/local/bin/npm" "run" "build"
31 verbose node v14.16.0
32 verbose npm  v7.7.0
33 error code 1
34 error path /Users/furtivite/Developer/platform
35 error command failed
36 error command sh -c eleventy && gulp
37 verbose exit 1

Статьи могут иметь различные версии. Необходимо придумать способ вывода контента прошлых версий.

Создать конфигурационынй файл .doka.json или аналогичный. Поместить в него первое свойство конфигурации — массив папок с контентом, которые мы забираем из репозитория content

Зачем

В платформе есть одинаковые значения, которые появляются в различных файлах, но обозначают одно и то же. Пример на поверхности — название папок внутри репозитория content, которые содержат материалы: js, css, html, tools. Они указаны и в make-links.js, в Dockerfile и появляются в пул реквестах

Согласно рекомендациям команды Docker (https://docs.docker.com/develop/dev-best-practices/#how-to-keep-your-images-small), число слоев предлагается уменьшать, если это возможно. Рекомендация способствует уменьшению образа и кэша от образа. Поэтому есть предложение изменить Dockerfile на следующий вариант:

FROM node:lts-alpine

WORKDIR /platform
COPY . .

RUN npm install \
&& ln -sf ../content/css src/css \
&& ln -sf ../content/js src/js \
&& ln -sf ../content/html src/html

VOLUME /platform/content
EXPOSE 8080

ENTRYPOINT ["npm", "start"]

У меня образ собрался без проблем.

Получается четыре слоя вместо семи. Уменьшение слоев будет способствовать оптимизации хранения образов. Это особенно важно, если образ будет усложняться.

Это повысит качество ишью: можно будет сразу выбрать нужный тип и заполнить нужные поля.

Добавить обложки в статьи

Сейчас на заголовки внутри блока «В работе» (имена авторов) не вешаются якоря. Это происходит потому, что ссылки проставляются только заголовкам внутри лейаута articles.njk, а мнения находятся отдельно в practices.njk.

В #116 были введены якоря с одинаковым 'aria-label': 'Этот заголовок',, это необходимо, чтобы не имеющий значения символ был понятен людям, которые пользуются скринридером.

Тем не менее, возможно неправильно указывать везде одинаковый aria-label — нужно продумать этот момент.

Предлагается для увеличения поддержки браузерами и уменьшения размера и веса CSS-файлов использовать PostCSS, Autoprefixer и CSSnano.

Соответствующие зависимости:

npm i postcss-loader --save-dev
npm i autoprefixer --save-dev
npm i cssnano --save-dev 

Пока стили пишутся по наитию, было бы хорошо придумать стиль и придерживаться.

Есть опыт и взгляды, возьму на себя :)

У заголовка

Выводить дату коммита, сравнивать с текущей датой, высчитывать разницу и выводить текст.

У текущих фавиконок закруглённые углы. Нужно сделать их квадратными. Закругления сделает ОС.

Необходимо завести тестовую страницу с тестовым контентом, где упомянуть все варианты отображения текста со снипетами.

Поправить подключение стилей. Сейчас они подключаются некорректно.

Настроить скриытие ответов в форме

После редизайна или переноса вёрстки проверить как работает скрипт. Сейчас выдаёт ошибку из-за отсутствия необходимых элементов.

Перенести форму

Скрипты подключаются модулями

Чтобы при пулреквесте финальная сборка платформы проверялась на валидность.

Что это даёт:

1. Ловит ошибки вложенности или незакрытые блоки
2. Показывает атрибуты в неправильных местах
3. Помогает совместимости вёрстки
4. Улучшает итоговую доступность разметки

Есть несколько вариантов добавить, можно здесь поразмышлять.

Какую бы статью мы ни открыли, заголовок браузерного таба оудет одинаковым — «Дока». Нужно использовать название статьи в заголовке

И генерировать уникальные автоматически, например вот так. На будущее, мечтаю.