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

Fix LANGUAGES.md link on README #1747

Merged
merged 2 commits into from
Oct 7, 2021
Merged

Fix LANGUAGES.md link on README #1747

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bee9534
Fix link to LANGUAGES.md doc
tancnle Oct 7, 2021
e422442
Format README with prettier
tancnle Oct 7, 2021
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
123 changes: 60 additions & 63 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,14 @@
[![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][] is a pure Ruby syntax highlighter. It can highlight
[over 200 different languages][], and output HTML or ANSI 256-color text.
Its HTML output is compatible with stylesheets designed for [Pygments][].

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

[Pygments]: http://pygments.org "Pygments"
[over 200 different languages][languages-doc], and output HTML
or ANSI 256-color text. Its HTML output is compatible with
stylesheets designed for [Pygments][].

[over 200 different languages]: https://rouge-ruby.github.io/docs/file.Languages.html "Languages"
[rouge]: http://rouge.jneen.net/ "Rouge"
[languages-doc]: docs/LANGUAGES.md "Languages"
[pygments]: http://pygments.org "Pygments"

## Installation

Expand All @@ -25,8 +23,8 @@ gem 'rouge'

or

```bash
$ gem install rouge
```sh
gem install rouge
```

## Usage
Expand All @@ -39,7 +37,7 @@ command line tool.
Here's a quick example of using Rouge as you would any other regular Ruby
library:

``` ruby
```ruby
require 'rouge'

# make some nice lexed html
Expand All @@ -62,17 +60,16 @@ used to highlight text wrapped in the `{% highlight %}` template tags. The
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"
[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
```sh
rougify foo.rb
rougify style monokai.sublime > syntax.css
```

## Configuration
Expand All @@ -84,57 +81,60 @@ encouraged to write your own formatter if you need something custom.

The built-in formatters are:

* `Rouge::Formatters::HTML.new` will render your code with standard class names
- `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
- `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')` will split
- `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::HTMLLineHighlighter.new(formatter, highlight_lines: [3, 5])`
- `Rouge::Formatters::HTMLLineHighlighter.new(formatter, highlight_lines: [3, 5])`
will split your code into lines and wrap the lines specified by the
`highlight_lines` option in a span with a class name specified by the
`highlight_line_class` option (default: `hll`).

* `Rouge::Formatters::HTMLLineTable.new(formatter, opts={})` will output an HTML
- `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_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

- `start_line: 1` - the number of the first row
- `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
- `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
- `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:
* `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)` is a formatter for generating
- `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)` 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.

Expand All @@ -145,7 +145,7 @@ of the HTML document, we suggest writing your own HTML formatter. This can be
accomplished by subclassing `Rouge::Formatters::HTML` and overriding specific
methods:

``` ruby
```ruby
class MyFormatter < Rouge::Formatters::HTML

# this is the main entry method. override this to customize the behavior of
Expand Down Expand Up @@ -189,16 +189,16 @@ end

### Lexer Options

* `debug: false` will print a trace of the lex on stdout.
- `debug: false` will print a trace of the lex on stdout.

* `parent: ''` allows you to specify which language the template is inside.
- `parent: ''` allows you to specify which language the template is inside.

### CSS Options

* `scope: '.highlight'` sets the CSS selector to which styles are applied,
- `scope: '.highlight'` sets the CSS selector to which styles are applied,
e.g.:

``` ruby
```ruby
Rouge::Themes::MonokaiSublime.render(scope: 'code')
```

Expand All @@ -222,16 +222,16 @@ different encoding, please convert it to UTF-8 first.

## Integrations

* Middleman:
* [middleman-syntax][] (@bhollis)
* [middleman-rouge][] (@Linuus)
* RDoc: [rdoc-rouge][] (@zzak)
* Rails: [Rouge::Rails][] (@jacobsimeon)
- Middleman:
- [middleman-syntax][] (@bhollis)
- [middleman-rouge][] (@Linuus)
- RDoc: [rdoc-rouge][] (@zzak)
- 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

Expand All @@ -242,14 +242,12 @@ developing new lexers.

### Bug Reports

Rouge uses GitHub's Issues to report bugs. You can [choose][issue_chooser] from
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][].

[issue_chooser]: https://github.com/rouge-ruby/rouge/issues/new/choose
"Choose an issue from the templates"

[Probot]: https://probot.github.io "Read more about GitHub's Probot"
[issue-chooser]: https://github.com/rouge-ruby/rouge/issues/new/choose "Choose an issue from the templates"
[probot]: https://probot.github.io "Read more about GitHub's Probot"

### Developing Lexers

Expand All @@ -260,8 +258,7 @@ 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.

[lexer-dev-doc]: https://rouge-ruby.github.io/docs/file.LexerDevelopment.html
"Rouge's lexer development guide"
[lexer-dev-doc]: https://rouge-ruby.github.io/docs/file.LexerDevelopment.html "Rouge's lexer development guide"

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
Expand All @@ -273,11 +270,11 @@ with actual code.
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
test. For example, to test just the _`ruby` lexer_ (located at path
`spec/lexers/ruby_spec.rb`) simply run the following:

``` shell
$ TEST=spec/lexers/ruby_spec.rb rake
```sh
TEST=spec/lexers/ruby_spec.rb rake
```

To test a lexer visually, run `rackup` from the top-level working directory and
Expand Down