Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README #1271

Merged
merged 8 commits into from
Jul 30, 2019
Merged

Update README #1271

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5bec472
Update README
pyrmont Jul 23, 2019
070a999
Add express note paragraph blocks
pyrmont Jul 24, 2019
8003a06
Tweak formatting
pyrmont Jul 24, 2019
c9a3330
Correct typo
pyrmont Jul 26, 2019
4ce83f3
Replace tips section, correct typo
pyrmont Jul 26, 2019
b328f26
Correct wording
pyrmont Jul 26, 2019
04c7a4a
Revise wording for HTMLTable formatter
pyrmont Jul 28, 2019
d3f8764
Fixed punctuation error
pyrmont Jul 29, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
252 changes: 157 additions & 95 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,28 @@
[![Gem Version](https://badge.fury.io/rb/rouge.svg)](https://rubygems.org/gems/rouge)
[![YARD Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://rouge-ruby.github.io/docs/)

[rouge]: http://rouge.jneen.net/

[Rouge][] is a pure-ruby syntax highlighter. It can highlight 100 different languages, and output HTML or ANSI 256-color text. Its HTML output is compatible with stylesheets designed for [pygments][].
[Rouge][] is a pure Ruby syntax highlighter. It can highlight over 100 different
languages, and output HTML or ANSI 256-color text. Its HTML output is
compatible with stylesheets designed for [Pygments][].

If you'd like to help out with this project, assign yourself something from the [issues][] page, and send me a pull request (even if it's not done yet!). Bonus points for feature branches.
[Rouge]: http://rouge.jneen.net/ "Rouge"

[issues]: https://github.com/rouge-ruby/rouge/issues "Help Out"
[pygments]: http://pygments.org/ "Pygments"
[Pygments]: http://pygments.org "Pygments"

## Usage

First, take a look at the [pretty colors][].
Rouge's most common uses are as a Ruby library, as part of Jekyll and as a
command line tool.

[pretty colors]: http://rouge.jneen.net/
### Library

Here's a quick example of using Rouge as you would any other regular Ruby
library:

``` ruby
require 'rouge'

# make some nice lexed html
source = File.read('/etc/bashrc')
formatter = Rouge::Formatters::HTML.new
Expand All @@ -32,154 +38,210 @@ Rouge::Themes::Base16.mode(:light).render(scope: '.highlight')
Rouge::Theme.find('base16.light').render(scope: '.highlight')
```

### Full options
### Jekyll

**NOTE**: If you're using GitHub Pages, you're stuck with [version
2.2.1][ghp-versions] of Rouge. Although GitHub Pages uses an up to date version
of Jekyll, it locks the version of Rouge. There is [an open issue][ghp-issue] to
upgrade this to a more current release.

[ghp-versions]: https://pages.github.com/versions/
"Version of the dependencies used by GitHub Pages"

[ghp-issue]: https://github.com/github/pages-gem/issues/601
"pages-gem Issue #601"

Rouge is Jekyll's default syntax highlighter. Out of the box, Rouge will be
used to highlight text wrapped in the `{% highlight %}` template tags. The
`{% highlight %}` tag provides minimal options: you can specify the language to
use and whether to enable line numbers or not. More information is available in
[the Jekyll docs][j-docs].

[j-docs]: https://jekyllrb.com/docs/liquid/tags/#code-snippet-highlighting
"Code snippet highlighting in the Jekyll documentation"

### Command Line

Rouge ships with a `rougify` command which allows you to easily highlight files
in your terminal:

``` shell
$ rougify foo.rb
$ rougify style monokai.sublime > syntax.css
```

## Configuration

### Formatters

Rouge comes with a number of formatters built-in but as of Rouge 2.0, you are
encouraged to write your own formatter if you need something custom.

The built-in formatters are:

#### Formatters
* `Rouge::Formatters::HTML.new` will render your code with standard class names
for tokens, with no div-wrapping or other bells or whistles.

As of Rouge 2.0, you are encouraged to write your own formatter for custom formatting needs.
Builtin formatters include:
* `Rouge::Formatters::HTMLInline.new(theme)` will render your code with no class
names, but instead inline the styling options into the `style=` attribute.
This is good for emails and other systems where CSS support is minimal.

* `Rouge::Formatters::HTML.new` - will render your code with standard class names for tokens,
with no div-wrapping or other bells or whistles.
* `Rouge::Formatters::HTMLInline.new(theme)` - will render your code with no class names, but
instead inline the styling options into the `style=` attribute. This is good for emails and
other systems where CSS support is minimal.
* `Rouge::Formatters::HTMLLinewise.new(formatter, class: 'line-%i')`
This formatter will split your code into lines, each contained in its own div. The
`class` option will be used to add a class name to the div, given the line
number.
* `Rouge::Formatters::HTMLLineTable.new(formatter, opts={})` will output an HTML table containing
numbered lines, each contained in its own table-row. Options are:
* `Rouge::Formatters::HTMLLinewise.new(formatter, class: 'line-%i')` will split
your code into lines, each contained in its own div. The `class` option will
be used to add a class name to the div, given the line number.

* `Rouge::Formatters::HTMLLineTable.new(formatter, opts={})` will output an HTML
table containing numbered lines, each contained in its own table-row. Options
are:
* `start_line: 1` - the number of the first row
* `line_id: 'line-%i'` - a `sprintf` template for `id` attribute with current line number
* `line_id: 'line-%i'` - a `sprintf` template for `id` attribute with
current line number
* `line_class: 'lineno'` - a CSS class for each table-row
* `table_class: 'rouge-line-table'` - a CSS class for the table
* `gutter_class: 'rouge-gutter'` - a CSS class for the line-number cell
* `code_class: 'rouge-code'` - a CSS class for the code cell
* `Rouge::Formatters::HTMLPygments.new(formatter, css_class='codehilite')`
wraps the given formatter with div wrappers generally expected by stylesheets designed for
Pygments.
* `Rouge::Formatters::HTMLTable.new(formatter, opts={})` will output an HTML table containing
numbered lines. Options are:

* `Rouge::Formatters::HTMLPygments.new(formatter, css_class='codehilite')` wraps
the given formatter with div wrappers generally expected by stylesheets
designed for Pygments.

* `Rouge::Formatters::HTMLTable.new(formatter, opts={})` will output an HTML
table containing numbered lines similar to `Rouge::Formatters::HTMLLineTable`,
except that the table from this formatter has just a single table-row.
Therefore, while the table is more DOM-friendly for JavaScript scripting, long
code lines will mess with the column alignment. Options are:
* `start_line: 1` - the number of the first line
* `line_format: '%i'` - a `sprintf` template for the line number itself
* `table_class: 'rouge-table'` - a CSS class for the table
* `gutter_class: 'rouge-gutter'` - a CSS class for the gutter
* `code_class: 'rouge-code'` - a CSS class for the code column
* `Rouge::Formatters::HTMLLegacy.new(opts={})` is a backwards-compatibility class intended
for users of rouge 1.x, with options that were supported then. Options are:

* `Rouge::Formatters::HTMLLegacy.new(opts={})` is a backwards-compatibility
class intended for users of Rouge 1.x, with options that were supported then.
Options are:
* `inline_theme: nil` - use an HTMLInline formatter with the given theme
* `line_numbers: false` - use an HTMLTable formatter
* `wrap: true` - use an HTMLPygments wrapper
* `css_class: 'codehilite'` - a CSS class to use for the pygments wrapper
* `Rouge::Formatters::Terminal256.new(theme)`
* `theme` must be an instnce of `Rouge::Theme`, or a `Hash` structure with `:theme` entry
* `css_class: 'codehilite'` - a CSS class to use for the Pygments wrapper

#### Lexer options
##### debug: false
Print a trace of the lex on stdout
* `Rouge::Formatters::Terminal256.new(theme)` is a formatter for generating
highlighted text for use in the terminal. `theme` must be an instance of
`Rouge::Theme`, or a `Hash` structure with `:theme` entry.

##### parent: ''
Allows you to specify which language the template is inside
### Lexer Options

#### CSS theme options
##### scope: '.highlight'
CSS selector that styles are applied to, e.g. `Rouge::Themes::MonokaiSublime.render(scope: 'code')`
* `debug: false` will print a trace of the lex on stdout.

Rouge aims to be simple to extend, and to be a drop-in replacement for pygments, with the same quality of output. Also, Rouge ships with a `rougify` command which allows you to easily highlight files in your terminal:
* `parent: ''` allows you to specify which language the template is inside.

``` bash
$ rougify foo.rb
$ rougify style monokai.sublime > syntax.css
```
### CSS Options

### Advantages to pygments.rb
* No need to [spawn Python processes](https://github.com/tmm1/pygments.rb).
* We're faster in [almost every measure](https://github.com/rouge-ruby/rouge/pull/41#issuecomment-223751572)
* `scope: '.highlight'` sets the CSS selector to which styles are applied,
e.g.:

### Advantages to CodeRay
* The HTML output from Rouge is fully compatible with stylesheets designed for pygments.
* The lexers are implemented with a dedicated DSL, rather than being hand-coded.
* Rouge supports every language CodeRay does and more.
``` ruby
Rouge::Themes::MonokaiSublime.render(scope: 'code')
```

## You can even use it with Redcarpet
## Documentation

``` ruby
require 'redcarpet'
require 'rouge'
require 'rouge/plugins/redcarpet'
Rouge's documentation is available at [rouge-ruby.github.io/docs/][docs].

class HTML < Redcarpet::Render::HTML
include Rouge::Plugins::Redcarpet # yep, that's it.
end
```
[docs]: https://rouge-ruby.github.io/docs "Rouge's official documentation"

## Requirements

If you have `:fenced_code_blocks` enabled, you can specify languages, and even options with CGI syntax, like `php?start_inline=1`, or `erb?parent=javascript`.
### Ruby

## Encodings
Rouge is compatible with all versions of Ruby from 2.0.0 onwards. It has no
external dependencies.

Rouge is only for UTF-8 strings. If you'd like to highlight a string with a different encoding, please convert it to UTF-8 first.
### Encodings

## Other integrations
Rouge only supports UTF-8 strings. If you'd like to highlight a string with a
different encoding, please convert it to UTF-8 first.

* Middleman: [middleman-syntax](https://github.com/middleman/middleman-syntax) (@bhollis)
* Middleman: [middleman-rouge][] (@Linuus)
## Integrations

* Middleman:
* [middleman-syntax][] (@bhollis)
* [middleman-rouge][] (@Linuus)
* RDoc: [rdoc-rouge][] (@zzak)
* Rouge::Rails: [render code samples in your rails views][rouge-rails] (@jacobsimeon)
* Rails: [Rouge::Rails][] (@jacobsimeon)

[middleman-syntax]: https://github.com/middleman/middleman-syntax
[middleman-rouge]: https://github.com/Linuus/middleman-rouge
[rdoc-rouge]: https://github.com/zzak/rdoc-rouge
[rouge-rails]: https://github.com/jacobsimeon/rouge-rails
[Rouge::Rails]: https://github.com/jacobsimeon/rouge-rails

## Contributing

### Bug reports

Rouge uses GitHub issues to report bugs. You can [choose][issue-chooser] from one of our templates or create a custom issue. Issues that have not been active for a year are automatically closed by GitHub's [Probot][].
We're always exited to welcome new contributors to Rouge. By it's nature, a
syntax highlighter relies for its success on submissions from users of the
languages being highlighted. You can help Rouge by filing bug reports or
developing new lexers.

[issue-chooser]: https://github.com/rouge-ruby/rouge/issues/new/choose "Issue Template Chooser"
[Probot]: https://probot.github.io "GitHub's Probot"
### Bug Reports

### Installing Ruby
Rouge uses GitHub's Issues to report bugs. You can [choose][issue_chooser] from
one of our templates or create a custom issue. Issues that have not been active
for a year are automatically closed by GitHub's [Probot][].

If you're here to implement a lexer for your awesome language, there's a good chance you don't already have a ruby development environment set up. Follow the [instructions on the wiki](https://github.com/rouge-ruby/rouge/wiki/Setting-up-Ruby) to get up and running. If you have trouble getting set up, let me know - I'm always happy to help.
[issue_chooser]: https://github.com/rouge-ruby/rouge/issues/new/choose
"Choose an issue from the templates"

### Run the tests
[Probot]: https://probot.github.io "Read more about GitHub's Probot"

You can test the core of Rouge simply by running `rake` (no `bundle exec` required). You can also run a single test file by
setting the `TEST` environment variable to the path of the desired test. For example, to test just the *`ruby` lexer* which is
at path, `spec/lexers/ruby_spec.rb` within the repository, one may simply run the following:
### Developing Lexers

```sh
TEST=spec/lexers/ruby_spec.rb rake
```
**NOTE**: Please don't submit lexers that are copy-pasted from other files.
These submission will be rejected and we don't want you to waste your time.

It's also set up with `guard`, if you like.
We want to make it as easy as we can for anyone to contribute a lexer to Rouge.
To help get you started, we have [a shiny new guide][lexer-dev-doc] on lexer
development in the documentation. The best place is to start there.

To test a lexer visually, run `rackup` from the root and go to `localhost:9292/#{some_lexer}` where `some_lexer` is the tag or an alias of a lexer you'd like to test. If you add `?debug=1`, helpful debugging info will be printed on stdout.
[lexer-dev-doc]: https://rouge-ruby.github.io/docs/file.LexerDevelopment.html
"Rouge's lexer development guide"

### API Documentation
If you get stuck and need help, submit a pull request with what you have and
make it clear in your submission that the lexer isn't finished yet. We'll do our
best to answer any questions you have and sometimes the best way to do that is
with actual code.

is at https://rouge-ruby.github.io/docs/.
### Testing Rouge

### Developing lexers
Once you've cloned the repository from GitHub, you can test the core of Rouge
simply by running `rake` (no `bundle exec` required). You can also run a single
test file by setting the `TEST` environment variable to the path of the desired
test. For example, to test just the *`ruby` lexer* (located at path
`spec/lexers/ruby_spec.rb`) simply run the following:

We have [a guide][lexer-dev-doc] on lexer development in the documentation but you'll also learn a lot by reading through the existing lexers.
``` shell
$ TEST=spec/lexers/ruby_spec.rb rake
```

[lexer-dev-doc]: https://rouge-ruby.github.io/docs/file.LexerDevelopment.html
To test a lexer visually, run `rackup` from the top-level working directory and
you should have a web server running and ready to go. Visit
<http://localhost:9292> to see the full list of Rouge's lexers.

Please don't submit lexers that are largely copy-pasted from other files.
Once you've selected a particular lexer, you can add `?debug=1` to your URL
string to see a lot of helpful debugging info printed on stdout.

## Versioning

Rouge uses [Semantic Versioning 2.0.0][sv2].

[sv2]: http://semver.org/

## Tips
## Maintainers

I don't get paid to maintain rouge. If you've found this software useful, consider dropping a tip in the [bucket](http://cash.me/$jneen).
Rouge is largely the result of the hard work of unpaid volunteers. It was
originally developed by Jeanine Adkisson (@jneen) and is currently maintained by
Jeanine Adkisson, Drew Blessing (@dblessing), Michael Camilleri (@pyrmont) and
Goro Fuji (@gfx).

## License

Rouge is released under the MIT license. Please see the `LICENSE` file for more information.
Rouge is released under the MIT license. Please see the `LICENSE` file for more
information.