107 lines
2.3 KiB
ReStructuredText
107 lines
2.3 KiB
ReStructuredText
|
Style guide
|
||
|
|
===========
|
||
|
|
|
||
|
|
|
||
|
|
Key principle
|
||
|
|
-------------
|
||
|
|
|
||
|
|
Highlight.js themes are language agnostic.
|
||
|
|
|
||
|
|
Instead of trying to make a *rich* set of highlightable classes look good in a
|
||
|
|
handful of languages we have a *limited* set of classes that work for all
|
||
|
|
languages.
|
||
|
|
|
||
|
|
Hence, there are two important implications:
|
||
|
|
|
||
|
|
* Highlight.js styles tend to be minimalistic.
|
||
|
|
* It's not possible to exactly emulate themes from other highlighting engines.
|
||
|
|
|
||
|
|
|
||
|
|
Defining a theme
|
||
|
|
----------------
|
||
|
|
|
||
|
|
A theme is a single CSS defining styles for class names listed in the
|
||
|
|
:doc:`class reference </css-classes-reference>`. The general guideline is to
|
||
|
|
style all available classes, however an author may deliberately choose to
|
||
|
|
exclude some (for example, ``.attr`` is usually left unstyled).
|
||
|
|
|
||
|
|
You are not required to invent a separate styling for every group of class
|
||
|
|
names, it's perfectly okay to group them:
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
.hljs-string,
|
||
|
|
.hljs-section,
|
||
|
|
.hljs-selector-class,
|
||
|
|
.hljs-template-variable,
|
||
|
|
.hljs-deletion {
|
||
|
|
color: #800;
|
||
|
|
}
|
||
|
|
|
||
|
|
Use as few or as many unique style combinations as you want.
|
||
|
|
|
||
|
|
|
||
|
|
Typography and layout dos and don'ts
|
||
|
|
------------------------------------
|
||
|
|
|
||
|
|
Don't use:
|
||
|
|
|
||
|
|
* non-standard borders/margin/paddings for the root container ``.hljs``
|
||
|
|
* specific font faces
|
||
|
|
* font size, line height and anything that affects position and size of
|
||
|
|
characters within the container
|
||
|
|
|
||
|
|
Okay to use:
|
||
|
|
|
||
|
|
* colors (obviously!)
|
||
|
|
* italic, bold, underlining, etc.
|
||
|
|
* image backgrounds
|
||
|
|
|
||
|
|
These may seem arbitrary at first but it's what has shown to make sense in
|
||
|
|
practice.
|
||
|
|
|
||
|
|
There's also a common set of rules that *has* to be defined for the root
|
||
|
|
container verbatim:
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
.hljs {
|
||
|
|
display: block;
|
||
|
|
overflow-x: auto;
|
||
|
|
padding: 0.5em;
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
``.subst``
|
||
|
|
----------
|
||
|
|
|
||
|
|
One important caveat: don't forget to style ``.subst``. It's used for parsed
|
||
|
|
sections within strings and almost always should be reset to the default color:
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
.hljs,
|
||
|
|
.hljs-subst {
|
||
|
|
color: black;
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
Contributing
|
||
|
|
------------
|
||
|
|
|
||
|
|
You should include a comment at the top of the CSS file with attribution and
|
||
|
|
other meta data if necessary. The format is free:
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
/*
|
||
|
|
|
||
|
|
Fancy style (c) John Smith <email@domain.com>
|
||
|
|
|
||
|
|
*/
|
||
|
|
|
||
|
|
If you're a new contributor add yourself to the authors list in AUTHORS.en.txt
|
||
|
|
Also update CHANGES.md with your contribution.
|
||
|
|
|
||
|
|
Send your contribution as a pull request on GitHub.
|