refactor(docs): replace nav menus with virtual one

Now that the header is dynamically generated (when doom-docs-mode is
active), a literal header is unnecessary.

core/autoload/docs.el

@@ -7,10 +7,90 @@
   (expand-file-name "../../docs/" (file-name-directory load-file-name))
   "Where Doom's documentation files are stored. Must end with a slash.")
 
+(defvar doom-docs-header-alist
+  `(("/docs/index\\.org$"
+     (left ("↖ FAQ" . "doom-faq:")))
+    (("/docs/[^/]+\\.org$" "/modules/README\\.org$")
+     (left ("← Back to index" . "doom-index:")))
+    ("/modules/[^/]+/README\\.org$"
+     (left ("← Back to module index" . "doom-module-index:")))
+    ("/modules/[^/]+/[^/]+/README\\.org$"
+     (left ("← Back to module index" . "doom-module-index:"))
+     (right ("↖ History"
+             . ,(lambda (file)
+                  (cl-destructuring-bind (category . module) (doom-module-from-path file)
+                    (format "doom-module-history:%s/%s" (doom-keyword-name category) module))))
+            ("! Issues"
+             . ,(lambda (file)
+                  (cl-destructuring-bind (category . module) (doom-module-from-path file)
+                    (format "doom-module-issues::%s %s" category module)))))))
+  "TODO")
+
+(defvar doom-docs-header-common-alist
+  `(("± Suggest edits" . "doom-suggest-edit:")
+    ("? Help"
+     . ,(lambda (_file)
+          (let ((title (cadar (org-collect-keywords '("TITLE")))))
+            (cond ((equal title "Changelog")   "doom-help-changelog:")
+                  ((string-prefix-p ":" title) "doom-help-modules:")
+                  ("doom-help:"))))))
+  "TODO")
+
 
 ;;
 ;;; `doom-docs-mode'
 
+(defun doom-docs--display-header-h ()
+  "Show header line in Doom documentation."
+  (let ((beg (point-min))
+        end)
+    (org-with-wide-buffer
+     (goto-char (point-min))
+     (when (looking-at-p org-drawer-regexp)
+       (re-search-forward org-drawer-regexp nil t 2)
+       (setq beg (1+ (line-end-position))))
+     (with-silent-modifications
+       (let ((inhibit-modification-hooks nil))
+         (when (re-search-forward "^-\\{80\\}" 512 t)
+           (delete-region beg (1+ (line-end-position))))
+         (when doom-docs-mode
+           (let* ((menu
+                   (cl-loop for (regexp . rules) in doom-docs-header-alist
+                            if (seq-find (doom-rpartial #'string-match-p (buffer-file-name))
+                                         (ensure-list regexp))
+                            return rules))
+                  (fn
+                   (lambda (menu)
+                     (cl-destructuring-bind (icon . label)
+                         (split-string (car menu) " ")
+                       (if (cdr menu)
+                           (format "%s [[%s][%s]]"
+                                   icon
+                                   (cond ((functionp (cdr menu))
+                                          (funcall (cdr menu) (buffer-file-name)))
+                                         ((file-name-absolute-p (cdr menu))
+                                          (concat "file:"
+                                                  (file-relative-name (file-truename (cdr menu)))))
+                                         ((cdr menu)))
+                                   (string-join label " "))
+                         (format "%s+ %s+" icon (string-join label " "))))))
+                  (lenfn
+                   (lambda (link)
+                     (length (replace-regexp-in-string org-link-any-re "\\3" link))))
+                  (sep  "  ")
+                  (lhs  (mapconcat fn (alist-get 'left menu) sep))
+                  (rhs  (mapconcat fn (append (alist-get 'right menu)
+                                              doom-docs-header-common-alist)
+                                   sep))
+                  (llen (funcall lenfn lhs))
+                  (rlen (funcall lenfn rhs))
+                  (pad  (max 0 (- 80 llen rlen))))
+             (insert lhs
+                     (if (zerop rlen) ""
+                       (format "%s%s" (make-string pad 32) rhs))
+                     "\n" (make-string 80 ?-) "\n")))))
+     (org-element-cache-refresh (point-min)))))
+
 (defun doom-docs--hide-meta-h ()
   "Hide all meta or comment lines."
   (org-with-wide-buffer
@@ -244,6 +324,7 @@ This primes `org-mode' for reading."
     (kill-local-variable 'doom-docs--initial-values)))
 
 (add-hook! 'doom-docs-mode-hook
+           #'doom-docs--display-header-h
            #'doom-docs--hide-meta-h
            #'doom-docs--hide-tags-h
            #'doom-docs--hide-drawers-h

core/cli/make.el

@@ -14,12 +14,7 @@
                   (format "doom-module-issues::%s %s" category module)))))))
 
 (defvar doom-cli-docs-common-menu
-  `(("↖ Github"
-     . ,(fn! (&key readme)
-          (if (file-exists-p! readme doom-modules-dir)
-              (format "doom-repo:tree/develop/modules/%s" (string-remove-prefix "./" (file-name-directory readme)))
-            (format "doom-repo:tree/develop/%s" (string-remove-prefix "./../" readme)))))
-    ("± Suggest edits" . "doom-suggest-edit:")
+  `(("± Suggest edits" . "doom-suggest-edit:")
     ("? Help"
      . ,(fn! (&key title)
           (cond ((equal title "Changelog")   "doom-help-changelog:")

modules/README.org

@@ -1,8 +1,6 @@
 :PROPERTIES:
 :ID:       12d2de30-c569-4b8e-bbc7-85dd5ccc4afa
 :END:
-← [[doom-index:][Back to index]]                                ↖ [[doom-repo:tree/develop/modules/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help:][Help]]
---------------------------------------------------------------------------------
 #+title:    Official modules
 #+subtitle: Doom Emacs' official module repository
 #+startup:  nonum

modules/app/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]                         ↖ [[doom-repo:tree/develop/modules/app/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:   :app
 #+created: February 19, 2017
 #+since:   21.12.0
@@ -8,3 +6,6 @@
 Application modules are complex and opinionated modules that transform Emacs
 toward a specific purpose. They may have additional dependencies and *should be
 loaded last* (but before [[doom-module:][:config]] modules).
+
+* Frequently asked questions
+/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

modules/app/calendar/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::app calendar][Issues]]  ↖ [[doom-repo:tree/develop/modules/app/calendar/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :app calendar
 #+subtitle: Watch your missed deadlines in real time
 #+created:  January 13, 2018

modules/app/emms/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::app emms][Issues]]  ↖ [[doom-repo:tree/develop/modules/app/emms/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :app emms
 #+subtitle: A media player for music no one's heard of
 #+created:  March 06, 2021

modules/app/everywhere/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::app everywhere][Issues]]  ↖ [[doom-repo:tree/develop/modules/app/everywhere/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :app everywhere
 #+subtitle: *leave* Emacs!? You must be joking
 #+created:  February 07, 2021

modules/app/irc/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::app irc][Issues]]  ↖ [[doom-repo:tree/develop/modules/app/irc/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :app irc
 #+subtitle: How neckbeards socialize
 #+created:  June 11, 2017

modules/app/rss/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::app rss][Issues]]  ↖ [[doom-repo:tree/develop/modules/app/rss/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :app rss
 #+subtitle: An RSS reader that Google can't shut down
 #+created:  May 12, 2020

modules/app/twitter/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::app twitter][Issues]]  ↖ [[doom-repo:tree/develop/modules/app/twitter/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :app twitter
 #+subtitle: Be superficial in plain text
 #+created:  October 11, 2019

modules/checkers/README.org

@@ -1,8 +1,9 @@
-← [[doom-module-index:][Back to module index]]                         ↖ [[doom-repo:tree/develop/modules/checkers/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:   :checkers
 #+created: August 01, 2021
 #+since:   21.12.0
 
 * Description
 For modules dedicated to linting plain text (primarily code and prose).
+
+* Frequently asked questions
+/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

modules/checkers/grammar/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::checkers grammar][Issues]]  ↖ [[doom-repo:tree/develop/modules/checkers/grammar/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :checkers grammar
 #+subtitle: Tasing grammar mistake every you make
 #+created:  January 09, 2020

modules/checkers/spell/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::checkers spell][Issues]]  ↖ [[doom-repo:tree/develop/modules/checkers/spell/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :checkers spell
 #+subtitle: Tasing you for misspelling mispelling
 #+created:  February 20, 2017

modules/checkers/syntax/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::checkers syntax][Issues]]  ↖ [[doom-repo:tree/develop/modules/checkers/syntax/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :checkers syntax
 #+subtitle: Tasing you for every semicolon you forget
 #+created:  February 20, 2017

modules/completion/README.org

@@ -1,12 +1,11 @@
-← [[doom-module-index:][Back to module index]]                         ↖ [[doom-repo:tree/develop/modules/completion/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:   :completion
 #+created: July 29, 2021
 #+since:   21.12.0
 
 * Description
 These modules provide interfaces and frameworks completion, including code
 completion.
+
 * Frequently asked questions
 ** Should I choose Ivy, Helm, Vertico, or Ido?
 :PROPERTIES:

modules/completion/company/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::completion company][Issues]]  ↖ [[doom-repo:tree/develop/modules/completion/company/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :completion company
 #+subtitle: The ultimate code completion backend
 #+created:  February 19, 2017
@@ -15,6 +13,7 @@ https://assets.doomemacs.org/completion/company/overlay.png
 - [[doom-user:][@hlissner]]
 
 [[doom-contrib-maintainer:][Become a maintainer?]]
+
 ** Module flags
 - +childframe ::
   Display completion candidates in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an overlay or

modules/completion/helm/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::completion helm][Issues]]  ↖ [[doom-repo:tree/develop/modules/completion/helm/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :completion helm
 #+subtitle: A tank for hunting a house fly
 #+created:  February 20, 2017

modules/completion/ido/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::completion ido][Issues]]  ↖ [[doom-repo:tree/develop/modules/completion/ido/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :completion ido
 #+subtitle: A foil for other search engines
 #+created:  February 20, 2017

modules/completion/ivy/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::completion ivy][Issues]]  ↖ [[doom-repo:tree/develop/modules/completion/ivy/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :completion ivy
 #+subtitle: Yesterday's lightest search engine
 #+created:  February 20, 2017

modules/completion/vertico/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::completion vertico][Issues]]  ↖ [[doom-repo:tree/develop/modules/completion/vertico/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :completion vertico
 #+subtitle: Tomorrow's search engine
 #+created:  July 25, 2021

modules/config/README.org

@@ -1,9 +1,10 @@
-← [[doom-module-index:][Back to module index]]                         ↖ [[doom-repo:tree/develop/modules/config/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:   :config
 #+created: July 29, 2021
 #+since:   21.12.0
 
 * Description
 Modules in this category provide sane defaults or improve your ability to
 configure Emacs. It is best to load these last.
+
+* Frequently asked questions
+/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

modules/config/default/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::config default][Issues]]  ↖ [[doom-repo:tree/develop/modules/config/default/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :config default
 #+subtitle: Reasonable defaults for reasonable people
 #+created:  February 14, 2018

modules/config/literate/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::config literate][Issues]]  ↖ [[doom-repo:tree/develop/modules/config/literate/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :config literate
 #+subtitle: Disguise your config as poor documentation
 #+created:  May 28, 2020

modules/editor/README.org

@@ -1,8 +1,9 @@
-← [[doom-module-index:][Back to module index]]                         ↖ [[doom-repo:tree/develop/modules/editor/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:   :editor
 #+created: July 30, 2021
 #+since:   21.12.0
 
 * Description
 For modules concerned with the insertion and editing of text. Amen.
+
+* Frequently asked questions
+/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

modules/editor/evil/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::editor evil][Issues]]  ↖ [[doom-repo:tree/develop/modules/editor/evil/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :editor evil
 #+subtitle: The text editor Emacs was missing
 #+created:  April 08, 2020
@@ -202,6 +200,27 @@ If you prefer the old behavior, it can be reversed with:
 Evil-specific configuration and keybindings (defined with ~map!~) will be
 ignored without [[doom-module:][:editor evil]] present (and omitted when byte-compiling).
 
+** Include underscores in evil word motions?
+A more in-depth answer and explanation for this can be found [[https://evil.readthedocs.io/en/latest/faq.html#underscore-is-not-a-word-character][in Evil's
+documentation]].
+
+TL;DR If you want the underscore to be recognized as word character, you can
+modify its entry in the syntax-table:
+#+begin_src emacs-lisp
+(modify-syntax-entry ?_ "w")
+#+end_src
+
+This gives the underscore the word syntax-class. You can use a mode-hook to
+modify the syntax-table in all buffers of some mode, e.g.
+#+begin_src emacs-lisp
+;; For python
+(add-hook! 'python-mode-hook (modify-syntax-entry ?_ "w"))
+;; For ruby
+(add-hook! 'ruby-mode-hook (modify-syntax-entry ?_ "w"))
+;; For Javascript
+(add-hook! 'js2-mode-hook (modify-syntax-entry ?_ "w"))
+#+end_src
+
 * TODO Appendix
 #+begin_quote
  🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]

modules/editor/file-templates/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::editor file-templates][Issues]]  ↖ [[doom-repo:tree/develop/modules/editor/file-templates/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :editor file-templates
 #+subtitle: Fill the void in your empty files
 #+created:  February 11, 2017

modules/editor/file-templates/templates/org-mode/__doom-category-readme

@@ -1,8 +1,6 @@
 # -*- mode: snippet -*-
 # name: Doom category readme
 # --
-← [[doom-module-index:][Back to module index]]                         ↖ [[doom-module-source:lang][Source]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:   `(+file-templates-module-for-path)`
 #+created: `(format-time-string "%B %d, %Y")`
 #+since:   `(car (split-string doom-version "-"))`

modules/editor/file-templates/templates/org-mode/__doom-docs

@@ -1,9 +1,7 @@
 # -*- mode: snippet -*-
 # name: Doom documentation
 # --
-← [[doom-index:][Back to index]]                                ↖ [[doom-docs-source:faq.org][Source]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help:][Help]]
---------------------------------------------------------------------------------
-#+title:     ${1:Title}
-#+subtitle:  ${2:Subtitle}
+#+title:    ${1:Title}
+#+subtitle: ${2:Subtitle}
 
 $0

modules/editor/file-templates/templates/org-mode/__doom-readme

@@ -1,8 +1,6 @@
 # -*- mode: snippet -*-
 # name: Doom module readme                                             
 # --
-← [[doom-module-index:][Back to module index]]               ↙ [[doom-module-issues:::lang rust][Issues]]  ↖ [[doom-module-source:lang/rust][Source]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:     `(+file-templates-module-for-path)`
 #+subtitle:  <A one-line quip about this module to display in init.example.el>
 #+created:   `(format-time-string "%B %d, %Y")`

modules/editor/fold/README.org

@@ -1,5 +1,3 @@
-← [[doom-module-index:][Back to module index]]               ! [[doom-module-issues:::editor fold][Issues]]  ↖ [[doom-repo:tree/develop/modules/editor/fold/][Github]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
---------------------------------------------------------------------------------
 #+title:    :editor fold
 #+subtitle: What you can't see won't hurt you
 #+created:  May 15, 2019