Skip to content

Commit

Permalink
Format README with prettier
Browse files Browse the repository at this point in the history
  • Loading branch information
@tancnle
tancnle committed Oct 7, 2021
1 parent bee9534 commit 3b5c2aa
Showing 1 changed file with 54 additions and 55 deletions.
109 changes: 54 additions & 55 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@ gem 'rouge'

or

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

## Usage
Expand All @@ -37,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 @@ -60,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 @@ -82,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 @@ -143,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 @@ -187,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 @@ -220,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 @@ -240,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 @@ -258,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 @@ -271,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

0 comments on commit 3b5c2aa

Please sign in to comment.