Add reference documentation to docs site and separate out "Tips and Tricks" and "External Editors" from "Recipes" (#1332)

* First draft of command line reference, mostly pulled from help screen

* Add first draft of config file reference, mostly pulled from advanced.md

* Clean up config file doc for readability

* Add --config-file and remove examples from CLI reference

* Add warning about time zone in timeformat

* More small changes, and adding template config keyword

* Cleaning up and re-ordering config file reference

* Clean up reference and anything else from advanced documentation that can live elsewhere and linking to config file reference wherever config file is mentioned

* Fix syntax highlighting in command line reference, clean up content a bit, include --diagnostic

* Mention version config key

* Apply minor changes suggested in PR review

* Rename "recipes" to "Tips and Tricks", pull "External Editors" out of it into its own page, and redirect old recipes link to tips-and-tricks

* Revert broken mkdocs-redirects usage from last commit

docs/advanced.md

@@ -5,109 +5,15 @@
 
 ## Configuration File
 
-You can configure the way jrnl behaves in a configuration file. By
+`jrnl` has a wide variety of options that can be customized through the config file,
-default, this is `~/.config/jrnl/jrnl.yaml`. If you have the `XDG_CONFIG_HOME`
+including templates, formats, multiple journals, and more. See
-variable set, the configuration file will be saved as
+the [configuration file reference](./reference-config-file.md) for details
-`$XDG_CONFIG_HOME/jrnl/jrnl.yaml`.
+or read on for some common use cases.
 
-!!! note
+### Multiple journal files
-    On Windows, the configuration file is typically found at `%USERPROFILE%\.config\jrnl\jrnl.yaml`.
-
-The configuration file is a YAML file with the following options
-and can be edited with a plain text editor.
-
-!!! note
-    Backup your journal and config file before editing. Changes to the config file
-    can have destructive effects on your journal!
-
-- `journals`
-    paths to your journal files
-- `editor`
-    if set, executes this command to launch an external editor for
-    writing your entries, e.g. `vim`. Some editors require special
-    options to work properly, see `FAQ <recipes>` for details.
-- `encrypt`
-    if `true`, encrypts your journal using AES.
-- `tagsymbols`
-    Symbols to be interpreted as tags. (See note below)
-- `default_hour` and `default_minute`
-    if you supply a date, such as `last thursday`, but no specific
-    time, the entry will be created at this time
-- `timeformat`
-    how to format the timestamps in your journal, see the [python docs](http://docs.python.org/library/time.html#time.strftime) for reference
-- `highlight`
-    if `true`, tags will be highlighted in cyan.
-- `linewrap`
-    controls the width of the output. Set to `false` if you don't want to wrap long lines.
-- `colors`
-    dictionary that controls the colors used to display journal entries. It has four subkeys, which are: `body`, `date`, `tags`, and `title`. Current valid values are: `BLACK`, `RED`, `GREEN`, `YELLOW`, `BLUE`, `MAGENTA`, `CYAN`, `WHITE`, and `NONE`. `colorama.Fore` is used for colorization, and you can find the [docs here](https://github.com/tartley/colorama#colored-output). To disable colored output, set the value to `NONE`. If you set the value of any color subkey to an invalid color, no color will be used.
-- `display_format`
-    specifies formatter to use, formatters available are:
-    `boxed`, `fancy`, `json`, `markdown`, `md`, `tags`, `text`, `txt`, `xml`, or `yaml`.
-
-!!! note
-    Although it seems intuitive to use the `#`
-    character for tags, there's a drawback: on most shells, this is
-    interpreted as a meta-character starting a comment. This means that if
-    you type
-
-    > `jrnl Implemented endless scrolling on the #frontend of our website.`
-
-    your bash will chop off everything after the `#` before passing it to
-      `jrnl`. To avoid this, wrap your input into quotation marks like
-      this:
-
-    > `jrnl "Implemented endless scrolling on the #frontend of our website."`
-
-  Or use the built-in prompt or an external editor to compose your
-  entries.
-
-### Modifying Configurations from the Command line 
-
-You can override a configuration field for the current instance of `jrnl` using `--config-override CONFIG_KEY CONFIG_VALUE` where `CONFIG_KEY` is a valid configuration field, specified in dot-notation and `CONFIG_VALUE` is the (valid) desired override value.
-
-You can specify multiple overrides as multiple calls to `--config-override`.
-!!! note
-    These overrides allow you to modify ***any*** field of your jrnl configuration. We trust that you know what you are doing. 
-
-#### Examples: 
-
-``` sh
-#Create an entry using the `stdin` prompt, for rapid logging
-jrnl --config-override editor ""
-
-#Populate a project's log
-jrnl --config-override journals.todo "$(git rev-parse --show-toplevel)/todo.txt" todo find my towel 
-
-#Pass multiple overrides 
-jrnl --config-override display_format fancy --config-override linewrap 20 \
---config-override colors.title green
-
-```
-
-### Using an alternate config
-
-You can specify an alternate configuration file for the current instance of `jrnl` using `--config-file CONFIG_FILE_PATH` where
-`CONFIG_FILE_PATH` is a path to an alternate `jrnl` configuration file. 
-
-#### Examples:
-
-```
-# Use personalised configuration file for personal journal entries
-jrnl --config-file ~/foo/jrnl/personal-config.yaml
-
-# Use alternate configuration file for work-related entries
-jrnl --config-file ~/foo/jrnl/work-config.yaml
-
-# Use default configuration file (created on installation)
-jrnl
-```
-
-
-## Multiple journal files
 
 You can configure `jrnl`to use with multiple journals (eg.
-`private` and `work`) by defining more journals in your `jrnl.yaml`,
+`private` and `work`) by defining more journals in your [config file](./reference-config-file.md),
 for example:
 
 ``` yaml
@@ -167,12 +73,46 @@ journals:
 
 The `work` journal is encrypted, prints to `json` by default, and is edited using an existing window of VSCode. Similarly, the `food` journal prints to markdown by default, but uses all the other defaults.
 
+### Modifying Configurations from the Command line 
+
+You can override a configuration field for the current instance of `jrnl` using `--config-override CONFIG_KEY CONFIG_VALUE` where `CONFIG_KEY` is a valid configuration field, specified in dot notation and `CONFIG_VALUE` is the (valid) desired override value. The dot notation can be used to change config keys within other keys, such as `colors.title` for the `title` key within the `colors` key.
+
+You can specify multiple overrides as multiple calls to `--config-override`.
 !!! note
-    Changing `encrypt` to a different value will not encrypt or decrypt your
+    These overrides allow you to modify ***any*** field of your jrnl configuration. We trust that you know what you are doing. 
-    journal file, it merely says whether or not your journal
+
-    is encrypted. Hence manually changing
+#### Examples: 
-    this option will most likely result in your journal file being
+
-    impossible to load.
+``` sh
+#Create an entry using the `stdin` prompt, for rapid logging
+jrnl --config-override editor ""
+
+#Populate a project's log
+jrnl --config-override journals.todo "$(git rev-parse --show-toplevel)/todo.txt" todo find my towel 
+
+#Pass multiple overrides 
+jrnl --config-override display_format fancy --config-override linewrap 20 \
+--config-override colors.title green
+
+```
+
+### Using an alternate config
+
+You can specify an alternate configuration file for the current instance of `jrnl` using `--config-file CONFIG_FILE_PATH` where
+`CONFIG_FILE_PATH` is a path to an alternate `jrnl` configuration file. 
+
+#### Examples:
+
+```
+# Use personalised configuration file for personal journal entries
+jrnl --config-file ~/foo/jrnl/personal-config.yaml
+
+# Use alternate configuration file for work-related entries
+jrnl --config-file ~/foo/jrnl/work-config.yaml
+
+# Use default configuration file (created on first run)
+jrnl
+```
 
 ## Known Issues
 

docs/contributing.md

@@ -28,9 +28,9 @@ To edit the documentation, edit the `docs/*.md` files on the **develop** branch.
 
 The `gh-pages` branch is automatically maintained and generated after your changes are merged. You should never have to edit that branch.
 
-### Recipes and external editors
+### External editors and tips and tricks
 
-If you'd like to share a jrnl command line trick that you find useful, or advice on how to integrate a particular external editor, you may find it worthwhile to add it to the ["Recipes" section](recipes.md).
+If you'd like to share a jrnl command line trick that you find useful, you may find it worthwhile to add it to the ["Tips and Tricks" section](tips-and-tricks.md). For advice on how to integrate a particular external editor, you can add to the ["External Editors" section](external-editors.md).
 
 ## Testing
 

docs/encryption.md

@@ -35,6 +35,14 @@ replaces the encrypted journal file with a plain text file. You can also specify
 a filename, e.g., `jrnl --decrypt plain_text_copy.txt`, to leave the original
 encrypted file untouched and create a new plain text file next to it.
 
+!!! note
+    Changing `encrypt` in your [config file](./reference-config-file.md) to
+    a different value will not encrypt or decrypt your
+    journal file. It merely says whether or not your journal
+    is encrypted. Hence manually changing
+    this option will most likely result in your journal file being
+    impossible to load. This is why the above commands are necessary.
+
 ## Storing Passwords in Your Keychain
 
 Nobody can recover or reset your `jrnl` password. If you lose it,

docs/external-editors.md

@@ -0,0 +1,95 @@
+# External editors
+
+Configure your preferred external editor by updating the `editor` option
+in your [configuration file](./reference-config-file.md#editor)
+
+!!! note
+    To save and log any entry edits, save and close the file.
+
+If your editor is not in your operating system's `PATH` environment variable,
+then you will have to enter in the full path of your editor.
+
+## Sublime Text
+
+To use [Sublime Text](https://www.sublimetext.com/), install the command line
+tools for Sublime Text and configure your `jrnl.yaml` like this:
+
+```yaml
+editor: "subl -w"
+```
+
+Note the `-w` flag to make sure `jrnl` waits for Sublime Text to close the
+file before writing into the journal.
+
+## Visual Studio Code
+
+[Visual Studio Code](https://code.visualstudio.com) also requires a flag
+that tells the process to wait until the file is closed before exiting:
+
+```yaml
+editor: "code --wait"
+```
+
+On Windows, `code` is not added to the path by default, so you'll need to
+enter the full path to your `code.exe` file, or add it to the `PATH` variable.
+
+## MacVim
+
+Also similar to Sublime Text, MacVim must be started with a flag that tells
+the the process to wait until the file is closed before passing control
+back to journal. In the case of MacVim, this is `-f`:
+
+```yaml
+editor: "mvim -f"
+```
+
+## iA Writer
+
+On OS X, you can use the fabulous [iA
+Writer](http://www.iawriter.com/mac) to write entries. Configure your
+`jrnl.yaml` like this:
+
+```yaml
+editor: "open -b pro.writer.mac -Wn"
+```
+
+What does this do? `open -b ...` opens a file using the application
+identified by the bundle identifier (a unique string for every app out
+there). `-Wn` tells the application to wait until it's closed before
+passing back control, and to use a new instance of the application.
+
+If the `pro.writer.mac` bundle identifier is not found on your system,
+you can find the right string to use by inspecting iA Writer's
+`Info.plist` file in your shell:
+
+```sh
+grep -A 1 CFBundleIdentifier /Applications/iA\ Writer.app/Contents/Info.plist
+```
+
+## Notepad++ on Windows
+
+To set [Notepad++](http://notepad-plus-plus.org/) as your editor, edit
+the `jrnl` config file (`jrnl.yaml`) like this:
+
+```yaml
+editor: "C:\\Program Files (x86)\\Notepad++\\notepad++.exe -multiInst -nosession"
+```
+
+The double backslashes are needed so `jrnl` can read the file path
+correctly. The `-multiInst -nosession` options will cause `jrnl` to open
+its own Notepad++ window.
+
+
+## emacs
+
+To use `emacs` as your editor, edit the `jrnl` config file (`jrnl.yaml`) like this:
+
+```yaml
+editor: emacsclient -a "" -c
+```
+
+When you're done editing the message, save and `C-x #` to close the buffer and stop the emacsclient process.
+
+## Other editors
+
+If you're using another editor and would like to share, feel free to [contribute documentation](./contributing.md#editing-documentation) on it.

docs/reference-command-line.md

@@ -0,0 +1,128 @@
+# Command Line Reference
+
+## Synopsis
+```
+usage: jrnl [--debug] [--help] [--version] [--list] [--encrypt] [--decrypt]
+            [--import] [-on DATE] [-today-in-history] [-month DATE]
+            [-day DATE] [-year DATE] [-from DATE] [-to DATE] [-contains TEXT]
+            [-and] [-starred] [-n [NUMBER]] [-not [TAG]] [--edit] [--delete]
+            [--format TYPE] [--tags] [--short]
+            [--config-override CONFIG_KEY CONFIG_VALUE]
+            [--config-file CONFIG_FILE_PATH]
+            [[...]]
+```
+
+## Standalone Commands
+
+These commands will exit after they complete. You may only run one at a time.
+
+### --help
+Show a help message.
+
+### --version
+Print version and license information.
+
+### --list
+List the config file location, all configured journals, and their locations.
+
+### ---encrypt
+Encrypt a journal. See [encryption](encryption.md) for more information.
+
+### --decrypt
+Decrypt a journal. See [encryption](encryption.md) for more information.
+
+
+### --import
+Import entries from another journal. If any entries have the exact same content
+and timestamp, they will be deduplicated.
+
+Optional parameters:
+```sh
+--file FILENAME
+```
+Specify a file to import. If not provided, `jrnl` will use STDIN as the data source.
+
+```sh
+--format TYPE
+```
+Specify the format of the file that is being imported. Defaults to the same data
+storage method that jrnl uses. See [formats](formats.md) for more information.
+
+## Writing new entries
+See [Basic Usage](usage.md).
+
+## Searching
+
+To find entries from your journal, use any combination of the below filters.
+Only entries that match all the filters will be displayed.
+
+When specifying dates, you can use the same kinds of dates you use for new
+entries, such as `yesterday`, `today`, `Tuesday`, or `2021-08-01`.
+
+| Search Argument | Description |
+| --- | --- |
+| -on DATE | Show entries on this date |
+| -today-in-history | Show entries of today over the years |
+| -month DATE | Show entries on this month of any year |
+| -day DATE | Show entries on this day of any month |
+| -year DATE | Show entries of a specific year |
+| -from DATE | Show entries after, or on, this date |
+| -to DATE | Show entries before, or on, this date (alias: -until) |
+| -contains TEXT | Show entries containing specific text (put quotes around text with spaces) |
+| -and | Show only entries that match all conditions, like saying "x AND y" (default: OR) |
+| -starred | Show only starred entries (marked with *) |
+| -n [NUMBER] | Show a maximum of NUMBER entries (note: '-n 3' and '-3' have the same effect) |
+| -not [TAG] | Exclude entries with this tag |
+
+## Searching Options
+These help you do various tasks with the selected entries from your search.
+If used on their own (with no search), they will act on your entire journal.
+
+### --edit
+Opens the selected entries in your configured editor. It will fail if the
+`editor` key is not set in your config file.
+
+Once you begin editing, you can add multiple entries and delete entries
+by modifying the text in your editor. When your editor closes, jrnl reads
+the temporary file you were editing and makes the changes to your journal.
+
+### --delete
+Interactively deletes selected entries. You'll be asked to confirm deletion of
+each entry.
+
+### --format TYPE
+Display selected entries in an alternate format. See [formats](formats.md).
+
+#### Optional parameters
+```sh
+--file FILENAME
+```
+Write output to file instead of STDOUT. In most shells, the
+same effect can be achieved using `>`.
+
+### --tags
+
+Alias for '--format tags'. Returns a list of all tags and the number of times
+they occur within the searched entries. If there are no tags found, `jrnl` will output a message saying so.
+
+### --short
+Only shows the date and titles of the searched entries.
+
+## Configuration arguments
+
+### --config-override CONFIG_KEY CONFIG_VALUE
+
+Override configured key-value pair with CONFIG_KV_PAIR for this command invocation only. To access config keys that aren't at the top level, separate the keys with a dot, such as `colors.title` to access the `title` key within the `colors` key. Read [advanced usage](./advanced.md) for examples.
+
+### --config-file CONFIG_FILE_PATH
+
+Use the config file at CONFIG_FILE_PATH for this command invocation only.
+Read [advanced usage](./advanced.md) for examples.
+
+## Other Arguments
+
+### --debug
+Prints information useful for troubleshooting while `jrnl` executes.
+
+### --diagnostic
+Prints diagnostic information useful for [reporting issues](https://github.com/jrnl-org/jrnl/issues).

docs/reference-config-file.md

@@ -0,0 +1,117 @@
+# Configuration File Reference
+
+`jrnl` stores its information in a YAML configuration file.
+
+!!! note
+    Backup your journal and config file before editing. Changes to the config file
+    can have destructive effects on your journal!
+
+## Config location
+You can find your configuration file location by running:
+`jrnl --list`
+
+By default, the configuration file is `~/.config/jrnl/jrnl.yaml`.
+If you have the `XDG_CONFIG_HOME` variable set, the configuration
+file will be saved as `$XDG_CONFIG_HOME/jrnl/jrnl.yaml`.
+
+!!! note
+    On Windows, the configuration file is typically found at
+    `%USERPROFILE%\.config\jrnl\jrnl.yaml`.
+
+
+## Config format
+The configuration file is a [YAML](https://yaml.org/) file and can be edited with
+a text editor.
+
+## Config keys
+
+### journals
+
+Describes each journal used by `jrnl`. Each indented key after this key is
+the name of a journal.
+
+If a journal key has a value, that value will be interpreted as the path
+to the journal. Otherwise, the journal needs the additional indented key
+`journal` to specify its path.
+
+All keys below can be specified for each journal at the same level as the
+`journal` key. If a key conflicts with a top-level key, the journal-specific
+key will be used instead.
+
+### editor
+If set, executes this command to launch an external editor for
+writing and editing your entries. The path to a temporary file
+is passed after it, and `jrnl` processes the file once
+the editor is closed.
+
+Some editors require special options to work properly. See
+[External Editors](external-editors.md) for details.
+
+### encrypt
+If `true`, encrypts your journal using AES. Do not change this
+value for journals that already have data in them.
+
+### template
+The path to a text file to use as a template for new entries. Only works when you
+have the `editor` field configured.
+
+### tagsymbols
+Symbols to be interpreted as tags.
+
+!!! note
+    Although it seems intuitive to use the `#`
+    character for tags, there's a drawback: on most shells, this is
+    interpreted as a meta-character starting a comment. This means that if
+    you type
+
+    > `jrnl Implemented endless scrolling on the #frontend of our website.`
+
+    your bash will chop off everything after the `#` before passing it to
+      `jrnl`. To avoid this, wrap your input into quotation marks like
+      this:
+
+    > `jrnl "Implemented endless scrolling on the #frontend of our website."`
+
+  Or use the built-in prompt or an external editor to compose your
+  entries.
+
+### default_hour and default_minute
+Entries will be created at this time if you supply a date but no specific time (for example, `last thursday`).
+
+### timeformat
+Defines how to format the timestamps as they are stored in your journal.
+See the [python docs](http://docs.python.org/library/time.html#time.strftime) for reference.
+
+Do not change this for an existing journal, since that might lead
+to data loss.
+
+If you would just like to change how `jrnl` displays dates,
+use display_format instead.
+
+!!! note
+    `jrnl` doesn't support the `%z` or `%Z` time zone identifiers.
+
+### highlight
+If `true`, tags will be highlighted in cyan.
+
+### linewrap
+Controls the width of the output. Set to `false` if you don't want to
+wrap long lines.
+
+### colors
+A dictionary that controls the colors used to display journal entries.
+It has four subkeys, which are: `body`, `date`, `tags`, and `title`.
+
+Current valid values are: `BLACK`, `RED`, `GREEN`, `YELLOW`, `BLUE`,
+`MAGENTA`, `CYAN`, `WHITE`, and `NONE`.
+
+`colorama.Fore` is used for colorization, and you can find the [docs here](https://github.com/tartley/colorama#colored-output).
+
+To disable colored output, set the value to `NONE`.
+
+### display_format
+Specifies formatter to use by default. See [formats](formats.md).
+
+### version
+`jrnl` automatically updates this field to the version that it is running.
+There is no need to change this field manually.

docs/tips-and-tricks.md

@@ -1,10 +1,11 @@
 <!-- Copyright (C) 2012-2021 jrnl contributors
      License: https://www.gnu.org/licenses/gpl-3.0.html -->
-# FAQ
+# Tips and Tricks
 
-## Recipes
+This page contains tips and tricks for using `jrnl`, often in conjunction
+with other tools, including external editors.
 
-### Co-occurrence of tags
+## Co-occurrence of tags
 
 If I want to find out how often I mentioned my flatmates Alberto and
 Melo in the same entry, I run
@@ -20,7 +21,7 @@ tag `@alberto`, and then the `--tags` option will print out how often
 each tag occurred in this filtered journal. Finally, we pipe this to
 `grep` which will only display the line containing `@melo`.
 
-### Combining filters
+## Combining filters
 
 You can do things like
 
@@ -31,7 +32,7 @@ jrnl @fixed -starred -n 10 -to "jan 2013" --short
 To get a short summary of the 10 most recent, favourite entries before
 January 1, 2013 that are tagged with `@fixed`.
 
-### Statistics
+## Statistics
 
 How much did I write last year?
 
@@ -50,7 +51,7 @@ This will first get the total number of words in the journal and divide
 it by the number of entries (this works because `jrnl --short` will
 print exactly one line per entry).
 
-### Importing older files
+## Importing older files
 
 If you want to import a file as an entry to `jrnl`, you can just do `jrnl < entry.ext`. But what if you want the modification date of the file to
 be the date of the entry in `jrnl`? Try this
@@ -70,7 +71,7 @@ jrnlimport () {
 }
 ```
 
-### Using templates
+## Using templates
 
 !!! note
     Templates require an [external editor](./advanced.md) be configured.
@@ -79,7 +80,7 @@ A template is a code snippet that makes it easier to use repeated text
 each time a new journal entry is started. There are two ways you can utilize
 templates in your entries.
 
-#### 1. Command line arguments
+### 1. Command line arguments
 
 If you had a `template.txt` file with the following contents:
 
@@ -98,11 +99,11 @@ jrnl < template.txt     # Imports template.txt as the most recent entry
 jrnl -1 --edit          # Opens the most recent entry in the editor
 ```
 
-#### 2. Include the template file in `jrnl.yaml`
+### 2. Include the template file in `jrnl.yaml`
 
 A more efficient way to work with a template file is to declare the file
-in your config file by changing the `template` setting from `false` to the
+in your [config file](./reference-config-file.md) by changing the `template`
-template file's path in double quotes:
+setting from `false` to the template file's path in double quotes:
 
 ```sh
 ...
@@ -121,7 +122,7 @@ logged as a new entry in the journal you specified in the original argument.
 jrnl -n 1
 ```
 
-### Prompts on shell reload
+## Prompts on shell reload
 
 If you'd like to be prompted each time you refresh your shell, you can include
 this in your `.bash_profile`:
@@ -142,7 +143,7 @@ questions in the example above. Each answer will be logged as a separate
 journal entry at the `default_hour` and `default_minute` listed in your
 `jrnl.yaml` [config file](../advanced/#configuration-file).
 
-### Display random entry
+## Display random entry
 
 You can use this to select one title at random and then display the whole
 entry. The invocation of `cut` needs to match the format of the timestamp.
@@ -155,7 +156,7 @@ jrnl -on "$(jrnl --short | shuf -n 1 | cut -d' ' -f1,2)"
 ```
 
 
-### Launch a terminal for rapid logging
+## Launch a terminal for rapid logging
 You can use this to launch a terminal that is the `jrnl` stdin prompt so you can start typing away immediately.
 
 ```bash
@@ -180,7 +181,7 @@ Mod4+Mod1+j
 bindsym Mod4+Mod1+j exec --no-startup-id alacritty -t floating-jrnl -e jrnl --config-override editor ""
 for_window[title="floating *"] floating enable
 ```
-### Visualize Formatted Markdown in the CLI
+## Visualize Formatted Markdown in the CLI
 
 Out of the box, `jrnl` can output journal entries in Markdown. To visualize it, you can pipe to [mdless](https://github.com/ttscoff/mdless), which is a [less](https://en.wikipedia.org/wiki/Less_(Unix))-like tool that allows you to visualize your Markdown text with formatting and syntax highlighting from the CLI. You can use this in any shell that supports piping.
 
@@ -207,94 +208,3 @@ display_format: markdown
 
 For more information on how `jrnl` outputs your entries in Markdown, please visit the [Formats](./formats.md) section.
 
-## External editors
-
-Configure your preferred external editor by updating the `editor` option
-in your `jrnl.yaml` file. (See [advanced usage](./advanced.md) for details).
-
-!!! note
-    To save and log any entry edits, save and close the file.
-
-If your editor is not in your operating system's `PATH` environment variable,
-then you will have to enter in the full path of your editor.
-
-### Sublime Text
-
-To use [Sublime Text](https://www.sublimetext.com/), install the command line
-tools for Sublime Text and configure your `jrnl.yaml` like this:
-
-```yaml
-editor: "subl -w"
-```
-
-Note the `-w` flag to make sure `jrnl` waits for Sublime Text to close the
-file before writing into the journal.
-
-### Visual Studio Code
-
-[Visual Studio Code](https://code.visualstudio.com) also requires a flag
-that tells the process to wait until the file is closed before exiting:
-
-```yaml
-editor: "code --wait"
-```
-
-On Windows, `code` is not added to the path by default, so you'll need to
-enter the full path to your `code.exe` file, or add it to the `PATH` variable.
-
-### MacVim
-
-Also similar to Sublime Text, MacVim must be started with a flag that tells
-the the process to wait until the file is closed before passing control
-back to journal. In the case of MacVim, this is `-f`:
-
-```yaml
-editor: "mvim -f"
-```
-
-### iA Writer
-
-On OS X, you can use the fabulous [iA
-Writer](http://www.iawriter.com/mac) to write entries. Configure your
-`jrnl.yaml` like this:
-
-```yaml
-editor: "open -b pro.writer.mac -Wn"
-```
-
-What does this do? `open -b ...` opens a file using the application
-identified by the bundle identifier (a unique string for every app out
-there). `-Wn` tells the application to wait until it's closed before
-passing back control, and to use a new instance of the application.
-
-If the `pro.writer.mac` bundle identifier is not found on your system,
-you can find the right string to use by inspecting iA Writer's
-`Info.plist` file in your shell:
-
-```sh
-grep -A 1 CFBundleIdentifier /Applications/iA\ Writer.app/Contents/Info.plist
-```
-
-### Notepad++ on Windows
-
-To set [Notepad++](http://notepad-plus-plus.org/) as your editor, edit
-the `jrnl` config file (`jrnl.yaml`) like this:
-
-```yaml
-editor: "C:\\Program Files (x86)\\Notepad++\\notepad++.exe -multiInst -nosession"
-```
-
-The double backslashes are needed so `jrnl` can read the file path
-correctly. The `-multiInst -nosession` options will cause `jrnl` to open
-its own Notepad++ window.
-
-
-### emacs
-
-To use `emacs` as your editor, edit the `jrnl` config file (`jrnl.yaml`) like this:
-
-```yaml
-editor: emacsclient -a "" -c
-```
-
-When you're done editing the message, save and `C-x #` to close the buffer and stop the emacsclient process.

docs/usage.md

@@ -55,14 +55,15 @@ If you don't specify a date and time (e.g., `jrnl finished writing letter to bro
 
 If you don't use a timestamp, `jrnl` will create an entry using the current
 time. If you use a date only (no time), `jrnl` will use the default time
-specified in your configuration file (see [advanced usage](./advanced.md)).
+specified in your [configuration file](./reference-config-file.md#default_hour-and-default_minute).
 Behind the scenes, `jrnl` reorganizes entries in chronological order.
 
 ### Using Tags ###
 
 `jrnl` supports tags. The default tag symbol is `@` (largely because `#` is a
-reserved character). You can specify your own tag symbol in the configuration
+reserved character). You can specify your own tag symbol in the
-file. To use tags, preface the desired tag with the symbol:
+[configuration file](./reference-config-file.md#tagsymbols). To use tags, preface the
+desired tag with the symbol:
 
 ```sh
 jrnl Had a wonderful day at the @beach with @Tom and @Anna.
@@ -157,7 +158,7 @@ jrnl -n 5 @pinkie -and @WorldDomination
 
 displays the last five entries containing _both_ `@pinkie` _and_
 `@worldDomination`. You can change which symbols you'd like to use for tagging
-in the configuration.
+in the [configuration file](./reference-config-file.md#tagsymbols).
 
 !!! note
     Entering `jrnl @pinkie @WorldDomination` will display entries in which both
@@ -183,8 +184,8 @@ jrnl -starred
 
 You can edit entries after writing them. This is particularly useful when your
 journal file is encrypted. To use this feature, you need to have an external
-editor configured in your configuration file. You can also edit only the entries
+editor configured in your [configuration file](./reference-config-file.md#editor). You
-that match specific search criteria. For example,
+can also edit only the entries that match specific search criteria. For example,
 
 ```sh
 jrnl -to 1950 @texas -and @history --edit
@@ -248,5 +249,5 @@ To list all of your journals:
 jrnl --list
 ```
 
-The journals displayed correspond to those specified in the `jrnl` configuration
+The journals displayed correspond to those specified in the `jrnl`
-file.
+[configuration file](./reference-config-file.md#journals).

mkdocs.yml

@@ -26,6 +26,11 @@ nav:
     - Privacy and Security: privacy-and-security.md
     - Formats: formats.md
     - Advanced Usage: advanced.md
-    - Recipes: recipes.md
+    - 'External Editors': external-editors.md
+    - 'Tips and Tricks': tips-and-tricks.md
+  - 'Reference':
+    - Command Line: reference-command-line.md
+    - Configuration File: reference-config-file.md
   - 'Contributing':
     - Contributing to jrnl: contributing.md
+