diff --git a/.gitignore b/.gitignore index bb17779..b4afdb2 100644 --- a/.gitignore +++ b/.gitignore @@ -14,5 +14,4 @@ # Dependency directories (remove the comment below to include it) # vendor/ -# Documentation notebook marker -docs/.zk +.zk diff --git a/CHANGELOG.md b/CHANGELOG.md index bdff922..48e8c48 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,10 +8,14 @@ All notable changes to this project will be documented in this file. * Pair `--match` with `--exact-match` / `-e` to search for (case insensitive) exact occurrences in your notes. * This can be useful when looking for terms including special characters, such as `[[name]]`. +* Generating links to notes. + * Use the `{{link}}` template variable when [formatting notes](docs/template-format.md) to print a link to the note, relative to the working directory. + * Use the `{{format-link path title}}` template helper to render a custom link. + * Customize the link format from the [note formats settings](docs/note-format.md). You can for example choose regular Markdown links, Wiki-links or a custom format. ### Changed -* The local configuration is not required anymore in a notebook's `.zk` directory. +* The local configuration file (`.zk/config.toml`) is not required anymore in a notebook's `.zk` directory. * `--notebook-dir` does not change the working directory anymore, instead it sets manually the current notebook and disable auto-discovery. Use the new `--working-dir`/`-W` flag to run `zk` as if it was started from this path instead of the current working directory. * For convenience, `ZK_NOTEBOOK_DIR` behaves like setting a `--working-dir` fallback, instead of `--notebook-dir`. This way, paths will be relative to the root of the notebook. * A practical use case is to use `zk list -W .` when outside a notebook. This will list the notes in `ZK_NOTEBOOK_DIR` but print paths relative to the current directory, making them actionable from your terminal emulator. diff --git a/docs/note-format.md b/docs/note-format.md index 6e84c08..e96f97e 100644 --- a/docs/note-format.md +++ b/docs/note-format.md @@ -2,12 +2,28 @@ To keep your notebooks [future-proof](future-proof.md), `zk` uses a simple plain text format for your notes. Only Markdown is supported at the moment, but more formats may be added in the future. +## Markdown + You can set up some features of `zk`'s Markdown parser from your [configuration file](config.md), under the `[format.markdown]` section. -| Setting | Default | Description | -|------------------|---------|------------------------------------------------------------------------| -| `hashtags ` | `true` | Enable `#hashtags` support | -| `colon-tags` | `false` | Enable `:colon:separated:tags:` support | -| `multiword-tags` | `false` | Enable Bear's [`#multi-word tags#`][1]. Hashtags must also be enabled. | +| Setting | Default | Description | +|-----------------------|-----------------|--------------------------------------------------------------------------------| +| `link-format` | `"markdown"` | Format used to generate internal links (`markdown`, `wiki` or custom template) | +| `link-encode-path` | `-`1 | Percent-encode paths of generated internal links | +| `link-drop-extension` | `true` | Remove the path file extension of generated internal links | +| `hashtags ` | `true` | Enable `#hashtags` support | +| `colon-tags` | `false` | Enable `:colon:separated:tags:` support | +| `multiword-tags` | `false` | Enable Bear's [`#multi-word tags#`][1]. Hashtags must also be enabled. | + +1. Paths are not percent-encoded by default, unless the `link-format` is `markdown`. [1]: https://blog.bear.app/2017/11/bear-tips-how-to-create-multi-word-tags/ + +### Customizing the Markdown links generated by `zk` + +By default, `zk` will generate regular Markdown links for internal links. If you prefer to use `[[Wiki Links]]` instead, set the `link-format` setting to `wiki`. If you want to override completely the link format, you can also set `link-format` to a [custom template](template.md). Two variables `path` and `title` are available in the template, for example to generate a wiki-link with a title: + +```toml +[format.markdown] +link-format = "[[{{path}}|{{title}}]]" +``` diff --git a/docs/template-format.md b/docs/template-format.md index 8357cf3..bd6e39a 100644 --- a/docs/template-format.md +++ b/docs/template-format.md @@ -2,19 +2,21 @@ The following variables are available in the templates used when formatting notes, for example with `zk list --format