Вы могли обратить внимание, что на сайте с документацией ОСени 1сный код подсвечивается, причём весьма недурно - даже параметры аннотаций параметров методов светятся без ошибок. В общем прям как в VSCode и GitHub.
Если вы когда-то пытались встроить подсветку кода на сайт, то скорее всего вы быстро натыкалась на highlight.js. Штука, в целом, неплохая, но грамматика там не обновлялась много лет и даже в 2016ом году в подсветке в VSCode уже были фичи, которых нет в highlight.js, не говоря уже о новых штуках типа аннотаций типа
&Перед, #ИзменениеИКонтроль. Про расширения грамматики оскрипта даже думать не хочется.Авторы Vitepress, на котором построена документация, пошли по другому пути. Да, они написали/переиспользовали свой собственный хайлайтер. Но этот хайлайтер не стал изобретать свой собственный уникальный (тм) и неповторимый (r) формат для подсветки (привет, prism.js, rouge, codemirror, pygments и ещё минимум пяток известных мне систем токенизации, и даже телега отличилась как обычно). Они взяли тот же самый TextMate, на котором работает VSCode, Atom, SublimeText, GitHub и даже в Intellij IDEA есть поддержка, и построили разукрашку поверх него.
Называется эта разукрашка Shiki и живёт по адресу https://shiki.style
Недавно я добавил поддержку языка 1С для этой разукрашки, и на главной теперь можно выбрать как bsl, так и sdbl. Не знаю почему, но кириллица и 1сные запросы выглядят весьма комично на фоне того богатства языков, что доступны в селекторе - а там их за сотню.
Что самое приятное - так же как и подсветка на GitHub, авторы Shiki автоматом подтягивают обновления грамматик из репозитория в организации 1c-syntax. То есть при выходе новых версий грамматики мне больше не надо ломать голову, а куда ещё это надо дотащить - автоматика на их стороне сама все обновит и выпустит новый релиз.
Shiki содержит несколько бомбических фич, которые позволяют делать документацию нагляднее. Это например:
- фокус в блоках кода
- диффы и предупреждения
- нумерацию строк (привет, конфигуратор)
- и абсолютно шедевральный magic move, очень рекомендую посмотреть видосик на этой странице.
Все эти фичи постепенно будут появляться в документации к осени, например, работу фокуса можно оценить здесь.
Используйте богатые инструменты презентации, и пусть ваша документация будет блестящей и шелковистой
