[Docs] Minor copyediting of highlighting.md

Also add `apt-get` command for installing Pygments.
This commit is contained in:
Anthony Fok 2015-02-17 01:59:40 -07:00
parent bd0de85dbc
commit cb9fa62743

View file

@ -27,24 +27,26 @@ via an embedded shortcode (see example below). If Pygments is absent from the pa
### Pygments
If you have never worked with Pygments before here is a brief primer.
If you have never worked with Pygments before, here is a brief primer.
+ install python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient.
+ run `pip install Pygments` in order to install Pygments. Once installed Pygments gives you a command `pygmentize`. Make sure it sits in your path otherwise Hugo cannot find it.
+ Install Python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient.
+ Run `pip install Pygments` in order to install Pygments. Once installed, Pygments gives you a command `pygmentize`. Make sure it sits in your PATH, otherwise Hugo cannot find it.
Hugo gives you two options, that you can set with the variable `pygmentsuseclasses` (defaut `false`) in the `config.yaml` (or `config.toml`).
On Debian and Ubuntu systems, you may also install Pygments by running `sudo apt-get install python3-pygments`.
1. color-codes for highlighting keywords are directly inserted if `pygmentsuseclasses: false` (default). See in the example below. The color-codes depend on your choice of the `pygmentsstyle` (default `"monokai"`). You can explore the different color styles on [pygments.org](http://pygments.org/) after inserting some example code.
2. if you choose `pygmentsuseclasses: true` Hugo includes class names in your code instead of color-codes. For class-names to be meaningful you need to include a `.css`-file in your website representing your color-scheme. You can either generate this `.css`-files according to this [description](http://pygments.org/docs/cmdline/) or download the standard ones from the [github pygments-css repository](https://github.com/richleland/pygments-css).
Hugo gives you two options that you can set with the variable `pygmentsuseclasses` (default `false`) in `config.toml` (or `config.yaml`).
1. Color-codes for highlighting keywords are directly inserted if `pygmentsuseclasses = false` (default). See in the example below. The color-codes depend on your choice of the `pygmentsstyle` (default `"monokai"`). You can explore the different color styles on [pygments.org](http://pygments.org/) after inserting some example code.
2. If you choose `pygmentsuseclasses = true`, Hugo includes class names in your code instead of color-codes. For class-names to be meaningful, you need to include a `.css`-file in your website representing your color-scheme. You can either generate this `.css`-files according to this [description](http://pygments.org/docs/cmdline/) or download the standard ones from the [GitHub pygments-css repository](https://github.com/richleland/pygments-css).
### Usage
Highlighting is carried out via the in-built shortcode `highlight`. `highlight` takes exactly one required parameter of language and requires a
closing shortcode.
### Example
If you want to highlight code you need to either fence the code with ``` according to Github flavored Markdown or each line must be preceeded by 4 spaces to identify each line as a line of code.
If you want to highlight code, you need to either fence the code with ``` according to GitHub Flavored Markdown or preceed each line with 4 spaces to identify each line as a line of code.
Not doing either will result in the text being rendered as HTML. This will prevent Pygment highlighting from working.
Not doing either will result in the text being rendered as HTML. This will prevent Pygments highlighting from working.
```
{{</* highlight html */>}}