docs: rearrange example into sections

examples/README.md

@@ -1,15 +1,16 @@
 # Usage
 
 Overview:
-- [quick config example](#quick-config) shows how you can use the plugin config to setup a quick and easy tagging system.
+- [config example](#config-file) shows how you can use the plugin config to setup a quick and easy tagging system.
 - [simple example](#simple-example) goes into detail how to use it in your own plugin.
-- [advanced example](#advanced-example) touches on the potentials of the plugin.
+- [advanced example](#advanced-example) touches on the potentials of plugin development.
 - [Misc](#misc) shows other use-cases.
 
 After reading this tutorial, have a look at other plugins that use `lektor-groupby`:
 - [lektor-inlinetags](https://github.com/relikd/lektor-inlinetags-plugin)
 
 
+
 ## About
 
 To use the groupby plugin you have to add an attribute to your model file.
@@ -35,15 +36,9 @@ The attribute name is later used for grouping.
 
 
 
-## Quick config
+## Config File
 
-Relevant files:
+The easiest way to add tags to your site is by defining the [`configs/groupby.ini`](./configs/groupby.ini) file.
-
-- [`configs/groupby.ini`](./configs/groupby.ini)
-- [`templates/example-config.html`](./templates/example-config.html)
-
-
-The easiest way to add tags to your site is by defining the `groupby.ini` config file.
 
 ```ini
 [testA]
@@ -67,9 +62,12 @@ url_suffix = .page.
 title = "Tagged: " ~ this.key_obj
 
 [testA.key_map]
-Blog = News
+C# = c-sharp
 ```
 
+
+### Config: Main Section
+
 The configuration parameter are:
 
 1. The section title (`testA`) must be one of the attribute variables we defined in our model.
@@ -91,7 +89,7 @@ The configuration parameter are:
    These single-line fields are then expanded to lists as well.
    If you do not provide the `split` option, the whole field value will be used as tagname.
 6. The `enabled` parameter allows you to quickly disable the grouping.
-7. The `key_obj_fn` parameter (jinja2) accepts any function-like snippet or function call.
+7. The `key_obj_fn` parameter (jinja) accepts any function-like snippet or function call.
    The context provides two variables, `X` and `ARGS`.
    The former is the raw value of the grouping, this may be a text field, markdown, or whatever custom type you have provided.
    The latter is a named tuple with `record`, `key`, and `field` values (see [simple example](#simple-example)).
@@ -101,13 +99,22 @@ The configuration parameter are:
 You can have multiple listeners, e.g., one for `/blog/` and another for `/projects/`.
 Just create as many custom attributes as you like, each having its own section (and subsections).
 
+
+### Config Subsection: .children
+
 The `.children` subsection currently has a single config field: `order_by`.
 The usual [order-by](https://www.getlektor.com/docs/guides/page-order/) rules apply (comma separated list of keys with `-` for reversed order).
 The order-by key can be anything of the page attributes of the children.
 
-The `.pagination` subsection accepts the same configuration options as the Lektor pagination [model](https://www.getlektor.com/docs/models/children/#pagination) and [guide](https://www.getlektor.com/docs/guides/pagination/).
+
+### Config Subsection: .pagination
+
+The `.pagination` subsection accepts the same configuration options as the default Lektor pagination ([model](https://www.getlektor.com/docs/models/children/#pagination), [guide](https://www.getlektor.com/docs/guides/pagination/)).
 Plus, an additional `url_suffix` parameter if you would like to customize the URL scheme.
 
+
+### Config Subsection: .fields
+
 The `.fields` subsection is a list of key-value pairs which will be added as attributes to your grouping.
 You can access them in your template (e.g., `{{this.title}}`).
 All of the `.fields` values are evaluted in a jinja context, so be cautious when using plain strings.
@@ -122,11 +129,6 @@ The built-in field attributes are:
 - `children`: the elements of the grouping (a `Query` of `Record` type)
 - `config`: configuration object (see below)
 
-Without any changes, the `key` value will just be `slugify(key_obj)`.
-However, the `.key_map` subsection will replace `key_obj` with whatever replacement value is provided in the `.key_map` and then slugify.
-You could, for example, add a `C# = c-sharp` mapping, which would otherwise just be slugified to `c`.
-This is equivalent to `slugify(key_map.get(key_obj))`.
-
 The `config` attribute contains the values that created the group:
 
 - `key`: attribute key, e.g., `TestA`
@@ -142,9 +144,21 @@ The `config` attribute contains the values that created the group:
 - `pagination`: raw values from `TestA.pagination`
 - `order_by`: list of key-strings from `TestA.children.order_by`
 
-In your template file you have access to the config, attributes, fields, and children (Pages):
 
-```jinja2
+### Config Subsection: .key_map
+
+Without any changes, the `key` value will just be `slugify(key_obj)`.
+However, the `.key_map` subsection will replace `key_obj` with whatever replacement value is provided in the mapping and is then slugified.
+Take the given example, `C# = c-sharp`, which would otherwise be slugified to `c`.
+This is equivalent to `slugify(key_map.get(key_obj))`.
+
+
+### Config Template
+
+In your template file ([`templates/example-config.html`](./templates/example-config.html)), you have access to the aforementioned attributes:
+
+
+```jinja
 <h2>{{ this.title }}</h2>
 <p>Key: {{ this.key }}, Attribute: {{ this.config.key }}</p>
 <ul>
@@ -215,7 +229,7 @@ field = args.record[k.fieldKey].blocks[k.flowIndex].get(k.flowKey)
 
 Again, you can use all properties in your template.
 
-```jinja2
+```jinja
 <p>Custom field date: {{this.date}}</p>
 <ul>
 {%- for child in this.children %}
@@ -300,8 +314,8 @@ template = example-advanced.html
 match = {{([^}]{1,32})}}
 ```
 
-The config file takes the same parameters as the [config example](#quick-config).
+The config file takes the same parameters as the [config example](#config-file).
-We introduced a new config option `testC.pattern.match`.
+We introduce a new config option `testC.pattern.match`.
 This regular expression matches `{{` + any string less than 32 characters + `}}`.
 Notice, the parenthesis (`()`) will match only the inner part, thus the replace function (`re.sub`) removes the `{{}}`.
 
@@ -318,7 +332,7 @@ You can combine this with the next use-case.
 
 ### Index pages & Group query + filter
 
-```jinja2
+```jinja
 {%- for x in this|vgroups(keys=['TestA', 'TestB'], fields=[], flows=[], recursive=True, order_by='key_obj') %} 
 <a href="{{ x|url }}">({{ x.key_obj }})</a>
 {%- endfor %}