+**UPDATE** I have created a [[page|tips/follow_wikilinks_from_inside_vim]] in
+the tips section about the plugin, how to get it, install it and use it. Check
+that out. --[[jerojasro]]
+
I wrote a vim function to help me navigate the wiki when I'm editing it. It extends the 'gf' (goto file) functionality. Once installed, you place the cursor on a wiki page name and press 'gf' (without the quotes); if the file exists, it gets loaded.
This function takes into account the ikiwiki linking rules when deciding which file to go to.
let me know what you think
-To enable this functionality, paste the code below in your `.vim/ftplugin/ikiwiki.vim` file
+> " NOTE: the root of the wiki is considered the first directory that contains a
+> " .ikiwiki folder, except $HOME/.ikiwiki (the usual ikiwiki libdir)
+>
+> That's not going to work in all situations; for example, with an ikiwiki which uses git as the backend, the normal setup is that one has
+>
+> * a bare git repository
+> * a git repository which ikiwiki builds the wiki from (which has a .ikiwiki directory in it)
+> * an *additional* git repository cloned from the bare repository, which is used for making changes from the command-line rather than the web. It is this repository in which one would be editing files with vim, and *this* repository does not have a .ikiwiki directory in it. It does have a .git directory in the root, however, so I suppose you could use that as a method of detection of a root directory, but of course that would only work for git repositories.
+>
+> -- [[KathrynAndersen]]
+>
+>> You are completely right; all of my wikis are compiled both locally and
+>> remotely, and so the local repo also has a `.ikiwiki` folder. And that's not the
+>> "usual" setup.
+>>
+>> checking for a `.git` dir would not work when the wiki's source files aren't
+>> located at the root of the repo.
+>>
+>> So, besides of doing a `touch .ikiwiki` at the root of the wiki in your local
+>> repo, do you see any alternative?
+>>
+>> -- [[jerojasro]]
+
+well. I've rewritten the whole thing, to take into account:
+
+ * file matching ignoring case (MyPage matches mypage.mdwn)
+ * checking all the way down (up) to the root of the wiki (if there is a link `\[[foo]]` on `a/b/page`),
+ try `a/b/page/foo`, then `a/b/foo`, and so on, up to `foo`
+ * the alternate name for a page: when looking for the file for `\[[foo]]`, try both `foo.mdwn` and `foo/index.mdwn`
+
+you can find the file [here](http://git.devnull.li/cgi-bin/gitweb.cgi?p=vim-jerojasro.git;a=blob;f=.vim/ftplugin/ikiwiki_nav.vim;hb=HEAD). To use it, place it in `$HOME/.vim/ftplugin`. After that, hitting `<CR>` (Enter) in normal mode over a wikilink will take you to that page, if it exists.
+
+the plugin has, as of now, two problems:
+
+ * doesn't work with wikilinks that take more than one line (though this isn't really that bad)
+ * it assumes that the root of the wiki is the first directory down the filesystem hierarchy that
+ has a `.ikiwiki` folder on it. If your copy of the wiki doesn't have it, you must create it for
+ the plugin to work
+
+-- [[jerojasro]]
- " returns the directory which can be considered the root of the wiki the
- " current buffer belongs to, or an empty string if we are not inside an
- " ikiwiki wiki
- "
- " NOTE: the root of the wiki is considered the first directory that contains a
- " .ikiwiki folder, except $HOME/.ikiwiki (the usual ikiwiki libdir)
- "
- " if you can think of a better heuristic to get ikiwiki's root, let me know!
- function! GetWikiRootDir()
- let check_str = '%:p:h'
- let pos_wiki_root = expand(check_str)
- while pos_wiki_root != '/'
- if isdirectory(pos_wiki_root . '/.ikiwiki') && pos_wiki_root != $HOME
- return pos_wiki_root
- endif
- let check_str = check_str . ':h'
- let pos_wiki_root = expand(check_str)
- endwhile
- if isdirectory('/.ikiwiki')
- return '/'
- endif
- return ''
- endfunction
-
- " This function searches for a .mdwn file (<a:name>.mdwn) using the ikiwiki
- " WikiLink rules and returns its full path.
- "
- " The rules are the following
- "
- " if the filename starts with '/', use as base dir the root directory of the
- " wiki
- "
- " if not:
- "
- " try first ./<bufname>/<a:name>.mdwn
- " then for ./<a:name>.mdwn
- " then for <root_of_wiki>/<a:name>.mdwn
- "
- " return the first one that exists
- "
- " the base path (. above) is the directory that contains the current buffer
- "
- function! FileForWikiLink(name)
- let target_fname=a:name . ".mdwn"
- let wikiroot_dir = GetWikiRootDir()
- if match(target_fname, '^/') >= 0
- return wikiroot_dir . target_fname
- endif
- let subdir_file = expand('%:p:r') . "/" . target_fname
- let currdir_file = expand('%:p:h') . "/" . target_fname
- let wikiroot_file = wikiroot_dir . "/" . target_fname
- if filewritable(subdir_file)
- return subdir_file
- endif
- if filewritable(currdir_file)
- return currdir_file
- endif
- if filewritable(wikiroot_file)
- return wikiroot_file
- endif
- return a:name
- endfunction
-
- setlocal includeexpr=FileForWikiLink(v:fname)
+> Interesting. I was at one point looking at "potwiki.vim", which implements a local wiki and follows CamelCase links, creating new files where necessary etc., to see if it could be adapted for ikiwiki (See [[tips/vim syntax highlighting/discussion]]). I didn't get anywhere. -- [[Jon]]
+
+>> when I wrote the plugin I also considered the possibility of creating files (and their dirs, if necessary)
+>> from new wikilinks; the changes needed to get that working are fairly small -- [[jerojasro]]
+
+> Seems about ready for me to think about pulling it into ikiwiki
+> alongside [[tips/vim_syntax_highlighting/ikiwiki.vim]]. If you'll
+> please slap a license on it. :) --[[Joey]]
+>
+>> GPL version 2 or later (if that doesn't cause any problems here). I'll add it
+>> to the file --[[jerojasro]]
+>>
+>>> I see you've put the plugin on vim.org. Do you think it makes sense to
+>>> also include a copy in ikiwiki? --[[Joey]]
+>
+> Also, I have a possible other approach for finding ikiwiki's root. One
+> could consider that any subdirectory of an ikiwiki wiki is itself
+> a standalone wiki, though probably one missing a toplevel index page.
+> The relative wikilinks work such that this assumption makes sense;
+> you can build any subdirectory with ikiwiki and probably get something
+> reasonable with links that work, etc.
+>
+> So, if that's the case, then one could say that the directory that the
+> user considers to be the toplevel of their wiki is really also a subwiki,
+> enclosed in a succession of parents that go all the way down to the root
+> directory (or alternatively, to the user's home directory). I think that
+> logically makes some sense.
+>
+> And if that's the case, you can resolve an absolute link by looking for
+> the page closest to the root that matches the link.
+>
+>> I like your idea; it doesn't alter the matching of the relative links, and
+>> should work fine with absolute links too. I'll implement it, though I see
+>> some potential (but small) issues with it --[[jerojasro]]
+>
+> It may even make sense to change ikiwiki's own handling of "absolute"
+> links to work that way. But even without changing ikiwiki, I think it
+> would be a reasonable thing for vim to do. It would only fail in two
+> unusual circumstances:
+>
+> 1. There is a file further down, outside what the user considers
+> the wiki, that matches. Say a `$HOME/index.mdwn`
+> 2. An absolute link is broken in that the page linked to does
+> not exist in the root of the wiki. But it does exist in a subdir,
+> and vim would go to that file.
+>
+> --[[Joey]]
+>
+>> your approach will add more noise when the plugin grows the page-creation
+>> feature, since there will be no real root to limit the possible locations for
+>> the new page. But it is far better than demanding for a `.ikiwiki` dir --[[jerojasro]]