Make security guides more readable

[scottinet]

⚠️ depends on #274

Description

1. The security guide features examples using Javascript code instead of plain JSON objects, and this was confusing for our readers
2. Make the security guide examples clearer
3. Wrap the very, very long curl example to prevent an impractical horizontal scrollbar from appearing (the example still works after having been copy-pasted, obviously)

How to test

Go to the following pages in the netlify preview:

• Security guide: guide/1/essentials/security (current production version)
• User authentication guide: guide/1/essentials/user-authentication/ (current production version)

Note

There is a handlebar pattern that is not interpreted at the bottom of the security guide (this is already the case in production).
I don't have much time to spend on that, but AFAIK it seems that handlebars helpers returning a safestring prevent automatic field interpolation appearing later on the same line. To be investigated.

Fixed two of those actually. The problem is that, for still unknown reasons, using a handlebars safestring disables further markdown interpretation. So, until we understand what's going on, I used HTML instead of markdown.

[kuzzle]

Snippets tests reports

SDK	Version	Tests overview
	v6	✔️
	v5	✔️
	v1	✔️
	v1	✔️
	v1	✔️
	v1	✔️

[ballinette]

My comment is about the unchanged text below:

The `action permission` value can be set to either:
- a boolean. If `true`, the `role` allows the given action.
- an object describing a dynamic right definition. For more information check out the [advanced roles documentation]({{ site_base_path }}guide/1/kuzzle-depth/roles-definitions)).

As the closures are deprecated, do we really want to reference it here ?
Or at least add a deprecated tag to the line an object describing a dynamic right definition.

[scottinet]

I added a deprecated tag, because a documentation must be exhaustive, even if it means giving out of date details.

[ballinette]

nitpicking: I would put the example without restriction at the first place (to read the policies from the simplest form to the most complex one)

[scottinet]

Agreed. I also applied this remark to the restrictedTo example.

[ballinette]

About the last (unchanged) sentence There are multiple ways of adding a business logic layer on top of the standard Kuzzle security one:, I would reorder the items, and put:

1. write a pipe plugin
2. use document validators
3. use closures (deprecated)

[scottinet]

Makes more sense that way 👍