docs: Move docs into docs/

docs/highlighters.md

@@ -0,0 +1,59 @@
+zsh-syntax-highlighting / highlighters
+======================================
+
+Syntax highlighting is done by pluggable highlighters:
+
+* [`main`](highlighters/main.md) - the base highlighter, and the only one active by default.
+* [`brackets`](highlighters/brackets.md) - matches brackets and parenthesis.
+* [`pattern`](highlighters/pattern.md) - matches user-defined patterns.
+* [`cursor`](highlighters/cursor.md) - matches the cursor position.
+* [`root`](highlighters/root.md) - triggered if the current user is root.
+* [`line`](highlighters/line.md) - applied to the whole command line
+
+
+How to activate highlighters
+----------------------------
+
+To activate an highlighter, add it to the `ZSH_HIGHLIGHT_HIGHLIGHTERS` array in
+`~/.zshrc`, for example:
+
+    ZSH_HIGHLIGHT_HIGHLIGHTERS=(main brackets pattern cursor)
+
+
+How to tweak highlighters
+-------------------------
+
+Highlighters look up styles from the `ZSH_HIGHLIGHT_STYLES` array.
+Navigate into each highlighter directory to see what styles it defines
+and how to configure it.
+
+
+How to implement a new highlighter
+----------------------------------
+
+To create your own `myhighlighter` highlighter:
+
+* Create your script at
+    `highlighters/${myhighlighter}/${myhighlighter}-highlighter.zsh`.
+
+* Implement the `_zsh_highlight_myhighlighter_highlighter_predicate` function.
+  This function must return 0 when the highlighter needs to be called and
+  non-zero otherwise, for example:
+
+        _zsh_highlight_myhighlighter_highlighter_predicate() {
+          # Call this highlighter in SVN repositories
+          [[ -d .svn ]]
+        }
+
+* Implement the `_zsh_highlight_myhighlighter_highlighter` function.
+  This function does the actual syntax highlighting, by modifying
+  `region_highlight`, for example:
+
+        _zsh_highlight_myhighlighter_highlighter() {
+          # Colorize the whole buffer with blue background
+          region_highlight+=(0 $#BUFFER bg=blue)
+        }
+
+* Activate your highlighter in `~/.zshrc`:
+
+        ZSH_HIGHLIGHT_HIGHLIGHTERS+=(myhighlighter)

docs/highlighters/brackets.md

@@ -0,0 +1,26 @@
+zsh-syntax-highlighting / highlighters / brackets
+-------------------------------------------------
+
+This is the `brackets` highlighter, that highlights brackets and parentheses, and
+matches them.
+
+
+### How to tweak it
+
+This highlighter defines the following styles:
+
+* `bracket-error` - unmatched brackets
+* `bracket-level-N` - brackets with nest level N
+* `cursor-matchingbracket` - the matching bracket, if cursor is on a bracket
+
+To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
+for example in `~/.zshrc`:
+
+    # To define styles for nested brackets up to level 4
+    ZSH_HIGHLIGHT_STYLES[bracket-level-1]='fg=blue,bold'
+    ZSH_HIGHLIGHT_STYLES[bracket-level-2]='fg=red,bold'
+    ZSH_HIGHLIGHT_STYLES[bracket-level-3]='fg=yellow,bold'
+    ZSH_HIGHLIGHT_STYLES[bracket-level-4]='fg=magenta,bold'
+
+The syntax for declaring styles is documented in [the `zshzle(1)` manual
+page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

docs/highlighters/cursor.md

@@ -0,0 +1,19 @@
+zsh-syntax-highlighting / highlighters / cursor
+-----------------------------------------------
+
+This is the `cursor` highlighter, that highlights the cursor.
+
+
+### How to tweak it
+
+This highlighter defines the following styles:
+
+* `cursor` - the style for the current cursor position
+
+To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
+for example in `~/.zshrc`:
+
+    ZSH_HIGHLIGHT_STYLES[cursor]='bg=blue'
+
+The syntax for declaring styles is documented in [the `zshzle(1)` manual
+page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

docs/highlighters/line.md

@@ -0,0 +1,19 @@
+zsh-syntax-highlighting / highlighters / line
+---------------------------------------------
+
+This is the `line` highlighter, that highlights the whole line.
+
+
+### How to tweak it
+
+This highlighter defines the following styles:
+
+* `line` - the style for the whole line
+
+To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
+for example in `~/.zshrc`:
+
+    ZSH_HIGHLIGHT_STYLES[line]='bold'
+
+The syntax for declaring styles is documented in [the `zshzle(1)` manual
+page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

docs/highlighters/main.md

@@ -0,0 +1,63 @@
+zsh-syntax-highlighting / highlighters / main
+---------------------------------------------
+
+This is the `main` highlighter, that highlights:
+
+* Commands
+* Options
+* Arguments
+* Paths
+* Strings
+
+This highlighter is active by default.
+
+
+### How to tweak it
+
+This highlighter defines the following styles:
+
+* `unknown-token` - unknown tokens / errors
+* `reserved-word` - shell reserved words (`if`, `for`)
+* `alias` - aliases
+* `suffix-alias` - suffix aliases (requires zsh 5.1.1 or newer)
+* `builtin` - shell builtin commands (`shift`, `pwd`, `zstyle`)
+* `function` - function names
+* `command` - command names
+* `precommand` - precommand modifiers (e.g., `noglob`, `builtin`)
+* `commandseparator` - command separation tokens (`;`, `&&`)
+* `hashed-command` - hashed commands
+* `path` - existing filenames
+* `path_prefix` - prefixes of existing filenames
+* `globbing` - globbing expressions (`*.txt`)
+* `history-expansion` - history expansion expressions (`!foo` and `^foo^bar`)
+* `single-hyphen-option` - single hyphen options (`-o`)
+* `double-hyphen-option` - double hyphen options (`--option`)
+* `back-quoted-argument` - backquoted expressions (`` `foo` ``)
+* `single-quoted-argument` - single quoted arguments (`` 'foo' ``)
+* `double-quoted-argument` - double quoted arguments (`` "foo" ``)
+* `dollar-quoted-argument` - dollar quoted arguments (`` $'foo' ``)
+* `dollar-double-quoted-argument` - parameter expansion inside double quotes (`$foo` inside `""`)
+* `back-double-quoted-argument` -  back double quoted arguments (`\x` inside `""`)
+* `back-dollar-quoted-argument` -  back dollar quoted arguments (`\x` inside `$''`)
+* `assign` - parameter assignments
+* `redirection` - redirection operators (`<`, `>`, etc)
+* `comment` - comments, when `setopt INTERACTIVE_COMMENTS` is in effect (`echo # foo`)
+* `default` - everything else
+
+To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
+for example in `~/.zshrc`:
+
+    # Declare the variable
+    typeset -A ZSH_HIGHLIGHT_STYLES
+
+    # To differentiate aliases from other command types
+    ZSH_HIGHLIGHT_STYLES[alias]='fg=magenta,bold'
+    
+    # To have paths colored instead of underlined
+    ZSH_HIGHLIGHT_STYLES[path]='fg=cyan'
+    
+    # To disable highlighting of globbing expressions
+    ZSH_HIGHLIGHT_STYLES[globbing]='none'
+
+The syntax for declaring styles is documented in [the `zshzle(1)` manual
+page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

docs/highlighters/pattern.md

@@ -0,0 +1,16 @@
+zsh-syntax-highlighting / highlighters / pattern
+------------------------------------------------
+
+This is the `pattern` highlighter, that highlights user defined patterns.
+
+
+### How to tweak it
+
+To use this highlighter, associate patterns with styles in the
+`ZSH_HIGHLIGHT_PATTERNS` array, for example in `~/.zshrc`:
+
+    # To have commands starting with `rm -rf` in red:
+    ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')
+
+The syntax for declaring styles is documented in [the `zshzle(1)` manual
+page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

docs/highlighters/root.md

@@ -0,0 +1,20 @@
+zsh-syntax-highlighting / highlighters / root
+---------------------------------------------
+
+This is the `root` highlighter, that highlights the whole line if the current
+user is root.
+
+
+### How to tweak it
+
+This highlighter defines the following styles:
+
+* `root` - the style for the whole line if the current user is root.
+
+To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
+for example in `~/.zshrc`:
+
+    ZSH_HIGHLIGHT_STYLES[root]='bg=red'
+
+The syntax for declaring styles is documented in [the `zshzle(1)` manual
+page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

highlighters/README.md

@@ -1,59 +0,0 @@
-zsh-syntax-highlighting / highlighters
-======================================
-
-Syntax highlighting is done by pluggable highlighters:
-
-* [`main`](main) - the base highlighter, and the only one active by default.
-* [`brackets`](brackets) - matches brackets and parenthesis.
-* [`pattern`](pattern) - matches user-defined patterns.
-* [`cursor`](cursor) - matches the cursor position.
-* [`root`](root) - triggered if the current user is root.
-* [`line`](line) - applied to the whole command line
-
-
-How to activate highlighters
-----------------------------
-
-To activate an highlighter, add it to the `ZSH_HIGHLIGHT_HIGHLIGHTERS` array in
-`~/.zshrc`, for example:
-
-    ZSH_HIGHLIGHT_HIGHLIGHTERS=(main brackets pattern cursor)
-
-
-How to tweak highlighters
--------------------------
-
-Highlighters look up styles from the `ZSH_HIGHLIGHT_STYLES` array.
-Navigate into each highlighter directory to see what styles it defines
-and how to configure it.
-
-
-How to implement a new highlighter
-----------------------------------
-
-To create your own `myhighlighter` highlighter:
-
-* Create your script at
-    `highlighters/${myhighlighter}/${myhighlighter}-highlighter.zsh`.
-
-* Implement the `_zsh_highlight_myhighlighter_highlighter_predicate` function.
-  This function must return 0 when the highlighter needs to be called and
-  non-zero otherwise, for example:
-
-        _zsh_highlight_myhighlighter_highlighter_predicate() {
-          # Call this highlighter in SVN repositories
-          [[ -d .svn ]]
-        }
-
-* Implement the `_zsh_highlight_myhighlighter_highlighter` function.
-  This function does the actual syntax highlighting, by modifying
-  `region_highlight`, for example:
-
-        _zsh_highlight_myhighlighter_highlighter() {
-          # Colorize the whole buffer with blue background
-          region_highlight+=(0 $#BUFFER bg=blue)
-        }
-
-* Activate your highlighter in `~/.zshrc`:
-
-        ZSH_HIGHLIGHT_HIGHLIGHTERS+=(myhighlighter)

highlighters/README.md

@@ -0,0 +1 @@
+../docs/highlighters.md

highlighters/brackets/README.md

@@ -1,26 +0,0 @@
-zsh-syntax-highlighting / highlighters / brackets
--------------------------------------------------
-
-This is the `brackets` highlighter, that highlights brackets and parentheses, and
-matches them.
-
-
-### How to tweak it
-
-This highlighter defines the following styles:
-
-* `bracket-error` - unmatched brackets
-* `bracket-level-N` - brackets with nest level N
-* `cursor-matchingbracket` - the matching bracket, if cursor is on a bracket
-
-To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
-for example in `~/.zshrc`:
-
-    # To define styles for nested brackets up to level 4
-    ZSH_HIGHLIGHT_STYLES[bracket-level-1]='fg=blue,bold'
-    ZSH_HIGHLIGHT_STYLES[bracket-level-2]='fg=red,bold'
-    ZSH_HIGHLIGHT_STYLES[bracket-level-3]='fg=yellow,bold'
-    ZSH_HIGHLIGHT_STYLES[bracket-level-4]='fg=magenta,bold'
-
-The syntax for declaring styles is documented in [the `zshzle(1)` manual
-page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

highlighters/brackets/README.md

@@ -0,0 +1 @@
+../docs/highlighters/brackets.md

highlighters/cursor/README.md

@@ -1,19 +0,0 @@
-zsh-syntax-highlighting / highlighters / cursor
------------------------------------------------
-
-This is the `cursor` highlighter, that highlights the cursor.
-
-
-### How to tweak it
-
-This highlighter defines the following styles:
-
-* `cursor` - the style for the current cursor position
-
-To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
-for example in `~/.zshrc`:
-
-    ZSH_HIGHLIGHT_STYLES[cursor]='bg=blue'
-
-The syntax for declaring styles is documented in [the `zshzle(1)` manual
-page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

highlighters/cursor/README.md

@@ -0,0 +1 @@
+../docs/highlighters/cursor.md

highlighters/line/README.md

@@ -1,19 +0,0 @@
-zsh-syntax-highlighting / highlighters / line
----------------------------------------------
-
-This is the `line` highlighter, that highlights the whole line.
-
-
-### How to tweak it
-
-This highlighter defines the following styles:
-
-* `line` - the style for the whole line
-
-To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
-for example in `~/.zshrc`:
-
-    ZSH_HIGHLIGHT_STYLES[line]='bold'
-
-The syntax for declaring styles is documented in [the `zshzle(1)` manual
-page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

highlighters/line/README.md

@@ -0,0 +1 @@
+../docs/highlighters/line.md

highlighters/main/README.md

@@ -1,63 +0,0 @@
-zsh-syntax-highlighting / highlighters / main
----------------------------------------------
-
-This is the `main` highlighter, that highlights:
-
-* Commands
-* Options
-* Arguments
-* Paths
-* Strings
-
-This highlighter is active by default.
-
-
-### How to tweak it
-
-This highlighter defines the following styles:
-
-* `unknown-token` - unknown tokens / errors
-* `reserved-word` - shell reserved words (`if`, `for`)
-* `alias` - aliases
-* `suffix-alias` - suffix aliases (requires zsh 5.1.1 or newer)
-* `builtin` - shell builtin commands (`shift`, `pwd`, `zstyle`)
-* `function` - function names
-* `command` - command names
-* `precommand` - precommand modifiers (e.g., `noglob`, `builtin`)
-* `commandseparator` - command separation tokens (`;`, `&&`)
-* `hashed-command` - hashed commands
-* `path` - existing filenames
-* `path_prefix` - prefixes of existing filenames
-* `globbing` - globbing expressions (`*.txt`)
-* `history-expansion` - history expansion expressions (`!foo` and `^foo^bar`)
-* `single-hyphen-option` - single hyphen options (`-o`)
-* `double-hyphen-option` - double hyphen options (`--option`)
-* `back-quoted-argument` - backquoted expressions (`` `foo` ``)
-* `single-quoted-argument` - single quoted arguments (`` 'foo' ``)
-* `double-quoted-argument` - double quoted arguments (`` "foo" ``)
-* `dollar-quoted-argument` - dollar quoted arguments (`` $'foo' ``)
-* `dollar-double-quoted-argument` - parameter expansion inside double quotes (`$foo` inside `""`)
-* `back-double-quoted-argument` -  back double quoted arguments (`\x` inside `""`)
-* `back-dollar-quoted-argument` -  back dollar quoted arguments (`\x` inside `$''`)
-* `assign` - parameter assignments
-* `redirection` - redirection operators (`<`, `>`, etc)
-* `comment` - comments, when `setopt INTERACTIVE_COMMENTS` is in effect (`echo # foo`)
-* `default` - everything else
-
-To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
-for example in `~/.zshrc`:
-
-    # Declare the variable
-    typeset -A ZSH_HIGHLIGHT_STYLES
-
-    # To differentiate aliases from other command types
-    ZSH_HIGHLIGHT_STYLES[alias]='fg=magenta,bold'
-    
-    # To have paths colored instead of underlined
-    ZSH_HIGHLIGHT_STYLES[path]='fg=cyan'
-    
-    # To disable highlighting of globbing expressions
-    ZSH_HIGHLIGHT_STYLES[globbing]='none'
-
-The syntax for declaring styles is documented in [the `zshzle(1)` manual
-page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

highlighters/main/README.md

@@ -0,0 +1 @@
+../docs/highlighters/main.md

highlighters/pattern/README.md

@@ -1,16 +0,0 @@
-zsh-syntax-highlighting / highlighters / pattern
-------------------------------------------------
-
-This is the `pattern` highlighter, that highlights user defined patterns.
-
-
-### How to tweak it
-
-To use this highlighter, associate patterns with styles in the
-`ZSH_HIGHLIGHT_PATTERNS` array, for example in `~/.zshrc`:
-
-    # To have commands starting with `rm -rf` in red:
-    ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')
-
-The syntax for declaring styles is documented in [the `zshzle(1)` manual
-page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

highlighters/pattern/README.md

@@ -0,0 +1 @@
+../docs/highlighters/pattern.md

highlighters/root/README.md

@@ -1,20 +0,0 @@
-zsh-syntax-highlighting / highlighters / root
----------------------------------------------
-
-This is the `root` highlighter, that highlights the whole line if the current
-user is root.
-
-
-### How to tweak it
-
-This highlighter defines the following styles:
-
-* `root` - the style for the whole line if the current user is root.
-
-To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
-for example in `~/.zshrc`:
-
-    ZSH_HIGHLIGHT_STYLES[root]='bg=red'
-
-The syntax for declaring styles is documented in [the `zshzle(1)` manual
-page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

highlighters/root/README.md

@@ -0,0 +1 @@
+../docs/highlighters/root.md