mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-11-26 08:53:21 +00:00
Merge pull request #271495 from pennae/docs-source-highlighting
docs: improve source highlighting
This commit is contained in:
Silvan Mosberger
GitHub
commit
4487f72c5d
@ -90,6 +90,9 @@ insert_final_newline = unset
|
||||
indent_style = unset
|
||||
trim_trailing_whitespace = unset
|
||||
|
||||
[pkgs/misc/documentation-highlighter/**]
|
||||
insert_final_newline = unset
|
||||
|
||||
[pkgs/servers/dict/wordnet_structures.py]
|
||||
trim_trailing_whitespace = unset
|
||||
|
||||
|
||||
@ -1,24 +1,29 @@
|
||||
Copyright (c) 2006, Ivan Sagalaev
|
||||
BSD 3-Clause License
|
||||
|
||||
Copyright (c) 2006, Ivan Sagalaev.
|
||||
All rights reserved.
|
||||
|
||||
Redistribution and use in source and binary forms, with or without
|
||||
modification, are permitted provided that the following conditions are met:
|
||||
|
||||
* Redistributions of source code must retain the above copyright
|
||||
notice, this list of conditions and the following disclaimer.
|
||||
* Redistributions in binary form must reproduce the above copyright
|
||||
notice, this list of conditions and the following disclaimer in the
|
||||
documentation and/or other materials provided with the distribution.
|
||||
* Neither the name of highlight.js nor the names of its contributors
|
||||
may be used to endorse or promote products derived from this software
|
||||
without specific prior written permission.
|
||||
* Redistributions of source code must retain the above copyright notice, this
|
||||
list of conditions and the following disclaimer.
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
|
||||
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
||||
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||
DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
|
||||
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
||||
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
||||
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
* Redistributions in binary form must reproduce the above copyright notice,
|
||||
this list of conditions and the following disclaimer in the documentation
|
||||
and/or other materials provided with the distribution.
|
||||
|
||||
* Neither the name of the copyright holder nor the names of its
|
||||
contributors may be used to endorse or promote products derived from
|
||||
this software without specific prior written permission.
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
||||
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
||||
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
||||
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
@ -1,132 +1,30 @@
|
||||
This file was generated with pkgs/misc/documentation-highlighter/update.sh
|
||||
|
||||
# Highlight.js
|
||||
# Highlight.js CDN Assets
|
||||
|
||||
[](https://travis-ci.org/isagalaev/highlight.js)
|
||||
[](https://packagephobia.now.sh/result?p=highlight.js)
|
||||
|
||||
**This package contains only the CDN build assets of highlight.js.**
|
||||
|
||||
This may be what you want if you'd like to install the pre-built distributable highlight.js client-side assets via NPM. If you're wanting to use highlight.js mainly on the server-side you likely want the [highlight.js][1] package instead.
|
||||
|
||||
To access these files via CDN:<br>
|
||||
https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@latest/build/
|
||||
|
||||
**If you just want a single .js file with the common languages built-in:
|
||||
<https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@latest/build/highlight.min.js>**
|
||||
|
||||
---
|
||||
|
||||
## Highlight.js
|
||||
|
||||
Highlight.js is a syntax highlighter written in JavaScript. It works in
|
||||
the browser as well as on the server. It works with pretty much any
|
||||
markup, doesn’t depend on any framework and has automatic language
|
||||
markup, doesn’t depend on any framework, and has automatic language
|
||||
detection.
|
||||
|
||||
## Getting Started
|
||||
|
||||
The bare minimum for using highlight.js on a web page is linking to the
|
||||
library along with one of the styles and calling
|
||||
[`initHighlightingOnLoad`][1]:
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="/path/to/styles/default.css">
|
||||
<script src="/path/to/highlight.pack.js"></script>
|
||||
<script>hljs.initHighlightingOnLoad();</script>
|
||||
```
|
||||
|
||||
This will find and highlight code inside of `<pre><code>` tags; it tries
|
||||
to detect the language automatically. If automatic detection doesn’t
|
||||
work for you, you can specify the language in the `class` attribute:
|
||||
|
||||
```html
|
||||
<pre><code class="html">...</code></pre>
|
||||
```
|
||||
|
||||
The list of supported language classes is available in the [class
|
||||
reference][2]. Classes can also be prefixed with either `language-` or
|
||||
`lang-`.
|
||||
|
||||
To disable highlighting altogether use the `nohighlight` class:
|
||||
|
||||
```html
|
||||
<pre><code class="nohighlight">...</code></pre>
|
||||
```
|
||||
|
||||
## Custom Initialization
|
||||
|
||||
When you need a bit more control over the initialization of
|
||||
highlight.js, you can use the [`highlightBlock`][3] and [`configure`][4]
|
||||
functions. This allows you to control *what* to highlight and *when*.
|
||||
|
||||
Here’s an equivalent way to calling [`initHighlightingOnLoad`][1] using
|
||||
jQuery:
|
||||
|
||||
```javascript
|
||||
$(document).ready(function() {
|
||||
$('pre code').each(function(i, block) {
|
||||
hljs.highlightBlock(block);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
You can use any tags instead of `<pre><code>` to mark up your code. If
|
||||
you don't use a container that preserve line breaks you will need to
|
||||
configure highlight.js to use the `<br>` tag:
|
||||
|
||||
```javascript
|
||||
hljs.configure({useBR: true});
|
||||
|
||||
$('div.code').each(function(i, block) {
|
||||
hljs.highlightBlock(block);
|
||||
});
|
||||
```
|
||||
|
||||
For other options refer to the documentation for [`configure`][4].
|
||||
|
||||
|
||||
## Web Workers
|
||||
|
||||
You can run highlighting inside a web worker to avoid freezing the browser
|
||||
window while dealing with very big chunks of code.
|
||||
|
||||
In your main script:
|
||||
|
||||
```javascript
|
||||
addEventListener('load', function() {
|
||||
var code = document.querySelector('#code');
|
||||
var worker = new Worker('worker.js');
|
||||
worker.onmessage = function(event) { code.innerHTML = event.data; }
|
||||
worker.postMessage(code.textContent);
|
||||
})
|
||||
```
|
||||
|
||||
In worker.js:
|
||||
|
||||
```javascript
|
||||
onmessage = function(event) {
|
||||
importScripts('<path>/highlight.pack.js');
|
||||
var result = self.hljs.highlightAuto(event.data);
|
||||
postMessage(result.value);
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Getting the Library
|
||||
|
||||
You can get highlight.js as a hosted, or custom-build, browser script or
|
||||
as a server module. Right out of the box the browser script supports
|
||||
both AMD and CommonJS, so if you wish you can use RequireJS or
|
||||
Browserify without having to build from source. The server module also
|
||||
works perfectly fine with Browserify, but there is the option to use a
|
||||
build specific to browsers rather than something meant for a server.
|
||||
Head over to the [download page][5] for all the options.
|
||||
|
||||
**Don't link to GitHub directly.** The library is not supposed to work straight
|
||||
from the source, it requires building. If none of the pre-packaged options
|
||||
work for you refer to the [building documentation][6].
|
||||
|
||||
**The CDN-hosted package doesn't have all the languages.** Otherwise it'd be
|
||||
too big. If you don't see the language you need in the ["Common" section][5],
|
||||
it can be added manually:
|
||||
|
||||
```html
|
||||
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.4.0/languages/go.min.js"></script>
|
||||
```
|
||||
|
||||
**On Almond.** You need to use the optimizer to give the module a name. For
|
||||
example:
|
||||
|
||||
```
|
||||
r.js -o name=hljs paths.hljs=/path/to/highlight out=highlight.js
|
||||
```
|
||||
|
||||
If you'd like to read the full README:<br>
|
||||
<https://github.com/highlightjs/highlight.js/blob/main/README.md>
|
||||
|
||||
## License
|
||||
|
||||
@ -137,16 +35,13 @@ for details.
|
||||
|
||||
The official site for the library is at <https://highlightjs.org/>.
|
||||
|
||||
The Github project may be found at: <https://github.com/highlightjs/highlight.js>
|
||||
|
||||
Further in-depth documentation for the API and other topics is at
|
||||
<http://highlightjs.readthedocs.io/>.
|
||||
|
||||
Authors and contributors are listed in the [AUTHORS.en.txt][8] file.
|
||||
A list of the Core Team and contributors can be found in the [CONTRIBUTORS.md][8] file.
|
||||
|
||||
[1]: http://highlightjs.readthedocs.io/en/latest/api.html#inithighlightingonload
|
||||
[2]: http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html
|
||||
[3]: http://highlightjs.readthedocs.io/en/latest/api.html#highlightblock-block
|
||||
[4]: http://highlightjs.readthedocs.io/en/latest/api.html#configure-options
|
||||
[5]: https://highlightjs.org/download/
|
||||
[6]: http://highlightjs.readthedocs.io/en/latest/building-testing.html
|
||||
[7]: https://github.com/isagalaev/highlight.js/blob/master/LICENSE
|
||||
[8]: https://github.com/isagalaev/highlight.js/blob/master/AUTHORS.en.txt
|
||||
[1]: https://www.npmjs.com/package/highlight.js
|
||||
[7]: https://github.com/highlightjs/highlight.js/blob/main/LICENSE
|
||||
[8]: https://github.com/highlightjs/highlight.js/blob/main/CONTRIBUTORS.md
|
||||
|
||||
File diff suppressed because one or more lines are too long
@ -1,7 +1,6 @@
|
||||
/* This file is NOT part of highlight.js */
|
||||
document.onreadystatechange = function () {
|
||||
var listings = document.querySelectorAll('.programlisting, .screen');
|
||||
for (i = 0; i < listings.length; ++i) {
|
||||
hljs.highlightBlock(listings[i]);
|
||||
}
|
||||
}
|
||||
document.addEventListener('DOMContentLoaded', (event) => {
|
||||
document.querySelectorAll('.programlisting, .screen').forEach((element) => {
|
||||
hljs.highlightElement(element);
|
||||
});
|
||||
});
|
||||
|
||||
@ -1,17 +1,18 @@
|
||||
pre code.hljs {
|
||||
display: block;
|
||||
overflow-x: auto;
|
||||
padding: 1em
|
||||
}
|
||||
code.hljs {
|
||||
padding: 3px 5px
|
||||
}
|
||||
/*
|
||||
Five-color theme from a single blue hue.
|
||||
*/
|
||||
.hljs {
|
||||
display: block;
|
||||
overflow-x: auto;
|
||||
padding: 0.5em;
|
||||
background: #eaeef3;
|
||||
color: #00193a
|
||||
}
|
||||
|
||||
.hljs {
|
||||
color: #00193a;
|
||||
}
|
||||
|
||||
.hljs-keyword,
|
||||
.hljs-selector-tag,
|
||||
.hljs-title,
|
||||
@ -19,13 +20,11 @@
|
||||
.hljs-doctag,
|
||||
.hljs-name,
|
||||
.hljs-strong {
|
||||
font-weight: bold;
|
||||
font-weight: bold
|
||||
}
|
||||
|
||||
.hljs-comment {
|
||||
color: #738191;
|
||||
color: #738191
|
||||
}
|
||||
|
||||
.hljs-string,
|
||||
.hljs-title,
|
||||
.hljs-section,
|
||||
@ -38,9 +37,8 @@
|
||||
.hljs-name,
|
||||
.hljs-selector-id,
|
||||
.hljs-selector-class {
|
||||
color: #0048ab;
|
||||
color: #0048ab
|
||||
}
|
||||
|
||||
.hljs-meta,
|
||||
.hljs-subst,
|
||||
.hljs-symbol,
|
||||
@ -51,9 +49,8 @@
|
||||
.hljs-template-variable,
|
||||
.hljs-link,
|
||||
.hljs-bullet {
|
||||
color: #4c81c9;
|
||||
color: #4c81c9
|
||||
}
|
||||
|
||||
.hljs-emphasis {
|
||||
font-style: italic;
|
||||
}
|
||||
font-style: italic
|
||||
}
|
||||
@ -21,19 +21,21 @@ trap finish EXIT
|
||||
mkdir $scratch/src
|
||||
cd $scratch/src
|
||||
|
||||
token=$(curl https://highlightjs.org/download/ -c "$scratch/jar" \
|
||||
| grep csrf \
|
||||
| cut -d"'" -f6)
|
||||
curl \
|
||||
-X POST \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"api": 2,
|
||||
"languages": ["bash", "nix", "shell"]
|
||||
}' \
|
||||
https://highlightjs.org/api/download > $scratch/out.zip
|
||||
|
||||
curl --header "Referer: https://highlightjs.org/download/"\
|
||||
-b "$scratch/jar" \
|
||||
--data "csrfmiddlewaretoken=$token&nix.js=on&bash.js=on" \
|
||||
https://highlightjs.org/download/ > $scratch/out.zip
|
||||
|
||||
unzip "$scratch/out.zip"
|
||||
out="$root/"
|
||||
mkdir -p "$out"
|
||||
cp ./{highlight.pack.js,LICENSE,styles/mono-blue.css} "$out"
|
||||
cp ./highlight.min.js "$out/highlight.pack.js"
|
||||
cp ./{LICENSE,styles/mono-blue.css} "$out"
|
||||
|
||||
(
|
||||
echo "This file was generated with pkgs/misc/documentation-highlighter/update.sh"
|
||||
|
||||
@ -97,8 +97,8 @@ class HTMLRenderer(Renderer):
|
||||
def strong_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:
|
||||
return "</strong></span>"
|
||||
def fence(self, token: Token, tokens: Sequence[Token], i: int) -> str:
|
||||
# TODO use token.info. docbook doesn't so we can't yet.
|
||||
return f'<pre class="programlisting">\n{escape(token.content)}</pre>'
|
||||
info = f" {escape(token.info, True)}" if token.info != "" else ""
|
||||
return f'<pre><code class="programlisting{info}">{escape(token.content)}</code></pre>'
|
||||
def blockquote_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:
|
||||
return '<div class="blockquote"><blockquote class="blockquote">'
|
||||
def blockquote_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:
|
||||
|
||||
@ -496,8 +496,8 @@ class OptionsHTMLRenderer(OptionDocsRestrictions, HTMLRenderer):
|
||||
token.meta['compact'] = False
|
||||
return super().bullet_list_open(token, tokens, i)
|
||||
def fence(self, token: Token, tokens: Sequence[Token], i: int) -> str:
|
||||
# TODO use token.info. docbook doesn't so we can't yet.
|
||||
return f'<pre class="programlisting">{html.escape(token.content)}</pre>'
|
||||
info = f" {html.escape(token.info, True)}" if token.info != "" else ""
|
||||
return f'<pre><code class="programlisting{info}">{html.escape(token.content)}</code></pre>'
|
||||
|
||||
class HTMLConverter(BaseConverter[OptionsHTMLRenderer]):
|
||||
__option_block_separator__ = ""
|
||||
|
||||
@ -204,8 +204,10 @@ def test_full() -> None:
|
||||
<div class="blockquote">
|
||||
<blockquote class="blockquote">
|
||||
<p>with <span class="emphasis"><em>nesting</em></span></p>
|
||||
<pre class="programlisting">↵
|
||||
nested code block↵
|
||||
<pre>
|
||||
<code class="programlisting">
|
||||
nested code block↵
|
||||
</code>
|
||||
</pre>
|
||||
</blockquote>
|
||||
</div>
|
||||
@ -213,8 +215,10 @@ def test_full() -> None:
|
||||
<ul class="itemizedlist compact" style="list-style-type: disc;">
|
||||
<li class="listitem"><p>and lists</p></li>
|
||||
<li class="listitem">
|
||||
<pre class="programlisting">↵
|
||||
containing code↵
|
||||
<pre>
|
||||
<code class="programlisting">
|
||||
containing code↵
|
||||
</code>
|
||||
</pre>
|
||||
</li>
|
||||
</ul>
|
||||
@ -240,11 +244,15 @@ def test_full() -> None:
|
||||
</p>
|
||||
</blockquote>
|
||||
</div>
|
||||
<pre class="programlisting">↵
|
||||
code block↵
|
||||
<pre>
|
||||
<code class="programlisting">
|
||||
code block↵
|
||||
</code>
|
||||
</pre>
|
||||
<pre class="programlisting">↵
|
||||
fenced block↵
|
||||
<pre>
|
||||
<code class="programlisting">
|
||||
fenced block↵
|
||||
</code>
|
||||
</pre>
|
||||
<p>text</p>
|
||||
</dd>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user