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

docs/advanced.md

@@ -5,109 +5,15 @@
 
 ## Configuration File
 
-You can configure the way jrnl behaves in a configuration file. By
-default, this 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`.
-
-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
-```
+`jrnl` has a wide variety of options that can be customized through the config file,
+including templates, formats, multiple journals, and more. See
+the [configuration file reference](./reference-config-file.md) for details
+or read on for some common use cases.
 
-
-## Multiple journal files
+### 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
-    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.
+    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 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.