Fix export-breaking org links in documentation

As discussed in #8054 and #8136, org doesn't always export links correctly if
the syntax deviates from the one given on the org mode website. This results
in broken links on github and/or spacemacs.org as in #6722, #8036, #8054, #7956
and possibly others.

This modifies all links not already fixed in #8136. Internal links are
handled with Custom IDs. External file links are formatted according to org
guidelines as well (see bottom), and if they point to a specific headline in an
external file, a custom ID is created as well.

Fixes #6722, #8036, #7956, #7916 as well as other unreported broken
links.

http://orgmode.org/manual/External-links.html#External-links
http://orgmode.org/manual/Internal-links.html#Internal-links

TODO: make Custom IDs invisble in space-org-mode

doc/DOCUMENTATION.org

@@ -260,7 +260,7 @@ project.
 
 * Who can benefit from this?
 - Spacemacs was initially intended to be used by *Vim users* who want to go to
-  the next level by using Emacs (see [[./VIMUSERS.org][guide]] for Vimmers). But it is now
+  the next level by using Emacs (see [[file:VIMUSERS.org][guide]] for Vimmers). But it is now
   perfectly *usable by non Vim users* by choosing the =emacs= editing style.
 
 - It is also a good fit for people wanting to *lower the [[http://en.wikipedia.org/wiki/Repetitive_strain_injury][risk of RSI]]* induced by
@@ -325,6 +325,9 @@ and choosing a rollback slot (sorted by date). This button uses the command
 =configuration-layer/rollback=.
 
 * Configuration layers
+  :PROPERTIES:
+  :CUSTOM_ID: configuration-layers
+  :END:
 This section is an overview of layers. A more extensive introduction to writing
 configuration layers can be found [[file:LAYERS.org][here]] (recommended reading!).
 
@@ -458,7 +461,7 @@ guidelines first in [[file:../CONTRIBUTING.org][CONTRIBUTING]].
 
 ** Example: Themes Megapack example
 This is a simple configuration layer listing a bunch of themes which you can
-find [[../layers/+themes/themes-megapack/README.org][here]].
+find [[file:../layers/+themes/themes-megapack/README.org][here]].
 
 To install it, just add =themes-megapack= to your =~/.spacemacs= like so:
 
@@ -501,6 +504,9 @@ Please refer to [[file:LAYERS.org][this]] introduction for some tips on writing
 best make them fit with the Spacemacs philosophy and loading strategy.
 
 * Dotfile Configuration
+:PROPERTIES:
+:CUSTOM_ID: dotfile-configuration
+:END:
 User configuration can be stored in your =~/.spacemacs= file.
 
 ** Dotfile Installation
@@ -598,7 +604,7 @@ to add some layers in =~/.myconfig=, set the variable like this:
 
 *** Setting configuration layers variables
 Some configuration layers have configuration variables to enable specific
-feature. For instance the [[../layers/%2Bsource-control/git][git layer]] has several configuration variables, they
+feature. For instance the [[file:../layers/+source-control/git/README.org][git layer]] has several configuration variables, they
 can be set directly in the =dotspacemacs-configuration-layers= like this:
 
 #+BEGIN_SRC emacs-lisp
@@ -692,7 +698,7 @@ orphan so it is considered unused by Spacemacs).
 
 *** Excluding packages
 You can exclude packages you don't want to install with the variable
-=dotspacemacs-excluded-packages= (see [[Configuration layers][Configuration layers]] for more info
+=dotspacemacs-excluded-packages= (see [[#configuration-layers][Configuration layers]] for more info
 on packages).
 
 For instance, to disable the =rainbow-delimiters= package:
@@ -785,6 +791,9 @@ To toggle the hybrid style on and off use ~SPC t E h~ and ~M-m t E h~. When
 off the =vim= style is enabled.
 
 ** States
+:PROPERTIES:
+:CUSTOM_ID: states
+:END:
 Spacemacs has 10 states:
 
 | State        | Default Color | Description                                                                                                |
@@ -797,9 +806,9 @@ Spacemacs has 10 states:
 | replace      | chocolate     | exclusive to =Evil=, overwrites the character under point instead of inserting a new one                   |
 | hybrid       | blue          | exclusive to Spacemacs, this is like the insert state except that all the emacs key bindings are available |
 | evilified    | light brown   | exclusive to Spacemacs, this is an =emacs state= modified to bring Vim navigation, selection and search.   |
-| lisp         | pink          | exclusive to Spacemacs, used to navigate Lisp code and modify it (more [[Editing Lisp code][info]])                               |
-| iedit        | red           | exclusive to Spacemacs, used to navigate between multiple regions of text using =iedit= (more [[Replacing text with iedit][info]])        |
-| iedit-insert | red           | exclusive to Spacemacs, used to replace multiple regions of text using =iedit= (more [[Replacing text with iedit][info]])                 |
+| lisp         | pink          | exclusive to Spacemacs, used to navigate Lisp code and modify it (more [[#editing-lisp-code][info]])                               |
+| iedit        | red           | exclusive to Spacemacs, used to navigate between multiple regions of text using =iedit= (more [[#replacing-text-with-iedit][info]])        |
+| iedit-insert | red           | exclusive to Spacemacs, used to replace multiple regions of text using =iedit= (more [[#replacing-text-with-iedit][info]])                 |
 
 Note: Technically speaking there is also the =operator= evil state.
 
@@ -853,6 +862,9 @@ to ~SPC u~.
 pressing ~RETURN~. For instance: ~SPC SPC org-reload C-u RET~
 
 ** Transient-states
+   :PROPERTIES:
+   :CUSTOM_ID: transient-states
+   :END:
 Spacemacs defines a wide variety of =transient states= (temporary overlay maps)
 where it makes sense. This prevents one from doing repetitive and tedious
 presses on the ~SPC~ key.
@@ -862,7 +874,7 @@ minibuffer. Additional information may as well be displayed in the minibuffer.
 
 Auto-highlight-symbol transient state:
 [[file:img/spacemacs-ahs-transient-state.png]]
-[[Text][Text scale transient state]]:
+[[#text][Text scale transient state]]:
 
 [[file:img/spacemacs-scale-transient-state.png]]
 
@@ -1268,7 +1280,7 @@ can be reached using the =control= key.
 | ~SPC t p~   | =ⓟ=     | p     | [[https://github.com/Fuco1/smartparens][smartparens]] mode                                                     |
 | ~SPC t C-p~ | =ⓟ=     | p     | global smartparens                                                   |
 | ~SPC t s~   | =ⓢ=     | s     | syntax checking (flycheck)                                           |
-| ~SPC t S~   | =Ⓢ=     | S     | enabled in [[../layers/+checkers/spell-checking][spell checking layer]] (flyspell)                           |
+| ~SPC t S~   | =Ⓢ=     | S     | enabled in [[file:../layers/+checkers/spell-checking/README.org][spell checking layer]] (flyspell)                           |
 | ~SPC t w~   | =ⓦ=     | w     | whitespace mode                                                      |
 | ~SPC t C-w~ | =ⓦ=     | w     | global whitespace                                                    |
 | ~SPC t W~   | =Ⓦ=     | W     | automatic whitespace cleanup (see =dotspacemacs-whitespace-cleanup=) |
@@ -1557,7 +1569,10 @@ If you find yourself unable to return focus to Helm (after a careless
 mouse-click for example), use ~SPC w b~ to return focus to the minibuffer.
 
 **** Helm transient state
-Spacemacs defines a [[Transient-states][transient state]] for =Helm= to make it work like [[https://github.com/Shougo/unite.vim][Vim's Unite]]
+     :PROPERTIES:
+     :CUSTOM_ID: helm-transient-state
+     :END:
+Spacemacs defines a [[#transient-states][transient state]] for =Helm= to make it work like [[https://github.com/Shougo/unite.vim][Vim's Unite]]
 plugin.
 
 Initiate the transient state with ~M-SPC~ or ~s-M-SPC~ while in a =Helm= buffer.
@@ -1729,7 +1744,7 @@ Spacemacs.
 
 *** Toggles
 =helm-spacemacs-help= is also a central place to discover the available toggles.
-To display only the toggles source press ~C-l~ (or in [[Helm transient state][Helm transient state]] you can
+To display only the toggles source press ~C-l~ (or in [[#helm-transient-state][Helm transient state]] you can
 press just ~l~).
 
 The following helm actions are available on packages:
@@ -2010,10 +2025,13 @@ the opened buffer and kill them.
 | Any other key | leave the transient state                     |
 
 **** Special Buffers
+:PROPERTIES:
+:CUSTOM_ID: special-buffers
+:END:
 Unlike vim, emacs creates many buffers that most people do not need to see. Some
 examples are =*Messages*= and =*Compile-Log*=. Spacemacs tries to automatically
 ignore buffers that are not useful. However, you may want to change the way
-Spacemacs marks buffers as useful. For instructions, see the [[file:FAQ.org::Change%20special%20buffer%20rules?][special buffer howto]].
+Spacemacs marks buffers as useful. For instructions, see the [[file:FAQ.org::#change-special-buffer-rules][special buffer howto]].
 
 **** Files manipulations key bindings
 Files manipulation commands (start with ~f~):
@@ -2097,7 +2115,7 @@ Basic =ido= operations can be done with ~Ctrl~ key:
 | ~C-S-l~            | go to next directory                              |
 
 *** Ido transient state
-Spacemacs defines a [[Transient-states][transient state]] for =ido=.
+Spacemacs defines a [[#transient-states][transient state]] for =ido=.
 
 Initiate the transient state with ~M-SPC~ or ~s-M-SPC~ while in an =ido= buffer.
 
@@ -2410,6 +2428,9 @@ bindings (~SPC e n~ and ~SPC e p~) as well as the error transient state (~SPC e~
 | ~SPC s t F~ | =pt= with default text                              |
 
 **** Searching in a project
+:PROPERTIES:
+:CUSTOM_ID: searching-in-a-project
+:END:
 
 | Key Binding           | Description                                         |
 |-----------------------+-----------------------------------------------------|
@@ -2498,7 +2519,7 @@ Where =<M> [x/y]*= is:
 With [[https://github.com/bling/evil-visualstar][evil-visualstar]] you can search for the next occurrence of the current
 selection.
 
-It is pretty useful combined with the [[Region selection][expand-region]] bindings.
+It is pretty useful combined with the [[#expand-region][expand-region]] bindings.
 
 *Note*: If the current state is not the =visual state= then pressing ~*~ uses
 auto-highlight-symbol and its transient state.
@@ -2623,6 +2644,9 @@ It is possible to enable it easily for /all programming modes/ with the variable
 
 *** Zooming
 **** Text
+     :PROPERTIES:
+     :CUSTOM_ID: text
+     :END:
 The font size of the current buffer can be adjusted with the commands:
 
 | Key Binding   | Description                                                                    |
@@ -2676,7 +2700,7 @@ In transient state:
 argument (i.e. ~10 SPC n +~ will add 10 to the number under point).
 
 *** Spell checking
-Spell checking is enabled by including the [[../layers/+checkers/spell-checking][spell
+Spell checking is enabled by including the [[file:../layers/+checkers/spell-checking/README.org][spell
 checking]] layer in your dotfile.
 
 Keybindings are listed in the layer documentation.
@@ -2685,6 +2709,9 @@ Keybindings are listed in the layer documentation.
 Vi =Visual= modes are all supported by =evil=.
 
 **** Expand-region
+:PROPERTIES:
+:CUSTOM_ID: expand-region
+:END:
 Spacemacs adds another =Visual= mode via the [[https://github.com/magnars/expand-region.el][expand-region]] mode.
 
 | Key Binding | Description                              |
@@ -2726,6 +2753,9 @@ The displayed text of a buffer can be narrowed with the commands (start with
 | ~SPC n w~   | widen, i.e. show the whole buffer again    |
 
 *** Replacing text with iedit
+    :PROPERTIES:
+    :CUSTOM_ID: replacing-text-with-iedit
+    :END:
 Spacemacs uses the powerful [[https://github.com/tsdh/iedit][iedit]] mode through [[https://github.com/syl20bnr/evil-iedit-state][evil-iedit-state]] to quickly
 edit multiple occurrences of a symbol or selection.
 
@@ -2887,6 +2917,9 @@ To disable the trash you can set the variable =delete-by-moving-to-trash= to
 =nil= in your =~/.spacemacs=.
 
 *** Editing Lisp code
+    :PROPERTIES:
+    :CUSTOM_ID: editing-lisp-code
+    :END:
 Editing of lisp code is provided by [[https://github.com/syl20bnr/evil-lisp-state][evil-lisp-state]].
 
 Commands will set the current state to =lisp state= where different commands
@@ -2987,7 +3020,7 @@ are defined implicitly, for instance the root of a project is found when a
 
 =Helm= is used whenever it is possible.
 
-To search in a project see [[Searching in a project][project searching]].
+To search in a project see [[#searching-in-a-project][project searching]].
 
 =projectile= commands start with p:
 
@@ -3017,7 +3050,7 @@ To search in a project see [[Searching in a project][project searching]].
 | ~SPC p T~   | test project                                            |
 | ~SPC p v~   | open project root in =vc-dir= or =magit=                |
 | ~SPC /~     | search in project with the best search tool available   |
-| ~SPC s p~   | see [[Searching in a project][search in project]]                                   |
+| ~SPC s p~   | see [[#searching-in-a-project][searching in a project]]                              |
 | ~SPC s a p~ | run =ag=                                                |
 | ~SPC s g p~ | run =grep=                                              |
 | ~SPC s k p~ | run =ack=                                               |

doc/FAQ.org

@@ -263,6 +263,9 @@ the list =dotspacemacs-excluded-packages= if you prefer setting =exec-path=
 yourself.
 
 * How do I:
+:PROPERTIES:
+:CUSTOM_ID: how-do-i
+:END:
 ** Install a package not provided by a layer?
 Spacemacs provides a variable in the =dotspacemacs/layers= function in
 =.spacemacs= called =dotspacemacs-additional-packages=. Just add a package name
@@ -301,6 +304,9 @@ dotfile. The following snippet disables company for =python-mode=:
 #+END_SRC
 
 ** Change special buffer rules?
+   :PROPERTIES:
+   :CUSTOM_ID: change-special-buffer-rules
+   :END:
 To change the way spacemacs marks buffers as useless, you can customize
 =spacemacs-useless-buffers-regexp= which marks buffers matching the regexp as
 useless. The variable =spacemacs-useful-buffers-regexp= marks buffers matching

doc/LAYERS.org

@@ -275,6 +275,9 @@ Use-package supports heaps of useful keywords. Look at the [[https://github.com/
 more.
 
 * Anatomy of a layer
+:PROPERTIES:
+:CUSTOM_ID: anatomy-of-a-layer
+:END:
 A layer is simply a folder somewhere in Spacemacs' layer search path that
 usually contains these files (listed in loading order).
 
@@ -498,6 +501,9 @@ hooks, if the package should be loaded upon some event. It is not unusual to
 have both!
 
 ** Use-package hooks
+:PROPERTIES:
+:CUSTOM_ID: use-package-hooks
+:END:
 Spacemacs includes a macro for adding more code to the =:init= or =:config=
 blocks of a call to =use-package=, after the fact. This is useful for =pre-init=
 or =post-init= functions to "inject" code into the =use-package= call of the

doc/QUICK_START.org

@@ -80,8 +80,8 @@ dotspacemacs-configuration-layers '(auto-completion
 At anytime you can apply the changes made to the dotfile or layers
 _without restarting_ Spacemacs by pressing ~SPC f e R~.
 
-The [[file:../core/templates/.spacemacs.template][dotfile template]] contain further information about how to customize
-Spacemacs. See the dotfile configuration section of the [[file:DOCUMENTATION.org][documentation]] for
+The [[https://github.com/syl20bnr/spacemacs/blob/master/core/templates/.spacemacs.template][dotfile template]] contains further information about how to customize
+Spacemacs. See the dotfile configuration section of the [[file:DOCUMENTATION.org::#dotfile-configuration][documentation]] for
 more details.
 
 * Dotdirectory (~/.spacemacs.d)
@@ -174,4 +174,4 @@ about functions, variables, modes etc. These commands are bound thusly:
 | ~SPC h d v~ | describe-variable |
 
 * How-To's
-Some quick =how-to's= are compiled in the [[file:FAQ.org::How%20do%20I...][FAQ.org]] file.
+Some quick =how-to's= are compiled in the [[file:FAQ.org::#how-do-i][FAQ.]]