diff --git a/doc/pages/command-parsing.asciidoc b/doc/pages/command-parsing.asciidoc
new file mode 100644
index 00000000..aebe9eba
--- /dev/null
+++ b/doc/pages/command-parsing.asciidoc
@@ -0,0 +1,77 @@
+= Command Parsing
+
+Kakoune commands, either loaded from a script, or written in the command
+prompt are parsed according to the following rules:
+
+== Basic parsing
+
+- Commands are separated by `;` or end of lines
+
+- Words (command names and parameters) are separated by whitespaces
+
+== Quoted Strings
+
+If a word starts with `'`, `"` or `%X` with `X` a non nestable
+punctuation character it is parsed as a quoted string whose delimiter is,
+respectively, `'`, `"` or `X`.
+
+A quoted string contains every characters (including whitespaces) until
+its closing delimiter. If its closing delimiter is doubled, then it is
+considered to be part of the string content as a single delimiter.
+
+No other escaping takes place in quoted strings.
+
+=== Quoted Strings Examples
+
+- `'foo'` contents is *foo*
+
+- `'foo''bar'` is a single word whose content is *foo'bar*
+
+- `"baz"""` is a single word whose content is *baz"*.
+
+== Balanced Strings
+
+If a word starts with `%X` with `X` a nestable punctuation character (one
+of `(`, `[`, `{` and `<`), it is parsed as a balanced string whose closing
+delimiter is the matching character of its opening delimiter (respectively
+`)`, `]`, `}` and `>`).
+
+A balanced string contains every character (including whitespaces) until
+a closing delimiter is found, and opening and closing delimiters are
+balanced inside the string (each opening delimiter appearing inside the
+string have been closed by a matching closing delimiter).
+
+No other escaping takes place in balanced strings.
+
+=== Balanced Strings Examples
+
+- `%{foo}` contents is *foo*
+
+- `%{foo\{bar}}` contents is *foo\{bar}*
+
+== Non Quoted words
+
+Other words are non-quoted. Non-quoted words end either on a whitespaces
+or a `;`.
+
+If they start with `\\` followed by `%`, `'` or `"`, then that leading
+`\\` is discarded.
+
+If a whitespace or `;` is preceeded by `\\`, then the `\\` is discarded
+and the whitespace or `;` becomes part of the word. Any other `\\`
+is treated as a literal `\\`.
+
+== Typed Expansions
+
+Quoted and Balanced strings startings with `%` might have an optional
+alphabetic *expansion type* between the `%` and their delimiter (which
+is always a punctuation character). This *expansion type* defines how the
+string content is going to be expanded.
+
+- If the *expansion type* is empty, the string content is used verbatim.
+
+- If the *expansion type* is one of `sh`, `reg`, `opt`, `val` or `arg`,
+  The string is expanded according as described in
+  <<expansions#typed-expansions,`:doc expansion typed-expansions`>>
+
+- For any other *expansion type* a parsing error is raised.