(no commit message)
[ikiwiki.git] / doc / forum / navigation_of_wiki_pages_on_local_filesystem_with_vim.mdwn
1 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.
2
3 This function takes into account the ikiwiki linking rules when deciding which file to go to.
4
5 > 'gf' gets in the way when there are directories with the same name of a wiki page. The 
6 > function below doesn't implement the linking rules properly (test the link (ignoring case),
7 > if there is no match ascend the dir. hierarchy and start over, until we reach the root of
8 > the wiki). I'm rewriting it to follow these rules properly
9
10 > I think the page for [[LinkingRules|ikiwiki/subpage/linkingrules]] should say that ikiwiki **ascends**
11 > the dir. hierarchy when looking for a wikilink, not that it **descends** it. Am I correct? --[[jerojasro]]
12
13 let me know what you think
14
15 To enable this functionality, paste the code below in your `.vim/ftplugin/ikiwiki.vim` file
16
17     " returns the directory which can be considered the root of the wiki the
18     " current buffer belongs to, or an empty string if we are not inside an
19     " ikiwiki wiki
20     "
21     " NOTE: the root of the wiki is considered the first directory that contains a
22     " .ikiwiki folder, except $HOME/.ikiwiki (the usual ikiwiki libdir)
23     "
24     " if you can think of a better heuristic to get ikiwiki's root, let me know!
25     function! GetWikiRootDir()
26       let check_str = '%:p:h'
27       let pos_wiki_root = expand(check_str)
28       while pos_wiki_root != '/'
29         if isdirectory(pos_wiki_root . '/.ikiwiki') && pos_wiki_root != $HOME
30           return pos_wiki_root
31         endif
32         let check_str = check_str . ':h'
33         let pos_wiki_root = expand(check_str)
34       endwhile
35       if isdirectory('/.ikiwiki')
36         return '/'
37       endif
38       return ''
39     endfunction
40     
41     " This function searches for a .mdwn file (<a:name>.mdwn) using the ikiwiki
42     " WikiLink rules and returns its full path.
43     "
44     " The rules are the following
45     "
46     " if the filename starts with '/', use as base dir the root directory of the
47     " wiki
48     "
49     " if not:
50     "
51     " try first ./<bufname>/<a:name>.mdwn
52     " then for  ./<a:name>.mdwn
53     " then for  <root_of_wiki>/<a:name>.mdwn
54     "
55     " return the first one that exists
56     "
57     " the base path (. above) is the directory that contains the current buffer
58     "
59     function! FileForWikiLink(name)
60       let target_fname=a:name . ".mdwn"
61       let wikiroot_dir = GetWikiRootDir()
62       if match(target_fname, '^/') >= 0
63         return wikiroot_dir . target_fname
64       endif
65       let subdir_file = expand('%:p:r') . "/" . target_fname
66       let currdir_file = expand('%:p:h') . "/" . target_fname
67       let wikiroot_file = wikiroot_dir . "/" . target_fname
68       if filewritable(subdir_file)
69         return subdir_file
70       endif
71       if filewritable(currdir_file)
72         return currdir_file
73       endif
74       if filewritable(wikiroot_file)
75         return wikiroot_file
76       endif
77       return a:name
78     endfunction
79     
80     setlocal includeexpr=FileForWikiLink(v:fname)