fz0x1/jrnl
1
0
Fork 0
mirror of https://github.com/jrnl-org/jrnl.git synced 2025-07-04 07:26:14 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

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

Browse source
This commit is contained in:
Micah Jerome Ellison 2022-01-08 12:57:47 -08:00
parent e856cc74b9
commit b77a24bcf1
4 changed files with 68 additions and 116 deletions
Download patch file Download diff file Expand all files Collapse all files

150
docs/advanced.md
View file

@ -5,109 +5,15 @@
## Configuration File ## 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. 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: for example:
``` yaml ``` 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. 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 !!! 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 installation)
jrnl
```
## Known Issues ## Known Issues

8
docs/encryption.md
View file

@ -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 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. 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 ## Storing Passwords in Your Keychain
Nobody can recover or reset your `jrnl` password. If you lose it, Nobody can recover or reset your `jrnl` password. If you lose it,

9
docs/recipes.md
View file

@ -1,6 +1,9 @@
<!-- Copyright (C) 2012-2021 jrnl contributors <!-- Copyright (C) 2012-2021 jrnl contributors
License: https://www.gnu.org/licenses/gpl-3.0.html --> 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 ## Recipes
@ -101,8 +104,8 @@ 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 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 ```sh
... ...

17
docs/usage.md
View file

@ -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 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 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. Behind the scenes, `jrnl` reorganizes entries in chronological order.
### Using Tags ### ### Using Tags ###
`jrnl` supports tags. The default tag symbol is `@` (largely because `#` is a `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). To use tags, preface the
desired tag with the symbol:
```sh ```sh
jrnl Had a wonderful day at the @beach with @Tom and @Anna. 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_ displays the last five entries containing _both_ `@pinkie` _and_
`@worldDomination`. You can change which symbols you'd like to use for tagging `@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 !!! note
Entering `jrnl @pinkie @WorldDomination` will display entries in which both 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 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 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). You
that match specific search criteria. For example, can also edit only the entries that match specific search criteria. For example,
```sh ```sh
jrnl -to 1950 @texas -and @history --edit jrnl -to 1950 @texas -and @history --edit
@ -248,5 +249,5 @@ To list all of your journals:
jrnl --list 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).