mirror of
https://github.com/YunoHost/doc.git
synced 2024-09-03 20:06:26 +02:00
181 lines
8.7 KiB
Markdown
181 lines
8.7 KiB
Markdown
# Grav Highlight Plugin
|
|
|
|
|
|
|
|
`highlight` is a [Grav](http://github.com/getgrav/grav) plugin that adds simple and powerful code highlighting functionality utilizing [Highlight.js](https://highlightjs.org/).
|
|
|
|
> Highlight.js: v10.5.0
|
|
> Highlight.js line numbers [plugin](https://github.com/wcoder/highlightjs-line-numbers.js/): v2.8.0
|
|
|
|
# Installation
|
|
|
|
Installing the Highlight plugin can be done in one of two ways. Our GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.
|
|
|
|
## GPM Installation (Preferred)
|
|
|
|
The simplest way to install this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm) through your system's Terminal (also called the command line). From the root of your Grav install type:
|
|
|
|
bin/gpm install highlight
|
|
|
|
This will install the Highlight plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/highlight`.
|
|
|
|
## Manual Installation
|
|
|
|
To install this plugin, just download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the folder to `highlight`. You can find these files either on [GitHub](https://github.com/getgrav/grav-plugin-highlight) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
|
|
|
|
You should now have all the plugin files under
|
|
|
|
/your/site/grav/user/plugins/highlight
|
|
|
|
>> NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav), the [Error](https://github.com/getgrav/grav-plugin-error) and [Problems](https://github.com/getgrav/grav-plugin-problems) plugins, and a theme to be installed in order to operate.
|
|
|
|
# Usage
|
|
|
|
To best understand how Highlight works, you should read through the original project [documentation](https://highlightjs.org/usage/).
|
|
|
|
You can override any default settings from the page headers:
|
|
|
|
eg:
|
|
|
|
---
|
|
title: Sample Code With Custom Theme
|
|
highlight:
|
|
theme: monokai
|
|
---
|
|
|
|
```
|
|
@font-face {
|
|
font-family: Chunkfive; src: url('Chunkfive.otf');
|
|
}
|
|
|
|
body, .usertext {
|
|
color: #F0F0F0; background: #600;
|
|
font-family: Chunkfive, sans;
|
|
}
|
|
|
|
@import url(print.css);
|
|
@media print {
|
|
a[href^=http]::after {
|
|
content: attr(href)
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
You can also disable highlighting for a particular page if causes issues:
|
|
|
|
---
|
|
title: Sample Code with Highlight disabled
|
|
highlight:
|
|
enabled: false
|
|
---
|
|
|
|
```
|
|
@font-face {
|
|
font-family: Chunkfive; src: url('Chunkfive.otf');
|
|
}
|
|
|
|
body, .usertext {
|
|
color: #F0F0F0; background: #600;
|
|
font-family: Chunkfive, sans;
|
|
}
|
|
|
|
@import url(print.css);
|
|
@media print {
|
|
a[href^=http]::after {
|
|
content: attr(href)
|
|
}
|
|
}
|
|
```
|
|
|
|
Further, you can also enable line numbers on a specific page, or globally (in highlight.yaml):
|
|
|
|
---
|
|
title: Sample Code with Highlight and line numbers enabled
|
|
highlight:
|
|
enabled: true
|
|
lines: true
|
|
---
|
|
|
|
Valid theme options include:
|
|
|
|
| | | |
|
|
| :------------------------ | :-------------------- | :--------------------- |
|
|
| a11y-dark | darcula | nnfx-dark
|
|
| a11y-light | dark | nord
|
|
| agate | default | obsidian
|
|
| an-old-hope | docco | ocean
|
|
| androidstudio | dracula | paraiso-dark
|
|
| arduino-light | far | paraiso-light
|
|
| arta | foundation | pojoaque
|
|
| ascetic | github | purebasic
|
|
| atelier-cave-dark | github-gist | qtcreator_dark
|
|
| atelier-cave-light | gml | qtcreator_light
|
|
| atelier-dune-dark | googlecode | railscasts
|
|
| atelier-dune-light | gradient-dark | rainbow
|
|
| atelier-estuary-dark | gradient-light | routeros
|
|
| atelier-estuary-light | grayscale | school-book
|
|
| atelier-forest-dark | gruvbox-dark | school-book
|
|
| atelier-forest-light | gruvbox-light | shades-of-purple
|
|
| atelier-heath-dark | highlightjs-line-numbers | solarized-dark
|
|
| atelier-heath-light | hopscotch | solarized-light
|
|
| atelier-lakeside-dark | hybrid | srcery
|
|
| atelier-lakeside-light | idea | stackoverflow-dark
|
|
| atelier-plateau-dark | ir-black | stackoverflow-light
|
|
| atelier-plateau-light | isbl-editor-dark | sunburst
|
|
| atelier-savanna-dark | isbl-editor-light | tomorrow
|
|
| atelier-savanna-light | kimbie.dark | tomorrow-night
|
|
| atelier-seaside-dark | kimbie.light | tomorrow-night-blue
|
|
| atelier-seaside-light | learn | tomorrow-night-bright
|
|
| atelier-sulphurpool-dark | lightfair | tomorrow-night-eighties
|
|
| atelier-sulphurpool-light | lioshi | vs
|
|
| atom-one-dark | magula | vs2015
|
|
| atom-one-dark-reasonable | mono-blue | xcode
|
|
| atom-one-light | monokai | xt256
|
|
| brown-paper | monokai-sublime | zenburn
|
|
| codepen-embed | night-owl |
|
|
| color-brewer | nnfx |
|
|
|
|
Check out a [live demo](https://highlightjs.org/static/demo/) of these themes.
|
|
|
|
Following languages are supported:
|
|
|
|
| | | |
|
|
| :--------------------- | :-------------------- | :---------------------- |
|
|
| .properties | JSON | R |
|
|
| Apache config | Kotlin | Ruby |
|
|
| Bash | Less | Rust |
|
|
| C | Lua | SCSS |
|
|
| C# | Makefile | Shell Session |
|
|
| C++ | Markdown | SQL |
|
|
| CoffeeScript | Nginx config | Swift |
|
|
| CSS | Objective-C | TOML, also INI |
|
|
| Diff | Perl | Twig |
|
|
| Go | PHP | TypeScript |
|
|
| HTML, XML | PHP Template | Visual Basic .NET |
|
|
| HTTP | Plain text | YAML |
|
|
| Java | Python | |
|
|
| JavaScript | Python REPL | |
|
|
|
|
# Updating
|
|
|
|
As development for the Highlight plugin continues, new versions may become available that add additional features and functionality, improve compatibility with newer Grav releases, and generally provide a better user experience. Updating Highlight is easy, and can be done through Grav's GPM system, as well as manually.
|
|
|
|
## GPM Update (Preferred)
|
|
|
|
The simplest way to update this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm). You can do this with this by navigating to the root directory of your Grav install using your system's Terminal (also called command line) and typing the following:
|
|
|
|
bin/gpm update highlight
|
|
|
|
This command will check your Grav install to see if your Highlight plugin is due for an update. If a newer release is found, you will be asked whether or not you wish to update. To continue, type `y` and hit enter. The plugin will automatically update and clear Grav's cache.
|
|
|
|
## Manual Update
|
|
|
|
Manually updating Highlight is pretty simple. Here is what you will need to do to get this done:
|
|
|
|
* Delete the `your/site/user/plugins/highlight` directory.
|
|
* Downalod the new version of the Highlight plugin from either [GitHub](https://github.com/getgrav/grav-plugin-highlight) or [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
|
|
* Unzip the zip file in `your/site/user/plugins` and rename the resulting folder to `highlight`.
|
|
* Clear the Grav cache. The simplest way to do this is by going to the root Grav directory in terminal and typing `bin/grav clear-cache`.
|
|
|
|
> Note: Any changes you have made to any of the files listed under this directory will also be removed and replaced by the new set. Any files located elsewhere (for example a YAML settings file placed in `user/config/plugins`) will remain intact.
|