Вклад в Prism Themes

Благодарим вас за участие в проекте!

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

Подача сообщений об ошибках

Если вы столкнулись с ошибкой или багом при использовании темы из этого репозитория:

  1. Убедитесь, что ошибка связана с темой, а не с Prism или одним из его плагинов. Вы можете проверить это, заменив тему на другую. Если проблема связана с Prism или одним из его плагинов, пожалуйста, перейдите в основной репозиторий.

    • Кроме того, пожалуйста, убедитесь, что у вас загружена только одна тема! Загрузка нескольких тем может привести к конфликтующим или неожиданным стилям.

  2. Проверьте существующие проблемы (как открытые, так и закрытые), чтобы узнать, сообщалось ли о них ранее и/или были ли они решены. Если проблема уже существует, пожалуйста, оставьте комментарий к ней, а не создавайте новую проблему.

  3. Open a new issue с четким и лаконичным названием, и включите любую необходимую информацию, такую как:

    • Название темы, с которой у вас возникла проблема
    • Любые плагины, которые вы используете, если применимо
    • Скриншоты и/или воспроизводимый пример
    • Информация о браузере

Проблемы безопасности

В случае проблем с безопасностью, пожалуйста, ознакомьтесь с нашей Политикой безопасности для получения подробной информации.

Обсуждение проекта

Возможно, у вас есть какие-то мысли по поводу Prism Themes, будь то состояние кода, документации, функций, которые, по вашему мнению, могут быть полезны, или вы просто хотите узнать, когда будет следующий релиз, потому что вам очень нравится последняя тема и вы хотите ее использовать! Пожалуйста, откройте новый вопрос и дайте нам знать!

Отправка запросов на исправление

Будь то документация или код, Prism Themes приветствует Pull Requests! (Если вы хотите создать совершенно новую тему, то следующий раздел Создание новых тем будет более уместен)

  1. Сделайте форк этого репозитория и создайте новую ветку. Возможно, вам не придется клонировать ее на свою машину, если вам не нужно будет регенерировать скриншоты тем. Если вам нужна помощь в какой-либо момент, пожалуйста, свяжитесь с нами через opening a new issue!

  2. Внесите изменения.

  3. Зафиксируйте изменения и включите при этом четкие и ясные сообщения о фиксации.

  4. Как только вы закончите вносить изменения, отправьте Pull Request!

    • Если ваш Pull Request решает открытую проблему (или более), пожалуйста, включите closes #issuenumber (для каждой проблемы) в описание.

  5. Сопровождающий рассмотрит ваши изменения и проанализирует их, предоставив, при необходимости, дополнительные инструкции.

Благодарим вас за отправку Pull Request! Мы очень ценим время и усилия, которые вы в него вложили :)

Создание новых тем

Темы Prism - это CSS-файлы, задающие правила для встроенного кода, блоков кода и лексем внутри них. У нас есть шаблон темы, который вы можете использовать в качестве отправной точки, поскольку он содержит дополнительные советы и детали, помимо тех, что изложены здесь. Кроме того, при разработке темы убедитесь, что соблюдены Рекомендации и требования к теме.

Как оформить...

Жетоны

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

.token.token-name {
	/* styles */
}

Здесь приведен список стандартных маркеров Prism, включая общую концепцию, лежащую в их основе, и некоторые примеры. Все эти стандартные маркеры включены в шаблон темы.

Существует ли полный список маркеров для стилизации?

Мы рады, что вы спросили! Хотя у нас есть несколько ресурсов для поиска лексем, доступных в каждом языке, у нас, к сожалению, нет списка, содержащего название каждой лексемы. Однако, для большинства случаев достаточно стандартных лексем.

Если вы хотите помочь документировать больше лексем, мы будем очень признательны за вашу помощь в основном репозитории!

Токены для конкретного языка

Возможно, вы хотите, чтобы определенный токен был оформлен по-другому в определенном языке. Например, CSS использует .important для стилизации !important, а Markdown использует тот же токен в заголовках, и вы хотите, чтобы они имели разные стили. Вы можете добиться этого с помощью следующих селекторов:

/* Tokens with the `.important` class */
.token.important {
	/* styles */
}

/* Tokens in a CSS block with the `.important` class */
.language-css .token.important {
	/* styles */
}

/* Tokens in a Markdown block with the `.important` class */
.language-markdown .token.important {
	/* styles */
}

Рекомендации по стилю кода

Мы используем stylelint для автоматической проверки стиля кода. Просто выполните npm run lint для проверки (и npm run lint-fix для исправления)!

Рекомендации и требования к теме

Ваша тема будет использоваться Prism и его плагинами, которые имеют свои собственные правила CSS по умолчанию. Чтобы обеспечить совместимость вашей темы с Prism и ее плагинами, пожалуйста, следуйте этим рекомендациям!

Не используйте переменные CSS, по крайней мере, пока

Это может показаться немного странным, но это потому, что Prism поддерживает IE11, который не поддерживает переменные CSS. Однако мы будем отказываться от поддержки IE11 в Prism V2, поэтому мы рекомендуем вам оставлять в ваших CSS-файлах закомментированные CSS-переменные (или хотя бы список использованных цветов) для более легкого перехода в дальнейшем!

Убедитесь, что ваши селекторы токенов включают класс .token

Prism добавляет класс .token к маркерам, которые он выделяет с помощью своей волшебной магии. Таким образом, все маркеры, выделенные Prism, будут включать класс .token. Когда вы объявляете стиль для конкретного маркера, пожалуйста, убедитесь, что в селекторе указан класс .token!

/* Do this */
.token.token-name {
	/* styles */
}

/* Do not do this */
.token-name {
	/* styles */
}

Поддерживайте размер шрифта 1em для блоков кода

Некоторые плагины Prism предполагают, что элементы pre и code имеют одинаковый размер шрифта, иначе будут возникать ошибки, связанные с неправильным выравниванием и так далее. Поэтому, пожалуйста, установите font-size из code[class*="language-"], pre[class*="language-"] в 1em, т.е...:

code[class*="language-"],
pre[class*="language-"] {
	font-size: 1em;
	/* more styles */
}

Повышение специфичности селектора при переопределении правил CSS по умолчанию плагинов

Если вы хотите пойти еще дальше, вы также можете стилизовать дополнительные элементы, которые плагины Prism создают в DOM!

Поскольку Prism не может обеспечить упорядочивание таблиц стилей во всех случаях, необходимо увеличить специфичность ваших селекторов для переопределений плагинов вашей темы, чтобы убедиться, что ваши переопределения, ну, переопределяются! Вот пример с плагином Show Invisibles plugin:

/* Default Show Invisibles plugin styles */
.token.tab:not(:empty):before,
.token.cr:before,
.token.lf:before,
.token.space:before {
	color: #808080;
	opacity: 0.6;
}

/* Your Show Invisibles plugin overrides */
.token.token.tab:not(:empty):before,
.token.token.cr:before,
.token.token.lf:before,
.token.token.space:before {
	/* your styles */
}

Наши шаблоны плагинов охватывают большинство, если не все, плагины и переопределения, представляющие интерес, поэтому вы можете просто взять селекторы оттуда!

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

  1. Выделение линий
  2. Номера строк
  3. Панель инструментов

Избегайте повторного объявления существующих деклараций, если/когда стилизуете плагины

Чтобы обеспечить совместимость, не следует повторно объявлять существующие декларации, если/когда стилизуются плагины. Например, плагин Line Highlight plugin начинается со следующего CSS:

/* Default Line Highlight plugin styles */
pre[data-line] {
	position: relative;
	padding: 1em 0 1em 3em;
}

.line-highlight {
	position: absolute;
	left: 0;
	right: 0;
	padding: inherit 0;
	margin-top: 1em; /* Same as .prism’s padding-top */

	background: hsla(24, 20%, 50%,.08);
	background: linear-gradient(to right, hsla(24, 20%, 50%,.1) 70%, hsla(24, 20%, 50%,0));

	pointer-events: none;

	line-height: inherit;
	white-space: pre;
}

Хотя вы можете захотеть изменить цвет фона выделенных линий, чтобы он лучше соответствовал вашей теме, нет необходимости повторно объявлять другие свойства, такие как position, left, right и так далее, поскольку эти значения не должны измениться. Кроме того, в будущем мы можем исправить ошибки в этих плагинах, связанные с изменением этих свойств по умолчанию; повторное декларирование существующих значений по умолчанию вернет эти исправленные ошибки обратно.

Ресурсы

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

Отправка ваших тем

Этот раздел предполагает некоторое знакомство с git и npm (и, конечно, что у вас установлен git и последняя версия Node.js). Если у вас есть вопросы или вам нужны дополнительные рекомендации помимо Google, пожалуйста, свяжитесь с нами через открыть новый вопрос, мы будем рады помочь!

  1. Если вы еще не сделали этого, пожалуйста, создайте форк prism-themes и клонируйте его на свою машину. Также будет разумно создать новую ветку для работы.

  2. Скопируйте ваш CSS-файл в каталог themes. Имя файла вашей темы должно иметь формат prism-<theme-name>.css.

  3. Сделайте скриншот вашей темы, выполнив следующую команду в каталоге проекта:

    npm install --dev && npx gulp screenshot

  4. Добавьте вашу тему и ее скриншот в README.

  5. Убедитесь, что все проверки пройдены, выполнив команду:

    npm test

  6. Submit a Pull Request, и мы свяжемся с вами в течение недели! (Еще, дайте нам пинг!)

Мы с нетерпением ждем вашу новую тему :)