Renaming notes

[srid]

Would this be in scope for zk? Basically:

zk rename Foo "Bar Qux"

will rename Foo.md to Bar Qux.md while taking care of references. By which I mean it will replace all occurrences of [[Foo]] with [[Bar Qux]] in the notebook. As well as [[Foo|...]] with [[Bar Qux|..]]. This is exactly what the vscode-memo extension does.

The replacement can be delegated to sd.

EDIT: It should probably take directory and relative wiki links too into consideration? eg: [[Parent/Foo]] -> [[Parent/Bar Qux]]. Might have to disambiguate multiple Foo.md as well (in different parents).

[mickael-menu]

Absolutely, and this was partially discussed here: zk-org/zk-nvim#27 (comment)

I'll open a dedicated feature request issue to track this, as it's the next most important feature zk is lacking in my opinion.

The thing that is holding me back is the flexibility granted by wiki links. Currently a wiki link can match any unique sub-portion of the whole href, which allows for example to use [[a9dn]] to link to ref/a9dn An interesting book.md.

Maybe I could use the link-format config template to regenerate the links regardless of their current format.

[srid]

That's quite a detailed spec. :-) I'll take a look the soonest as possible.

[srid]

Personally, I think I'd use zk move with single note source/target. I don't imagine the need for any other use cases. In my notebook, the filename (sans ext) is the link title. IIUC your proposal would work for this simple use case.

I probably won't need to use interactive editing or -n. I would only run zk move with a clean Git working copy. Then I can use git diff to review the modifications and adjust accordingly. I imagine some edits would be false positives, such as those made inside code blocks, which will have to be manually reverted.¹

Footnotes

1. The only way to fix this would be to make the search-and-replace semantic. ↩

[mickael-menu]

Thanks for you review Srid 🙏

In my notebook, the filename (sans ext) is the link title. IIUC your proposal would work for this simple use case.

So I understand better, you don't have a title heading (or title YAML frontmatter property) in your notes? You only derive the title from the note filename? Because zk move would move the file without changing any heading in the Markdown content, but zk rename would.

Personally, I think I'd use zk move with single note source/target

True, I'll keep things simple for now. Moving whole folders can always be added later on.

The only way to fix this would be to make the search-and-replace semantic.

That's the plan 👍 I'll be using the database index to locate the links instead of parsing all the files to find matches.

I probably won't need to use interactive editing or -n.

I guess it's also not the most pressing feature. For my notebook, I think the interactive mode would be useful because:

• My note filenames are just an ID, e.g. oumc.md
• I write my links inlined in the prose, similarly to Andy Matuschak's notes.

Here's a concrete note I have, in the file oumc.md:

# Strings are a complicated data structure

Given the Hindi word "नमस्ते":

1.  It can be represented as a byte array of 18 bytes:
    `[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164, 224, 165, 135]`
    
2.  If you look at Unicode scalar values, you get an array of 6 characters:
    `['न', 'म', 'स', '्', 'त', 'े']`

3.  But the fourth and sixth letters are diacritics. To get the human-readable letters, you need to look at the
    strings as an array of *grapheme clusters*:
    `["न", "म", "स्", "ते"]`

Which is referenced in another note like this:

Rust prevents many string-related errors by forcing developers to put more thought into
handling UTF-8 data upfront, as [strings are complicated](oumc).

Say I want to rename this note because it's content went in another direction, I would like to review all the links to make sure they are still matching the context, and maybe adapt the letter case. I could do this after the fact using the Git diff, but that would be cumbersome to modify the files individually.

[srid]

So I understand better, you don't have a title heading (or title YAML frontmatter property) in your notes?

Notes can have them; and if they do, they will be used in place of the filename when rendering links. But, it doesn't change the way you link to them - thus this shouldn't impact zk move. For eg., if foo.md has a custom title # Foo Note, you would still link to it as [[foo]]. If I want to rename this title (not filename) I'd just do it manually - as there are no references to it. The link reference is always by filename (sans ext).

You only derive the title from the note filename?

Yes, unless a title (H1 or frontmatter) is explicitly specified by the user. Filename is simply a 'fallback' value for the note title when the user does not specify one explicitly. But again, note title is not the same thing as link reference (ID).

Example:

• Explicit title ("Woke Inveigling"): https://github.com/srid/srid/blob/master/content/unfree/woke/woke-inveigling.md
  • https://srid.ca/woke-inveigling
• Implicit title ("Stay niche"): https://github.com/srid/srid/blob/master/content/Thoughts/Stay%20niche.md
  • https://srid.ca/niche

---

Here's a sample notebook: https://github.com/srid/emanote/tree/master/docs

You can see how index.md links to guide.md using [[guide]]. Alternative ways of linking include: [foo](guide.md) or [[guide|foo]]. When I execute zk move ./guide.md ./somedir/newguide.md, I'd expect those links to be rewritten to: [[newguide]], [foo](somedir/newguide.md) and [[newguide|foo]] respectively. Does that clarify my use case?

Note that in Emanote [[newguide]] is equivalent to [[somedir/newguide]] (assuming no ambiguities).

[mickael-menu]

Thank you, this is in line with what I had in mind.

I'd expect those links to be rewritten to: [[newguide]], [foo](somedir/newguide.md) and [[newguide|foo]] respectively. Does that clarify my use case?

I'm not yet sure I plan to handle replacing multiple kind of links. I thought I would just use the link format declared in the .zk/config.toml file. But I doubt people are mixing intently wiki links and markdown links.

Note that in Emanote [[newguide]] is equivalent to [[somedir/newguide]] (assuming no ambiguities).

Yes this is also how it's handled with zk 👍 Any unique portion of a path is enough with wiki links.

[edrex]

Hoy Mickael and Srid,

I have been mostly staying out of discussions around link name resolution and bulk rename in these tools, mainly because I like to stay light on output-time link resolution magic and instead have my editor exactly resolve relative links at edit time.

My take:

• searching up the directory heirarchy is allowed for readability, but not descending to find cousins etc. For that use a relative link (or at least the descending fragment, so eg [[foo/bar]] could resolve [[../../foo/bar.md]]
• Your editor should autocomplete a relative path (to the current file, not the wiki root. This allows wikis to be composed by directory inclusion etc). Rename tools should handle path changes.
• Build-time link resolution should have well-defined precedence rules for directory search, and take the first match. Currently emanote treats a link with multiple matches as a failure, and renders an inline disambiguation error, which while neat, I don't find useful. Just search up from the current directory, and take the first match.

I know that a lot of zettel prefer flat repositories, and there are definitely good reasons to go that way, but I like my directories, since they make things like subsetting (ie, "publish my bike/ stuff to a separate branch using git subtree) and composition less hairy.

The thing that is holding me back is the flexibility granted by wiki links. Currently a wiki link can match any unique sub-portion of the whole href, which allows for example to use [[a9dn]] to link to ref/a9dn An interesting book.md.

Likewise, i don't see the value in prefix matching - I would rather resolve exact names at edit time. I get though that the motivation is that it works with zettelkasten-style names where the initial YYYYMMDDHHmm acts as a sort of quick-n-dirty UUID. But then you can only freely change the trailing part of the file name if you know for sure that every inbound link only uses the prefix, so again it doesn't seem that useful (unless you are consistent globally - I never am :D)

I planning to break ground on a kind of "folkspec" for markdown wiki syntax extensions, in the form of a (nix flake based) test suite that validates and compares the behavior of many different tools, which I hope can help inform many conversations about how we can make our syntax extensions and interpretation rules more consistent and predictable across the ecosystem.

Along with this test suite, I want to build a kind of linter/refactoring suite which uses a local description of the desired repository format/invariants for a repository, and reports/converts non-conforming nodes. I know there's a lot of overlap with zk here, and it will undoubtedly act as the backend for some of the functions, but I want a framework that supports a heterogeneous panoply of tools

An example of a local repo spec::

• Links are document-relative with updir-search
• Documents have a zettel date prefix (could get date from YAML or ctime if missing)
• All documents should be reachable from the Start node by at most 4 neuron-style folgezettel link traversals.
• If both Foo.md and Foo/ exist, rename Foo.md -> Foo/index.md. It makes operating on subdirectories so much more ergonomic

Just want to check in with y'all about what I'm planning, because I hope to collaborate a lot going forward.

Best
-- Eric

[mickael-menu]

@edrex Thank you for your input.

• searching up the directory heirarchy is allowed for readability, but not descending to find cousins etc. For that use a relative link (or at least the descending fragment, so eg [[foo/bar]] could resolve [[../../foo/bar.md]]

I'm not sure I understand this, why can't you descend in the folders from the current path? Could you give some examples of allowed and forbidden hrefs?

• Build-time link resolution should have well-defined precedence rules for directory search, and take the first match. Currently emanote treats a link with multiple matches as a failure, and renders an inline disambiguation error, which while neat, I don't find useful. Just search up from the current directory, and take the first match.

Searching the closest match in the file system makes sense. zk takes the first shortest path match, but it could probably be improved.

Likewise, i don't see the value in prefix matching - I would rather resolve exact names at edit time. I get though that the motivation is that it works with zettelkasten-style names where the initial YYYYMMDDHHmm acts as a sort of quick-n-dirty UUID.

It's indeed mostly for interop with zettelkasten.de format. But basically zk matches:

• For markdown links, any relative path prefix – so that it works with ID Title.md or dropping the extension.
• For Wiki links, any unique portion of a path.

I planning to break ground on a kind of "folkspec" for markdown wiki syntax extensions, in the form of a (nix flake based) test suite that validates and compares the behavior of many different tools, which I hope can help inform many conversations about how we can make our syntax extensions and interpretation rules more consistent and predictable across the ecosystem.

IMO this would be really helpful. Especially since wiki links are propagating quickly in all Markdown-based apps and there's no clear spec. After all we're using Markdown for future-proofing and interoperability.

[edrex]

Btw, the link resolution rules I described above come from Ikiwiki, AFAIK the first tool to embrace the "Git directory of markdown files with wiki links" format, and still today the most cohesive and humanely designed. I just wish I didn't have to interact with CPAN to install it 😨 (I say that knowing it's packaged in both Debian and nixpkgs. It may end up back in my toolbox shortly)