minor documentation improvements

README.md

@@ -32,23 +32,23 @@ _The [IPS/Kb ratio](http://ddnexus.github.io/pagination-comparison/gems.html#eff
 
 ### Straightforward Code
 
-- Pagy is just ~100 lines of simple ruby, organized in 3 flat modules very easy to understand and use _(see [API](https://ddnexus.github.io/pagy/api))_
-- No dependencies: it produces its own HTML, URLs, pluralization and interpolation with its own specialized and fast code _(see [why](https://ddnexus.github.io/pagy/index#specialized-code-instead-of-generic-helpers))_
+- Pagy is just ~100 lines of simple ruby, organized in 3 flat modules very easy to understand and use _(see [more...](https://ddnexus.github.io/pagy/api))_
+- No dependencies: it produces its own HTML, URLs, pluralization and interpolation with its own specialized and fast code _(see [why...](https://ddnexus.github.io/pagy/index#specialized-code-instead-of-generic-helpers))_
 - 100% of its methods are public API, accessible and overridable **right where you use them** (no need of monkey patching or subclassing)
 
 ### Totally Agnostic
 
-- It doesn't need to know anything about your models, ORM or storage, so it doesn't add any code to them _(see [why](https://ddnexus.github.io/pagy/index#stay-away-from-the-models))_
-- It works with all kinds of collections, even pre-paginated, records, Arrays, JSON data... and just whatever you can count _(see [how](https://ddnexus.github.io/pagy/how-to#paginate-any-collection))_
-- It works with all Rack frameworks (Rails, Sinatra, Padrino, ecc.) out of the box
-- It works with any possible non-Rack environment by just overriding one or two two-lines methods
+- It doesn't need to know anything about your models, ORM or storage, so it doesn't add any code to them _(see [why...](https://ddnexus.github.io/pagy/index#stay-away-from-the-models))_
+- It works with all kinds of collections, even pre-paginated, records, Arrays, JSON data... and just whatever you can count _(see [how...](https://ddnexus.github.io/pagy/how-to#paginate-any-collection))_
+- It works with all Rack frameworks (Rails, Sinatra, Padrino, ecc.) out of the box _(see [more...](https://ddnexus.github.io/pagy/how-to.md#environment-assumptions))_
+- It works with any possible non-Rack environment by just overriding one or two two-lines methods _(see [more...](https://ddnexus.github.io/pagy/how-to.md#environment-assumptions))_
 
 ### Unlike the other gems
 
-- It works with collections/scopes that already used `limit` and `offset` _(see [how](https://ddnexus.github.io/pagy/how-to#paginate-a-pre-offsetted-and-pre-limited-collection))_
-- It works with helpers or templates (your choice)
-- It raises real `Pagy::OutOfRangeError` exceptions that you can rescue from
-- It does not impose any difficult-to-override logic or output
+- It works with collections/scopes that already used `limit` and `offset` _(see [how...](https://ddnexus.github.io/pagy/how-to#paginate-a-pre-offsetted-and-pre-limited-collection))_
+- It works with helpers or templates _(see [more...](https://ddnexus.github.io/pagy/how-to#using-templates))_
+- It raises real `Pagy::OutOfRangeError` exceptions that you can rescue from _(see [how...](https://ddnexus.github.io/pagy/how-to#handling-pagyoutofrangeerror-exception))_
+- It does not impose any difficult-to-override logic or output _(see [why...](https://ddnexus.github.io/pagy/index#really-easy-to-customize))_
 
 ### Easy to use
 
@@ -72,37 +72,37 @@ Or - if you prefer - render the navigation links with a template:
 <%== render 'pagy/nav', locals: {pagy: @pagy} %>
 ```
 
+_(see [Quick Start](https://ddnexus.github.io/pagy/how-to#quick-start))_
+
 ## Easy to extend
 
 Use the official extras, or write your own in just a few lines.
 
 ### Bootstrap Extra
 
-Nav helper and templates for Bootstrap pagination. ([More info...](http://ddnexus.github.io/pagy/extras/bootstrap))
+Nav helper and templates for Bootstrap pagination. _(see [more...](http://ddnexus.github.io/pagy/extras/bootstrap))_
 
 ### Responsive Extra
 
-On resize, the number of page links will adapt in real-time to the available window or container width.
+On resize, the number of page links will adapt in real-time to the available window or container width. _(see [more...](http://ddnexus.github.io/pagy/extras/responsive))_
 
 ![pagy-responsive](docs/assets/images/pagy-responsive-w.png)
 
-([More info...](http://ddnexus.github.io/pagy/extras/responsive))
-
 ### Compact Extra
 
-An alternative UI that combines the pagination feature with the navigation info in one compact element.
+An alternative UI that combines the pagination feature with the navigation info in one compact element. _(see [more...](http://ddnexus.github.io/pagy/extras/compact))_
+
 
 ![pagy-compact](docs/assets/images/pagy-compact-w.png)
 
-([More info...](http://ddnexus.github.io/pagy/extras/compact))
 
 ### Array Extra
 
-Paginate arrays efficiently avoiding expensive array-wrapping and without any overriding. ([More info...](http://ddnexus.github.io/pagy/extras/array))
+Paginate arrays efficiently avoiding expensive array-wrapping and without any overriding. _(see [more...](http://ddnexus.github.io/pagy/extras/array))_
 
 ## Chat Support and Feedback
 
-[Chat on Gitter](https://gitter.im/ruby-pagy/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[Chat on Gitter](https://gitter.im/ruby-pagy/Lobby)
 
 ## Useful Links
 

docs/api/backend.md

@@ -9,7 +9,7 @@ For overriding convenience, the `pagy` method calls two sub-methods that you may
 
 However, keep in mind that the whole module is basically providing a single functionality: getting a pagy instance and the paginated items. You could re-write the whole module as one single and simple method specific to your need. (see [Writing your own pagy methods](#writing-your-own-pagy-methods))
 
-__Notice__: This module is also extended with a few _specific_ extra methods that paginate array collections, if you use the [array extra](../extras/array.md).
+**Notice**: This module is also extended with a few _specific_ extra methods that paginate array collections, if you use the [array extra](../extras/array.md).
 
 ## Synopsys
 
@@ -87,7 +87,7 @@ def pagy_get_items(array, pagy)
 end
 ```
 
-__Notice__: in order to paginate arrays, you may want to use the  [array extra](../extras/array.md).
+**Notice**: in order to paginate arrays, you may want to use the  [array extra](../extras/array.md).
 
 ## Writing your own pagy methods
 

docs/api/pagy.md

@@ -59,7 +59,7 @@ The `Pagy.new` method accepts a single hash of variables that will be merged wit
 
 All the variables not explicitly in the list of core-variables (the non-core variables) passed/merged to the new method will be kept in the object, passed around with it and accessible through the `pagy.vars` hash.
 
-__Notice__: Pagy replaces the blank values of the passed variables with their default values. It also applies `to_i` on the values expected to be integers, so you can use values from request `params` without problems. For example: `pagy(some_scope, items: params[:items])` will work without any additional cleanup.
+**Notice**: Pagy replaces the blank values of the passed variables with their default values. It also applies `to_i` on the values expected to be integers, so you can use values from request `params` without problems. For example: `pagy(some_scope, items: params[:items])` will work without any additional cleanup.
 
 ### Core Variables
 

docs/extras/array.md

@@ -30,12 +30,12 @@ This extra is composed of 1 file:
 
 This extra adds the `pagy_array` method to the `Pagy::Backend` to be used in place (or in parallel) of the `pagy` method when you have to paginate an array. It also adds a `pagy_array_get_variables` sub-method, used for easy customization of variables by overriding.
 
-__Notice__: there is no `pagy_array_get_items` method to override, since the items are fetched directly by the specialized `pagy_array` method.
+**Notice**: there is no `pagy_array_get_items` method to override, since the items are fetched directly by the specialized `pagy_array` method.
 
 ### pagy_array(array, vars=nil)
 
 This method is the same as the generic `pagy` method, but specialized for an Array. (see the [pagy doc](../api/backend.md#pagycollection-varsnil))
 
 ### pagy_array_get_vars(array)
 
-This sub-method is the same as the `pagy_get_vars` sub-method, but it is called only by the `pagy_array` nethod. (see the [pagy_get_vars doc](../api/backend.md#pagy_get_varscollection))
+This sub-method is the same as the `pagy_get_vars` sub-method, but it is called only by the `pagy_array` method. (see the [pagy_get_vars doc](../api/backend.md#pagy_get_varscollection-vars)).

docs/extras/responsive.md

@@ -61,7 +61,7 @@ The above statement means that from `0` to `450` pixels width, pagy will use the
 
 **IMPORTANT**: You can set any number of breakpoints with any arbitrary width and size. The only requirement is that the `:breakpoints` hash must contain always the `0` size. An `ArgumentError` exception will be raises if it is missing.
 
-__Notice__: Each breakpoint added slowers down pagy of almost 10%. For example: with 5 breakpoints (which are actually quite a lot) the nav will be rendered rougly in twice the normal time. However, that will still run about 15 times faster than Kaminari and 6 times faster than WillPaginate.
+**Notice**: Each breakpoint added slowers down pagy of almost 10%. For example: with 5 breakpoints (which are actually quite a lot) the nav will be rendered rougly in twice the normal time. However, that will still run about 15 times faster than Kaminari and 6 times faster than WillPaginate.
 
 ## Methods
 

docs/how-to.md

@@ -79,7 +79,7 @@ Pagy can work in any other scenario assuming that:
 - You may need to override the `pagy_get_items` method in your controller (to get the items out of your specific collection)
 - You may need to override the `pagy_url_for` (which uses `Rack` and `request`) in your view
 
-__Notice__: the total overriding you may need is usually just a handful of lines at worse, and it doesn't need monkey patching or writing any sub-class or module.
+**Notice**: the total overriding you may need is usually just a handful of lines at worse, and it doesn't need monkey patching or writing any sub-class or module.
 
 ## Items per page
 
@@ -252,7 +252,7 @@ You can also use the `:param` and : `:anchor` non core variables to add arbitrar
 @pagy, @records = pagy(some_scope, params: {custom: 'param'}, anchor: '#your-anchor')
 ```
 
-__IMPORTANT__: For performance reasons the `:anchor` string must include the `#`.
+**IMPORTANT**: For performance reasons the `:anchor` string must include the `#`.
 
 ## Customizing the URL
 
@@ -374,7 +374,7 @@ You can do so by setting the `:item_path` variable to the path to lookup in the
     @pagy, @record = pagy(my_scope, item_path: 'activerecord.models.product' )
     ```
 
-__Notice__: The variables passed to a pagy object have the precedence over the variables returned by the `pagy_get_vars`. The fastest way is passing a literal string to the `pagy` method, the most convenient way is using `pagy_get_vars`.
+**Notice**: The variables passed to a pagy object have the precedence over the variables returned by the `pagy_get_vars`. The fastest way is passing a literal string to the `pagy` method, the most convenient way is using `pagy_get_vars`.
 
 ## Handling Pagy::OutOfRangeError exception
 

docs/index.md

@@ -41,6 +41,6 @@ You could even use it directly (without using any other pagy code) in a small pa
 
 ## Really easy to customize
 
-If options and configuration are not enough, you have a few specialized [extras](extras.md). And if all that is still not enough, any other special customization is at most one step far from your own code. All its helpers are contained in 2 plain modules with no nesting. You include them in your code, so you can override any method right where you use it: no tricky gymnic required.
+If options and configuration are not enough, you have a few specialized [extras](extras.md), and if all that is still not enough, any other special customization is at most _one step far_ from your own code. All its helpers are contained in 2 plain modules with no nesting. You include them in your code, so you can override any method right where you use it: no tricky gymnic required.
 
 What could be easier?

docs/migration-tips.md

@@ -22,7 +22,7 @@ In this phase you will search statements from legacy pagination gems, remove the
 - If it makes sense, you should add the equivalent Pagy statement and remove the legacy statement(s).
 - If it doesn't make sense, then just remove the legacy statement.
 
-__Notice:__ Don't worry about missing something in this phase: if anything wont work as before you can fix it later in the process.
+**Notice:** Don't worry about missing something in this phase: if anything wont work as before you can fix it later in the process.
 
 #### Preparation