Skip to content

Latest commit

 

History

History
231 lines (156 loc) · 11.7 KB

CONTRIBUTING.md

File metadata and controls

231 lines (156 loc) · 11.7 KB
Raw

Contributing to Prism Themes

Thank you for coming on board!

There are a few ways you can contribute to Prism Themes, such as:

Filing bug reports

If you run into an error or a bug while using a theme from this repository:

  1. Confirm that the bug lies with the theme and not Prism or one of its plugins. You can check by swapping the theme out for another theme. If the issue lies with Prism or one of its plugins, please head over to the main repository instead.

    • In addition, please be sure that you only have one theme loaded! Having multiple themes loaded may result in conflicting or unexpected styles.

  2. Check existing issues (both open and closed) to see if it had previously been reported and/or resolved. If an existing issue exists, please leave a comment on it instead of creating a new issue.

  3. Open a new issue with a clear and concise title, and include any relevant information such as:

    • The name of the theme you're having an issue with
    • Any plugins that you're using, if applicable
    • Screenshots and/or a reproducible example
    • Browser information

Security issues

In the case of security issues, please check our Security Policy for details instead.

Discussing the project

Perhaps you have some thoughts on Prism Themes, whether it's the state of the code, documentation, features you think might be useful, or simply want to know when the next release will be because you really like the latest theme and want to use it! Please open a new issue and let us know!

Submitting Pull Requests

Whether it's documentation or code, Prism Themes welcomes Pull Requests! (If you're specifically looking to contribute a brand new theme, the next section on Creating new themes would be more relevant.)

  1. Fork this repository and create a new branch. It is possible that you do not have to clone it to your machine if you do not have to regenerate theme screenshots. If you need help at any point, please reach out by opening a new issue!

  2. Make the changes.

  3. Commit the changes, and include clear and concise commit messages when doing so.

  4. Once you're done making the changes, submit a Pull Request!

    • If your Pull Request resolves an open issue (or more), please include closes #issuenumber (for each issue) in the description.

  5. A maintainer will look through your changes and review them accordingly, providing further instructions where necessary.

Thank you for submitting a Pull Request! We really appreciate the time and effort you've put into it :)

Creating new themes

Prism themes are CSS files that set rules for inline code, code blocks, and the tokens within them. We have a theme template you may want to use as a starting point, as it provides additional tips and details beyond what is stated here. Additionally, when designing your theme, please make sure that the theme guidelines and requirements are adhered to.

How to style...

Tokens

To style a token, you can use a selector like:

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

While we have some resources for discovering tokens available in each language, we unfortunately do not currently have documentation for what sort of code each token targets/captures in general. But if you think you can help with that, we would really appreciate your assistance with some documentation over at the main repository!

Is there a comprehensive list of tokens to style?

We're glad you asked! Prism has quite a few tokens, but until we can get the token docs sorted out, we do not have such a list. However, covering the most common tokens should be enough for most cases, and the names of these tokens are documented in the theme template.

Tokens for a specific language

Perhaps you want a particular token to be styled differently in a certain language. For example, CSS uses .important to style !important, while Markdown uses the same token in its headings, and you want them to have different styles. You can achieve it with the following selectors:

/* 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 */
}

Code style guidelines

We use stylelint to automatically check code style. Just run npm run lint to check (and npm run lint-fix to fix)!

Theme guidelines and requirements

Your theme will be used by Prism and its plugins, which have default CSS rules of their own. To ensure that your theme is compatible with Prism and its plugins, please follow these guidelines!

Do not use CSS variables, at least not yet

This may be a little strange, but it's because Prism supports IE11, which does not support CSS variables. However, we will be dropping support for IE11 in Prism V2, so you are encouraged to leave commented-out CSS variables (or at least a list of the colours you used) in your CSS files for an easier transition later on!

Ensure that your token selectors include the .token class

Prism adds the class .token to the, well, tokens, that it highlights with its wizardry magic. As such, all tokens that are highlighted by Prism will include the .token class. When you declare a style for a specific token, please make sure to include the .token class in your selector!

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

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

Maintain a font size of 1em for code blocks

Some of Prism's plugins assume that the pre and code elements have the same font size, else there will be bugs pertaining to misaligned and so forth. As such, please set the font-size of code[class*="language-"], pre[class*="language-"] to 1em, i.e.:

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

Increase selector specificity if/when overriding the default CSS rules of plugins

If you want to take things a step further, you can also style the additional elements that Prism's plugins create in the DOM!

Since it is not possible for Prism to enforce the ordering of stylesheets in all cases, it is necessary to increase the specificity of your selectors for your theme's plugin overrides to ensure your overrides, well, override! Here's an example with the 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 */
}

Our plugin templates covers most, if not all, of the plugins and overrides of interest, so you can just grab the selectors from there!

If you'd like to prioritise plugins to style, these are the top three most popular plugins:

  1. Line Highlight
  2. Line Numbers
  3. Toolbar

Avoid re-declaring existing declarations if/when styling plugins

To ensure forward compatibility, do not re-declare existing declaration if/when styling plugins. For example, the Line Highlight plugin begins with the following 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;
}

While you might want to change the background colour of highlighted lines to fit your theme better, there is no need to redeclare other properties such as position, left, right, and so on, since those values should not change. Plus, we may fix bugs in those plugins in the future that involve changing these default properties; re-declaring the existing defaults will bring those fixed bugs right back.

Resources

Here are some resources that you may find helpful when designing and developing a new theme:

Submitting your themes

This section assumes some familiarity with git and npm (and of course, that you have git and a recent-ish version of Node.js installed). If you have any questions or need more guidance beyond Google, please reach out by opening a new issue, we'll be happy to help!

  1. If you haven't already done so, please fork prism-themes and clone it to your machine. It would also be wise to create a new branch to work on.

  2. Copy your CSS file into the themes directory. Your theme's filename must be of the format prism-<theme-name>.css.

  3. Take a screenshot of your theme by running the following command in your project's directory:

    npm install --dev && npx gulp screenshot

  4. Add your theme and its screenshot to the README.

  5. Verify that all checks pass by running:

    npm test

  6. Submit a Pull Request, and we'll get back to you within a week! (Else, give us a ping!)

We look forward to your new theme :)