mirror of
https://github.com/jrnl-org/jrnl.git
synced 2025-05-10 00:28:31 +02:00
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
This commit is contained in:
Micah Jerome Ellison
GitHub
parent
967ec86d9d
commit
972af21bca
9 changed files with 426 additions and 222 deletions
150
docs/advanced.md
150
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`.
|
||||
`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.
|
||||
|
||||
!!! 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
|
||||
```
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
95
docs/external-editors.md
Normal file
95
docs/external-editors.md
Normal file
|
|
@ -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.
|
||||
128
docs/reference-command-line.md
Normal file
128
docs/reference-command-line.md
Normal file
|
|
@ -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).
|
||||
117
docs/reference-config-file.md
Normal file
117
docs/reference-config-file.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
template file's path in double quotes:
|
||||
in your [config file](./reference-config-file.md) by changing the `template`
|
||||
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.
|
||||
|
|
@ -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
|
||||
file. To use tags, preface the desired tag with the symbol:
|
||||
reserved character). You can specify your own tag symbol in the
|
||||
[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
|
||||
that match specific search criteria. For example,
|
||||
editor configured in your [configuration file](./reference-config-file.md#editor). You
|
||||
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
|
||||
file.
|
||||
The journals displayed correspond to those specified in the `jrnl`
|
||||
[configuration file](./reference-config-file.md#journals).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue