mirror of
https://github.com/jrnl-org/jrnl.git
synced 2025-07-03 23:16:14 +02:00
Clean up reference and anything else from advanced documentation that can live elsewhere and linking to config file reference wherever config file is mentioned
This commit is contained in:
Micah Jerome Ellison
parent
e856cc74b9
commit
b77a24bcf1
4 changed files with 68 additions and 116 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.
|
||||
|
||||
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 installation)
|
||||
jrnl
|
||||
```
|
||||
|
||||
## Known Issues
|
||||
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
<!-- Copyright (C) 2012-2021 jrnl contributors
|
||||
License: https://www.gnu.org/licenses/gpl-3.0.html -->
|
||||
# FAQ
|
||||
# Recipes
|
||||
|
||||
This page contains tips and tricks for using `jrnl`, often in conjunction
|
||||
with other tools, including external editors.
|
||||
|
||||
## Recipes
|
||||
|
||||
|
|
@ -101,8 +104,8 @@ jrnl -1 --edit # Opens the most recent entry in the editor
|
|||
#### 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
|
||||
...
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
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). 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).
|
||||
|
||||
!!! 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). 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).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue