diff --git a/site/_docs/upgrading/2-to-3.md b/site/_docs/upgrading/2-to-3.md
index 25d38b00..8bbadd99 100644
--- a/site/_docs/upgrading/2-to-3.md
+++ b/site/_docs/upgrading/2-to-3.md
@@ -61,4 +61,14 @@ merged and some unexpected behaviour. In Jekyll 3, all layout data is accessible
 in Liquid. For example, if your layout has `class: my-layout` in its YAML front matter,
 then the layout can access that via `{% raw %}{{ layout.class }}{% endraw %}`.
 
+### Syntax highlighter changed
+
+For the first time, the default syntax highlighter has changed for the
+`highlight` tag and for backtick code blocks. Instead of [Pygments.rb][],
+it's now [Rouge][]. If you were using the `highlight` tag with certain
+options, such as `hl_lines`, they may not be available when using Rouge. To
+go back to using Pygments, set `highlighter: pygments` in your
+`_config.yml` file and run `gem install pygments.rb` or add
+`gem 'pygments.rb'` to your project's `Gemfile`.
+
 _Did we miss something? Please click "Improve this page" above and add a section. Thanks!_