diff --git a/doc/pages/commands.asciidoc b/doc/pages/commands.asciidoc
index d97e9554e..664f977ec 100644
--- a/doc/pages/commands.asciidoc
+++ b/doc/pages/commands.asciidoc
@@ -1,12 +1,6 @@
-kakoune(k)
-==========
+= Commands
 
-NAME
-----
-commands - a
-
-Builtins
---------
+== Builtins
 
 Some commands take an exclamation mark (*!*), which can be used to force
 the execution of the command (i.e. to quit a modified buffer, the
@@ -169,8 +163,8 @@ command *q!* has to be used). Aliases are mentionned below each commands.
 	remove the highlighter whose id is *highlighter_id* (c.f. the
 	'highlighters' documentation page)
 
-Helpers
--------
+== Helpers
+
 Kakoune provides some helper commands that can be used to define composite
 commands:
 
@@ -230,14 +224,14 @@ commands:
 Note that those commands are also available in the interactive mode, but
 are not really useful in that context.
 
-Multiple commands
------------------
+== Multiple commands
+
 Commands (c.f. previous sections) can be chained, by being separated either
 by new lines or by semicolons, as such a semicolon must be escaped with a
 backslash (\;) to be considered as a literal semicolon argument
 
-Declaring new commands
-----------------------
+== Declaring new commands
+
 New commands can be defined using the *define-command* command:
 
 *define-command* [flags] <command_name> <commands>::
diff --git a/doc/pages/execeval.asciidoc b/doc/pages/execeval.asciidoc
index 91b049d69..309cdbb42 100644
--- a/doc/pages/execeval.asciidoc
+++ b/doc/pages/execeval.asciidoc
@@ -1,12 +1,7 @@
-kakoune(k)
-==========
+= Exec and Eval
 
-NAME
-----
-execeval - a
+== Description
 
-Description
------------
 The *exec* and *eval* commands can be used to run Kakoune commands, and
 should be used as follows:
 
@@ -23,8 +18,8 @@ the last key/command is reached, or an error is raised.
 These two commands also save the following registers, who are then restored
 when the commands have been executed: */*, *"*, *|*, *^*, *@*.
 
-Optional flags
---------------
+== Optional flags
+
 *-client* <name>::
 	execute in the context of the client named *name*
 
diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc
index 895b8af13..516dc1108 100644
--- a/doc/pages/expansions.asciidoc
+++ b/doc/pages/expansions.asciidoc
@@ -1,12 +1,7 @@
-kakoune(k)
-==========
+= Expansions
 
-NAME
-----
-expansions - a
+== Strings
 
-Strings
--------
 \'strings'::
 	uninterpreted strings, use a backslash (\') to escape the separator
 "strings"::
@@ -29,8 +24,7 @@ e.g. %[string], %<string>, %(string), %~string~, %!string!
 e.g. %{ roger {}; } is a valid string, %{ marcel \} as well
 -----------------------------------------------------------
 
-Typed expansions
-----------------
+== Typed expansions
 
 %\{strings\} can have an expansion type between the *%* and the opening
 character. They will be written *%<type>\{<content>\}*. They will be
@@ -54,8 +48,8 @@ parameter:
 	argument expansion, expand to the arguments of the current
 	command, *<content>* can be a number, or @ for all arguments
 
-Shell expansions
-----------------
+== Shell expansions
+
 The '%sh{...}' expansion replaces its content with the output of the
 shell commands in it. The following environment variables are used to pass
 informations about Kakoune's state:
@@ -131,8 +125,8 @@ informations about Kakoune's state:
 Note that in order for Kakoune to pass a value in the environment, the
 variable has to be spelled out within the body of the expansion
 
-Markup strings
---------------
+== Markup strings
+
 In certain contexts, Kakoune can take a markup string, which is a string
 containing formatting informations. In these strings, the {facename}
 syntax will enable the face facename until another face gets activated,
diff --git a/doc/pages/faces.asciidoc b/doc/pages/faces.asciidoc
index 6e6ba3d82..c69fa9c72 100644
--- a/doc/pages/faces.asciidoc
+++ b/doc/pages/faces.asciidoc
@@ -1,12 +1,7 @@
-kakoune(k)
-==========
+= Faces
 
-NAME
-----
-faces - a
+== Declaration
 
-Declaration
------------
 A 'face' refers how the specified text is displayed, it has a foreground
 color, a background color, and some attributes. The value of a face has the
 following format:
@@ -42,8 +37,8 @@ fg_color[,bg_color][+attributes]
 			exclusive, override previous faces instead of merging
 			with them
 
-Builtin faces
--------------
+== Builtin faces
+
 The following default faces are used by color schemes to highlight certain
 areas of the user interface:
 
diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc
index 3a723da40..02d6ca60f 100644
--- a/doc/pages/faq.asciidoc
+++ b/doc/pages/faq.asciidoc
@@ -1,19 +1,12 @@
-kakoune(k)
-==========
+= FAQ
 
-NAME
-----
-faq - a
-
-How to pronounce the name of the project and what does it mean ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== How to pronounce the name of the project and what does it mean ?
 
 The name of the project is pronounced "Kak-oon", and is a word taken from a
 New Caledonian dialect based on french. It means a hard blow, usually a punch,
 but generally refers to a blow into which all of one's strength went.
 
-Is there going to be a Windows port of Kakoune ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Is there going to be a Windows port of Kakoune ?
 
 As many features provided by UNIX systems would be missing, or if anything
 much less efficient on a Windows system, the incentive to porting the
@@ -22,8 +15,7 @@ project to this operating system is pretty low.
 Moreover, you can get pretty decent performance by using Kakoune on Cygwin
 (which is officially supported).
 
-Kakoune is very slow on big files, what can I do about it ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Kakoune is very slow on big files, what can I do about it ?
 
 The default build mode (set in the `Makefile` of the `src` directory of the
 project) is "debug", which makes it convenient to track issues but also
@@ -34,21 +26,18 @@ Note that if your distribution provides a "kakoune" package, the program should
 already be built in non-debug mode (if you still experience slowness, please
 report the issue on the bug tracker).
 
-Can I use Kakoune as a pager ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Can I use Kakoune as a pager ?
 
 Kakoune can be used as a pager, either by setting the `PAGER` environment
 variable to `kak`, or by writing data directly to its standard input using a
 shell pipeline.
 
-Are there any non-console based frontends available ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Are there any non-console based frontends available ?
 
 No graphical frontend is currently officially maintained, you can however
 try experimental community-developed ones.
 
-Why are colors misrendered in my Kakoune clients ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Why are colors misrendered in my Kakoune clients ?
 
 The most probable cause for that is a very widespread practice that consists
 in setting the `TERM` environment variable in the shell's configuration file.
@@ -60,16 +49,14 @@ Note that if you're using `tmux`, the proper -official- way to get Kakoune to
 work is to add the following line to your `tmux` configuration file:
 `set -sg default-terminal screen-256color`
 
-Why does leaving insert mode take more than half a second in `tmux` ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Why does leaving insert mode take more than half a second in `tmux` ?
 
 Upon hitting the escape key, `tmux` waits for a short period of time to
 determine whether it's part of a function or a meta key sequence. In order
 to fix this "lag", set the waiting period in your `tmux` configuration file
 to a short time, e.g. 25ms: `set -sg escape-time 25`
 
-How do I automatically indent code, as Vim does with `=` ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== How do I automatically indent code, as Vim does with `=` ?
 
 As `Kakoune` doesn't parse the contents of the buffers, there is no builtin
 equivalent for this Vim feature. Use a formatter/prettifier dedicated to
@@ -80,8 +67,7 @@ Example: `%|indent<ret>` to indent an entire buffer with C code.
 Note that some languages have a default formatter set, which you can use
 with the `:format` command.
 
-Can Kakoune automatically complete the parameters of my functions ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Can Kakoune automatically complete the parameters of my functions ?
 
 As mentioned in the above question about Vim's `=` key, Kakoune does not
 parse the contents of a buffer by itself, which makes it impossible for
@@ -95,8 +81,7 @@ editing a C/C++ file, and completion will work on function parameters.
 Note that the same features are available for python buffers, with the
 `jedi` script.
 
-Why aren't widely known command line shortcuts such as <c-w> or <c-u> available in Kakoune ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Why aren't widely known command line shortcuts such as <c-w> or <c-u> available in Kakoune ?
 
 Despite their widespread availability in multiple tools, those shortcuts do
 not fit the paradigm that Kakoune implements, which is based on selections
@@ -106,8 +91,7 @@ However, you can easily declare key mappings in your configuration file
 to be able to use those control-based shortcuts in insert mode (c.f. the
 "map" command in the "commands" documentation page).
 
-How can I explore the filesystem the way Vim's NerdTree does ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== How can I explore the filesystem the way Vim's NerdTree does ?
 
 The builtin file completion engine used when opening a file for editing
 (using the `:edit` command and letting the suggestions popup in the menu
@@ -119,8 +103,7 @@ which should in return send an "edit" command followed by the path of the
 file you selected to the current Kakoune session (e.g. `echo "eval -client
 $kak_client edit /path/to/file" | kak -p $kak_session`).
 
-Why aren't there other scopes similar to `%sh{}` e.g. python ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Why aren't there other scopes similar to `%sh{}` e.g. python ?
 
 Supporting custom scopes would add hard dependencies to the project, which
 is too much of a drawback when balanced against the low cost of using
@@ -129,8 +112,7 @@ The shell scope allows users to spawn any interpreter they want, for a minimal
 cost in terms of performance, it is therefore the reason why it's the only
 one available by default.
 
-What shell is used to expand `%sh{}` scopes ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== What shell is used to expand `%sh{}` scopes ?
 
 The server expands shell scopes using the `sh` binary, stored in one of the
 directories where all the POSIX standard utilities can be found -this list
@@ -139,22 +121,19 @@ by Kakoune at startup.
 
 In most distributions, `/bin/sh` will end up being used.
 
-Can I disable auto-indentation completely ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Can I disable auto-indentation completely ?
 
 All the indentation hooks are conventionally named `<lang>-indent`, which
 allows us to use the `disabled_hooks` variable to disable indentation
 globally with the following command: `set global disabled_hooks '.+-indent'`
 
-How to enable syntax highlighting ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== How to enable syntax highlighting ?
 
 The mimetype of the files opened in new buffers is detected using the
 `file` command, and syntax highlighting enabled automatically when
 possible.
 
-My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically ?
 
 The `file` utility has several short comings, such as detecting the
 wrong mimetype for a file containing data with different syntax, e.g.
@@ -166,16 +145,14 @@ for a given format for instance), but not much can be done about those
 ambiguous cases. You might consider writing a custom `$HOME/.magic` file
 if needed.
 
-Can I disable syntax highlighting completely ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Can I disable syntax highlighting completely ?
 
 Similarly to the indentation hooks, the name format followed by the
 highlighting hooks is `<lang>-highlight`. You can thus disable syntax
 highlighting using the following command: `set global disabled_hooks
 '.+-highlight'`
 
-Why does a dot `.` in a regex select newline characters ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Why does a dot `.` in a regex select newline characters ?
 
 Data in buffers is a stream of characters, and newlines do not receive special
 treatment compared to other characters, with regards to regex matching. In
@@ -183,8 +160,7 @@ order to select data in a line without any trailing newline characters, one coul
 use the `[^\n]+` pattern, which is arguably a good compromise when
 balanced against the ability to select data over several lines.
 
-Can I split the window to display different buffers in them ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Can I split the window to display different buffers in them ?
 
 As a fairly compliant follower of the UNIX philosophy, Kakoune does not
 try to implement features that are best handled by separate, dedicated
@@ -198,8 +174,7 @@ In order to open buffers in the same window simultaneously using `tmux`
 and simply use the `:new` command to spawn new clients as you would
 have otherwise in an X11 environment.
 
-Why does `a` extend the current selection, but `i` leaves it untouched ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Why does `a` extend the current selection, but `i` leaves it untouched ?
 
 Selections are ranges of characters whose delimiters are an "anchor" and
 a "cursor", and inserting characters is always done before the cursor in
diff --git a/doc/pages/highlighters.asciidoc b/doc/pages/highlighters.asciidoc
index 9931355ea..3e103696f 100644
--- a/doc/pages/highlighters.asciidoc
+++ b/doc/pages/highlighters.asciidoc
@@ -1,12 +1,6 @@
-kakoune(k)
-==========
+= Highlighters
 
-NAME
-----
-highlighters - a
-
-Description
------------
+== Description
 
 Manipulation of the displayed text is done through highlighters, which can
 be added or removed with the following commands:
@@ -30,8 +24,8 @@ separated path starting with a scope. Scopes are *global*, *buffer*,
 completion in a prompt on the *remove-highlighter* command to see the existing highlighters
 ids.
 
-General highlighters
---------------------
+== General highlighters
+
 *regex* <ex> <capture_id>:<face> ...::
 	highlight a regex, takes the regex as first parameter, followed by
 	any number of face parameters. For example:
@@ -119,8 +113,8 @@ add-highlighter window regex //\h*(TODO:)[^\n]* 0:cyan 1:yellow,red
 *line* <number> <face>::
 	highlight line *number* with face *face*
 
-Highlighting Groups
--------------------
+== Highlighting Groups
+
 
 The *group* highlighter is a container for other highlighters. You can add a
 a subgroup to an existing group, or scope using:
@@ -143,8 +137,7 @@ or several (separated with a pipe sign) of *colorize*, *move* or *wrap* (default
 add-highlighter window group -passes colorize|move|wrap <name>
 --------------------------------------------------------------
 
-Regions highlighters
---------------------
+== Regions highlighters
 
 A special highlighter provides a way to segment the buffer into regions,
 which are to be highlighted differently.
@@ -221,8 +214,7 @@ add-highlighter <path>/<lang>/string ...
 add-highlighter <path>/<lang>/comment ...
 -----------------------------------------------------------------
 
-Shared Highlighters
--------------------
+== Shared Highlighters
 
 Highlighters are often defined for a specific filetype, and it makes then
 sense to share the highlighters between all the windows on the same filetypes.
diff --git a/doc/pages/hooks.asciidoc b/doc/pages/hooks.asciidoc
index a971e47b5..b542dd810 100644
--- a/doc/pages/hooks.asciidoc
+++ b/doc/pages/hooks.asciidoc
@@ -1,12 +1,6 @@
-kakoune(k)
-==========
+= Hooks
 
-NAME
-----
-hooks - a
-
-Description
------------
+== Description
 
 Commands can be registered to be executed when certain events arise. To
 register a hook use the following command:
@@ -38,8 +32,8 @@ remove-hooks <scope> <group>
 A call to the command above will remove every hooks in *scope* that are part
 of the given *group*.
 
-Default hooks
--------------
+== Default hooks
+
 *NormalIdle*::
 	a certain duration has passed since last key was pressed in normal mode
 
@@ -172,8 +166,7 @@ the following expansions:
 * `kak_hook_param`: filtering text passed to the currently executing hook
 * `kak_hook_param_capture_N`: text captured by the hook filter regex capture N
 
-Disabling Hooks
----------------
+== Disabling Hooks
 
 Any normal mode command can be prefixed with `\` which will disable hook
 execution for the duration for the command (including the duration of modes
diff --git a/doc/pages/keys.asciidoc b/doc/pages/keys.asciidoc
index 160afa7a3..f1777cebb 100644
--- a/doc/pages/keys.asciidoc
+++ b/doc/pages/keys.asciidoc
@@ -1,12 +1,7 @@
-kakoune(k)
-==========
+= Keys
 
-NAME
-----
-keys - a
+== Key Syntax
 
-Key Syntax
-----------
 Usual keys are written using their ascii character, including capital
 keys. Non printable keys use an alternate name, written between *<*
 and *>*, such as *<esc>* or *<del>*. Modified keys are written between
@@ -17,8 +12,8 @@ name or ascii character), for example *<c-x>*, *<a-space>*.
 In order to bind some keys to arbitrary ones, refer to the 'mapping'
 documentation page.
 
-Insert mode
------------
+== Insert mode
+
 *<esc>*::
 	leave insert mode
 
@@ -73,8 +68,7 @@ Insert mode
 *<a-;>*::
 	escape to normal mode for a single command
 
-Using Counts
-------------
+== Using Counts
 
 In normal mode, commands can be prefixed with a numeric count, which can control
 the command behaviour.
@@ -82,8 +76,7 @@ the command behaviour.
 For example, *3W* selects 3 consecutive words and *3w* select the third word on
 the right of selection end.
 
-Disabling Hooks
----------------
+== Disabling Hooks
 
 Any normal mode command can be prefixed with *\* which will disable hook execution
 for the duration for the command (including the duration of modes the command could
@@ -92,8 +85,8 @@ move to, so *\i* will disable hooks for the whole insert session).
 As autoindentation is implemented in terms of hooks, this can be used to disable
 it when pasting text.
 
-Movement
---------
+== Movement
+
 'word' is a sequence of alphanumeric characters or underscore, and 'WORD'
 is a sequence of non whitespace characters
 
@@ -212,8 +205,7 @@ is a sequence of non whitespace characters
 *<a-.>*::
 	repeat last object or *f*/*t* selection command
 
-Changes
--------
+== Changes
 
 *i*::
 	enter insert mode before current selection
@@ -364,8 +356,7 @@ Changes
 
 	rotate (1, 2, 3) and (3, 4, 6) independently
 
-Goto Commands
--------------
+== Goto Commands
 
 *g*, *G*::
 	When a count is specified, *G* only extends the current selection to the given line,
@@ -408,8 +399,7 @@ Goto Commands
 	*.*:::
 		go to last buffer modification position
 
-View commands
--------------
+== View commands
 
 *v*, *V*::
 	*V* enters lock view mode (which will be left when the <esc> is hit),
@@ -441,8 +431,8 @@ View commands
 		scroll the window count columns right
 
 
-Marks
------
+== Marks
+
 Marks use the *^* register by default.
 
 *Z*::
@@ -477,8 +467,8 @@ Marks use the *^* register by default.
 	*-*:::
 		select the shortest selection
 
-Macros
-------
+== Macros
+
 Macros use the *@* register by default
 
 *<esc>*::
@@ -490,8 +480,8 @@ Macros use the *@* register by default
 *q*::
 	play a recorded macro
 
-Searching
----------
+== Searching
+
 Searches use the */* register by default
 
 ***::
@@ -502,8 +492,8 @@ Searches use the */* register by default
 	set the search pattern to the current selection (verbatim, no smart
 	detection)
 
-Jump list
----------
+== Jump list
+
 
 *<c-i>*::
 	Jump forward
@@ -514,8 +504,7 @@ Jump list
 *<c-s>*::
 	save current selections
 
-Multiple selections
--------------------
+== Multiple selections
 
 *s*::
 	create a selection
@@ -548,8 +537,7 @@ Multiple selections
 	pipe each selection to the given shell command and keep the ones
 	for which the shell returned 0
 
-Object Selection
-----------------
+== Object Selection
 
 *<a-a>*::
 	selects the whole object
@@ -620,8 +608,7 @@ object you want
 *c*::
 	select user defined object, will prompt for open and close text
 
-Prompt Commands
----------------
+== Prompt Commands
 
 *<ret>*::
 	validate prompt
diff --git a/doc/pages/mapping.asciidoc b/doc/pages/mapping.asciidoc
index 18863d394..99b326756 100644
--- a/doc/pages/mapping.asciidoc
+++ b/doc/pages/mapping.asciidoc
@@ -1,12 +1,7 @@
-kakoune(k)
-==========
+= Mapping
 
-NAME
-----
-mapping - a
+== Description
 
-Description
------------
 Creating and removing shortcuts boils down to the following commands,
 respectively:
 
@@ -51,8 +46,7 @@ set to the same sequence of keys passed using the *expected* argument.
 For more information about the values of the *scope* parameter, refer to
 the 'scopes' documentation page.
 
-Mappable keys
--------------
+== Mappable keys
 
 For *key* and *keys* in the *map* command, the following key names can
 be used:
diff --git a/doc/pages/options.asciidoc b/doc/pages/options.asciidoc
index d13dc9f56..b075c189b 100644
--- a/doc/pages/options.asciidoc
+++ b/doc/pages/options.asciidoc
@@ -1,12 +1,6 @@
-kakoune(k)
-==========
+= Options
 
-NAME
-----
-options - a
-
-Options
--------
+== Description
 
 Kakoune can store named and typed values that can be used both to customize
 the core editor behaviour, and to store data used by extension scripts.
@@ -28,8 +22,7 @@ declare-option [-hidden] <type> <name> [<value>]
 If `-hidden` is specified, the option will not be displayed in completion
 suggestions.
 
-Types
------
+== Types
 
 All options have a type, which defines how they are translated to/from text
 and their set of valid values.
@@ -76,8 +69,7 @@ are exclusively available to built-in options.
 	a set of flags, taking a combination of the given values joined by a
 	'|' character
 
-Builtin options
----------------
+== Builtin options
 
 *tabstop* 'int'::
 	*default* 8 +
diff --git a/doc/pages/regex.asciidoc b/doc/pages/regex.asciidoc
index 81c47c966..763b0442a 100644
--- a/doc/pages/regex.asciidoc
+++ b/doc/pages/regex.asciidoc
@@ -1,20 +1,13 @@
-kakoune(k)
-==========
+= Regex
 
-NAME
-----
-regex - a
-
-Regex Syntax
-------------
+== Regex Syntax
 
 Kakoune regex syntax is based on the ECMAScript syntax, as defined by the
 ECMA-262 standard (see <<Compatibility>>).
 
 Kakoune's regex always run on Unicode codepoint sequences, not on bytes.
 
-Literals
---------
+== Literals
 
 Every character except the syntax characters `\^$.*+?[]{}|().` match
 themselves. Syntax characters can be escaped with a backspace so `\$`
@@ -32,8 +25,7 @@ Some literals are available as escape sequences:
 * `\xXX` matches the character whose codepoint is XX (in hexadecimal).
 * `\uXXXX` matches the character whose codepoint is XXXX (in hexadecimal).
 
-Character classes
------------------
+== Character classes
 
 The `[` character introduces a character class, matching one character
 from a set of characters.
@@ -76,13 +68,11 @@ non-digit character.
 Character class escapes can be used outside of a character class, `\d`
 is equivalent to `[\d]`.
 
-Any character
--------------
+== Any character
 
 `.` matches any character, including new lines.
 
-Groups
-------
+== Groups
 
 Regex atoms can be grouped using `(` and `)` or `(?:` and `)`. If `(` is
 used, the group will be a capturing group, which means the positions from
@@ -95,8 +85,7 @@ for the whole sequence that matched.
 `(?:` introduces a non capturing group, which will not record the
 matching positions.
 
-Alternations
-------------
+== Alternations
 
 `|` introduces an alternation, which will either match its left-hand side,
 or its right-hand side (preferring the left-hand side)
@@ -104,8 +93,7 @@ or its right-hand side (preferring the left-hand side)
 For example, `foo|bar` matches either `foo` or `bar`, `foo(bar|baz|qux)`
 matches `foo` followed by either `bar`, `baz` or `qux`.
 
-Quantifier
-----------
+== Quantifier
 
 Literals, Character classes, Any characters and groups can be followed
 by a quantifier, which specifies the number of times they can match.
@@ -123,8 +111,7 @@ match more characters if possible. Suffixing a quantifier with `?` will
 make it non-greedy, meaning it will prefer to match as few characters
 as possible.
 
-Zero width assertions
----------------------
+== Zero width assertions
 
 Assertions do not consume any character, but will prevent the regex
 from matching if they are not fulfilled.
@@ -163,8 +150,7 @@ For example, `(?<!bar)(?=foo).` will match any character which is not
 preceded by `bar` and where `foo` matches from the current position
 (which means the character has to be an `f`).
 
-Modifiers
----------
+== Modifiers
 
 Some modifiers can control the matching behavior of the atoms following
 them:
@@ -172,8 +158,7 @@ them:
 * `(?i)` enables case-insensitive matching
 * `(?I)` disables case-insensitive matching
 
-Quoting
--------
+== Quoting
 
 `\Q` will start a quoted sequence, where every character is treated as
 a literal. That quoted sequence will continue until either the end of
@@ -182,8 +167,7 @@ the regex, or the appearance of `\E`.
 For example `.\Q.^$\E$` will match any character followed by the literal
 string `.^$` followed by an end of line.
 
-Compatibility
--------------
+== Compatibility
 
 The syntax tries to follow the ECMAScript regex syntax as defined by
 https://www.ecma-international.org/ecma-262/8.0/ some divergences
diff --git a/doc/pages/registers.asciidoc b/doc/pages/registers.asciidoc
index 206d38eab..8cdf788fa 100644
--- a/doc/pages/registers.asciidoc
+++ b/doc/pages/registers.asciidoc
@@ -1,18 +1,13 @@
-kakoune(k)
-==========
+= Registers
 
-NAME
-----
-registers - a
+== Description
 
-Description
------------
 Registers are named lists of text -instead of simply text- in order to interact
 well with multiselection. They are used for various purposes, like storing
 the last yanked text, or the captured groups associated with the selections.
 
-Interacting
------------
+== Interacting
+
 *<c-r><c>*::
 	when in insert mode or in a prompt, insert the value stored in the
 	*c* register (single character)
@@ -20,14 +15,13 @@ Interacting
 *"<c>*::
 	in normal mode, select the *<c>* register (single character)
 
-Alternate names
----------------
+== Alternate names
 
 Non alphanumeric registers have an alternative name that can be used
 in contexts where only alphanumeric identifiers are possible.
 
-Default registers
------------------
+== Default registers
+
 Most commands using a register default to a specific one if not specified:
 
 *"* (dquote)::
@@ -48,8 +42,8 @@ Most commands using a register default to a specific one if not specified:
 	default shell command register, used by command that spawn a subshell such as
 	*|*, *<a-|>*, *!* or *<a-!>*
 
-Special registers
------------------
+== Special registers
+
 Some registers are not general purposes, they cannot be written to, but they
 contain some special data
 
@@ -68,8 +62,8 @@ contain some special data
 *:* (colon)::
 	last entered command
 
-Integer registers
------------------
+== Integer registers
+
 Registers *1* to *9* hold the grouped sub-matches of the regular
 expression used to make the last selection. Example: applying the
 following regular expression to the date of the day would put the day of
diff --git a/doc/pages/scopes.asciidoc b/doc/pages/scopes.asciidoc
index 9df5458b7..52609d3bf 100644
--- a/doc/pages/scopes.asciidoc
+++ b/doc/pages/scopes.asciidoc
@@ -1,19 +1,12 @@
-kakoune(k)
-==========
+= Scopes
 
-NAME
-----
-scopes - a
-
-Description
------------
+== Description
 
 Scopes are groups in which a particular Kakoune object (a variable,
 hook, alias etc) can have different values, depending on the group the
 value was declared in.
 
-Names and hierarchy
--------------------
+== Names and hierarchy
 
 Scopes are named as follows:
 
@@ -34,8 +27,7 @@ The above priority line implies that objects can have individual values that
 will be resolved first in the *window* scope (highest priority), then in
 the *buffer* scope, and finally in the *global* scope (lowest priority).
 
-Uses
-----
+== Uses
 
 The scope paradigm is very useful as it allows the user to customize the
 behavior of the editor without modifying the configuration globally, as
@@ -56,8 +48,7 @@ Examples:
 	customized in the *buffer* scope with 'set', c.f. the 'options'
 	documentation page)
 
-Execution context
------------------
+== Execution context
 
 Some commands work in a specific context that might exclude one or
 several scopes altogether, consequently ignoring some values of a given
diff --git a/rc/core/doc.kak b/rc/core/doc.kak
index 84c56c6ea..c1a3c1e50 100644
--- a/rc/core/doc.kak
+++ b/rc/core/doc.kak
@@ -1,54 +1,64 @@
 decl -docstring "name of the client in which documentation is to be displayed" \
     str docsclient
 
-def -hidden -params 1..2 doc-open %{
-    %sh{
-        manout=$(mktemp "${TMPDIR:-/tmp}"/kak-man-XXXXXX)
+declare-option -hidden range-specs doc_render_ranges
 
-        # This option is handled by the `man-db` implementation
-        export MANWIDTH=${kak_window_width}
-
-        if man "$1" > "${manout}" 2>/dev/null; then
-            readonly manout_noescape=$(mktemp "${TMPDIR:-/tmp}"/kak-man-XXXXXX)
-
-            sed -e $(printf 's/.\x8//g') -e 's,\x1B\[[0-9;]*[a-zA-Z],,g' "${manout}" > "${manout_noescape}"
-            mv -f "${manout_noescape}" "${manout}"
-
-            printf %s\\n "
-                edit! -scratch '*doc*'
-                exec |cat<space>${manout}<ret>gg
-                nop %sh{rm ${manout}}
-                set buffer filetype man
-                remove-hooks window man-hooks
-            "
-
-            if [ $# -gt 1 ]; then
-                needle=$(printf %s\\n "$2" | sed 's,<,<lt>,g')
-                printf %s\\n "try %{ exec '%<a-s><a-k>(?i)^\h+[^\n]*?\Q${needle}\E<ret>\z' } catch %{ exec <space>gg }"
-            fi
-        else
-           printf %s\\n "echo -markup %{{Error}doc '$@' failed: see *debug* buffer for details}"
-           rm ${manout}
-        fi
-    }
+define-command -hidden -params 4 doc-render-regex %{
+    eval -draft %{ try %{
+        exec \%s %arg{1} <ret>
+        exec -draft s %arg{2} <ret> d
+        exec "%arg{3}"
+        %sh{
+            ranges=$(echo "$kak_selections_desc" | sed -e "s/:/|$4:/g; s/\$/|$4/")
+            echo "update-option buffer doc_render_ranges"
+            echo "set -add buffer doc_render_ranges '$ranges'"
+        }
+    } }
 }
 
-def -params 1..2 \
+define-command -params 1 -hidden doc-render %{
+    edit! -scratch *doc*
+    exec "!cat %arg{1}<ret>gg"
+
+    # Join paragraphs together
+    try %{ exec -draft \%S \n{2,}|(?<=\+)\n|^[^\n]+::\n <ret> <a-K>^-{2,}(\n|\z)<ret> S\n\z<ret> <a-k>\n<ret> <a-j> }
+
+    # Remove some line end markers
+    try %{ exec -draft \%s \h*(\+|:{2,})$ <ret> d }
+
+    # Setup the doc_render_ranges option
+    set buffer doc_render_ranges %val{timestamp}
+    doc-render-regex \B(?<!\\)\*[^\n]+?(?<!\\)\*\B \A|.\z 'H' default+b
+    doc-render-regex \B(?<!\\)`[^\n]+?(?<!\\)`\B \A|.\z 'H' mono
+    doc-render-regex ^=\h+[^\n]+ ^=\h+ '~' title
+    doc-render-regex ^={2,}\h+[^\n]+ ^={2,}\h+ '' header
+    doc-render-regex ^-{2,}\n.*?^-{2,}\n ^-{2,}\n '' block
+    doc-render-regex <lt><lt>.*?<gt><gt> <lt><lt>.*,|<gt><gt> 'H' link
+
+    # Remove escaping of * and `
+    try %{ exec -draft \%s \\((?=\*)|(?=`)) <ret> d }
+
+    set-option buffer readonly true
+    add-highlighter buffer ranges doc_render_ranges
+    add-highlighter buffer wrap -word -indent
+}
+
+def -params 1 \
     -shell-candidates %{
-        find "${kak_runtime}/doc/" -type f -name "*.gz" | while read l; do
+        find "${kak_runtime}/doc/" -type f -name "*.asciidoc" | while read l; do
             basename "${l%.*}"
         done
     } \
     doc -docstring %{doc <topic> [<keyword>]: open a buffer containing documentation about a given topic
 An optional keyword argument can be passed to the function, which will be automatically selected in the documentation} %{
     %sh{
-        readonly PATH_DOC="${kak_runtime}/doc/${1}.gz"
+        readonly page="${kak_runtime}/doc/${1}.asciidoc"
 
         shift
-        if [ -f "${PATH_DOC}" ]; then
-            printf %s\\n "eval -try-client %opt{docsclient} doc-open ${PATH_DOC} $@"
+        if [ -f "${page}" ]; then
+            printf %s\\n "eval -try-client %opt{docsclient} doc-render ${page}"
         else
-            printf %s\\n "echo -markup '{Error}No such doc file: ${PATH_DOC}'"
+            printf %s\\n "echo -markup '{Error}No such doc file: ${page}'"
         fi
     }
 }
diff --git a/src/Makefile b/src/Makefile
index 01db5c8de..534db36ea 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -16,8 +16,6 @@ endif
 sources := $(sort $(wildcard *.cc))
 objects := $(addprefix ., $(sources:.cc=$(suffix).o))
 deps := $(addprefix ., $(sources:.cc=$(suffix).d))
-docs := $(wildcard ../doc/pages/*.asciidoc)
-mandocs := $(docs:.asciidoc=.gz)
 
 PREFIX ?= /usr/local
 DESTDIR ?= # root dir
@@ -77,16 +75,6 @@ kak$(suffix) : $(objects)
 	a2x --no-xmllint -f manpage $<
 	gzip -n -9 -f $(basename $<)
 
-# Generate the editor's documentation pages
-# Since `a2x` won't generate man pages if some sections are missing (which we don't need),
-# we generate the pages, patch them and then compress them
-../doc/pages/%.gz: ../doc/pages/%.asciidoc
-	a2x --no-xmllint -f manpage $<
-	sed -i -r -e "s,^\.TH .+,.TH kakoune k \"\" \"\" \"$(basename $(notdir $<))\"," \
-	-e "/^\.SH \"NAME\"/{N;d;}" $(@:.gz=.k)
-	gzip -n -9 -f $(@:.gz=.k)
-	mv -f $(@:.gz=.k.gz) $@
-
 check: test
 test:
 	cd ../test && ./run
@@ -95,7 +83,6 @@ TAGS: tags
 tags:
 	ctags -R
 man: ../doc/kak.1.gz
-doc: $(mandocs)
 
 clean:
 	rm -f .*.o .*.d
@@ -114,10 +101,10 @@ installdirs:
 		$(docdir) \
 		$(mandir)
 
-install: kak man doc installdirs
+install: kak man installdirs
 	install -m 0755 kak $(bindir)
 	install -m 0644 ../share/kak/kakrc $(sharedir)
-	install -m 0644 ../doc/pages/*.gz $(sharedir)/doc
+	install -m 0644 ../doc/pages/*.asciidoc $(sharedir)/doc
 	install -m 0644 ../rc/base/* $(sharedir)/rc/base
 	install -m 0644 ../rc/core/* $(sharedir)/rc/core
 	install -m 0644 ../rc/extra/* $(sharedir)/rc/extra
@@ -136,4 +123,4 @@ uninstall:
 		$(mandir)/kak.1.gz
 
 .PHONY: check TAGS clean distclean installdirs install install-strip uninstall
-.PHONY: tags test man doc kak
+.PHONY: tags test man kak