Docs additions

CHANGELOG.md

@@ -74,7 +74,8 @@ You should not have used any of the private methods, but if you did so, you will
 ### Changes
 
 - [ARIA compliance](https://ddnexus.github.io/pagy/docs/api/aria/)
-- Removed the pagy templates: they were a burden for maintenance with very limited usage.
+- Removed the pagy templates: they were a burden for maintenance with very limited usage,
+  still [you can use them](http://ddnexus.github.io/pagy/docs/how-to/#using-your-pagination-templates)
 - Internal renaming of private frontend methods
 
 [LEGACY CHANGELOG >>>](CHANGELOG_LEGACY.md) 

README.md

@@ -15,13 +15,13 @@
 
 ---
 
-### What's new in 7.0
+### ✴ What's new in 7.0 ✴
 
 - [JSON:API support](https://ddnexus.github.io/pagy/docs/extras/jsonapi/)
 - [ARIA compliance](https://ddnexus.github.io/pagy/docs/api/aria/)
 - Added a simpler and faster nav without gaps supporting single integer as the `:size`
 - Pagy follows the [ruby end-of-life](https://endoflife.date/ruby) supported rubies now.
-- See the [Changelog](https://ddnexus.github.io/pagy/changelog)
+- See the [Changelog](https://ddnexus.github.io/pagy/changelog) for breaking changes
 
 ---
 

docs/assets/nav.html.erb

@@ -0,0 +1,41 @@
+<%#
+  The link variable is set to a proc that returns the link tag (complete with rel and aria-current)
+  Usage: link.call( page_number [, text [, extra_attributes_string ]])
+-%>
+<% link = pagy_link_proc(pagy) -%>
+<nav class="pagy_nav pagination" aria-label="Pages">
+  <%# Previous page link %>
+  <% if pagy.prev -%>
+    <span class="page prev">
+      <%== link.call(pagy.prev, '&lt;', 'aria-label="Previous"') %>
+    </span>
+  <% else -%>
+    <span class="page prev disabled">
+      <a role="link" aria-disabled="true" aria-label="Previous">&lt;</a>
+    </span>
+  <% end -%>
+  <%# Page links (series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]) %>
+  <% pagy.series.each do |item| -%>
+    <% if item.is_a?(Integer) -%>
+      <span class="page">
+        <%== link.call(item) %>
+      </span>
+    <% elsif item.is_a?(String) -%>
+      <span class="page active">
+        <a role="link" aria-disabled="true" aria-current="page"><%== item %></a>
+      </span>
+    <% elsif item == :gap -%>
+      <span class="page gap">&hellip;</span>
+    <% end -%>
+  <% end -%>
+  <%# Next page link %>
+  <% if pagy.next -%>
+    <span class="page next">
+      <%== link.call(pagy.next, '&gt;', 'aria-label="Next"') %>
+    </span>
+  <% else -%>
+    <span class="page next disabled">
+      <a role="link" aria-disabled="true" aria-label="Next">&gt;</a>
+    </span>
+  <% end -%>
+</nav>

docs/how-to.md

@@ -1013,3 +1013,22 @@ If you need to test pagination, remember:
 ```rb
 @pagy, @books = pagy(Book.all, items: 10) # the items default has been overridden
 ```
+
+## Using your pagination templates
+
+!!!warning Warning!
+The pagy nav helpers are not only a lot faster than templates, but accept dynamic arguments and comply with ARIA and I18n standards. Using your own templates is possible, but it's kind of reinventing a slower wheel.
+!!!
+
+Pagy can be used with your own templates. Here is a very simple static example that doesn't use any other helper nor dictionary
+file:
+
+:::code source="assets/nav.html.erb" :::
+
+You can use it as usual: just remember to pass the `:pagy` local set to the `@pagy` object:
+
+```erb
+<%== render file: 'nav.html.erb', locals: {pagy: @pagy} %>
+```
+
+You may want to read also the [Pagy::Frontend API documentation](api/frontend.md) for complete control over your templates.