doc/forum/navigation_of_wiki_pages_on_local_filesystem_with_vim.mdwn

   1 **UPDATE** I have created a [[page|tips/follow_wikilinks_from_inside_vim]] in
   2 the tips section about the plugin, how to get it, install it and use it. Check
   3 that out. --[[jerojasro]]
   4
   5 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.
   6
   7 This function takes into account the ikiwiki linking rules when deciding which file to go to.
   8
   9 > 'gf' gets in the way when there are directories with the same name of a wiki page. The
  10 > function below doesn't implement the linking rules properly (test the link (ignoring case),
  11 > if there is no match ascend the dir. hierarchy and start over, until we reach the root of
  12 > the wiki). I'm rewriting it to follow these rules properly
  13 >
  14 > I think the page for [[LinkingRules|ikiwiki/subpage/linkingrules]] should say that ikiwiki **ascends**
  15 > the dir. hierarchy when looking for a wikilink, not that it **descends** it. Am I correct? --[[jerojasro]]
  16
  17 >> Conventionally, the root directory is considered to be lower than other
  18 >> directories, so I think the current wording is correct. --[[Joey]]
  19
  20 let me know what you think
  21
  22 >         " NOTE: the root of the wiki is considered the first directory that contains a
  23 >         " .ikiwiki folder, except $HOME/.ikiwiki (the usual ikiwiki libdir)
  24 >
  25 > 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
  26 >
  27 > * a bare git repository
  28 > * a git repository which ikiwiki builds the wiki from (which has a .ikiwiki directory in it)
  29 > * 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.
  30 >
  31 > -- [[KathrynAndersen]]
  32 >
  33 >> You are completely right; all of my wikis are compiled both locally and
  34 >> remotely, and so the local repo also has a `.ikiwiki` folder. And that's not the
  35 >> "usual" setup.
  36 >>
  37 >> checking for a `.git` dir would not work when the wiki's source files aren't
  38 >> located at the root of the repo.
  39 >>
  40 >> So, besides of doing a `touch .ikiwiki` at the root of the wiki in your local
  41 >> repo, do you see any alternative?
  42 >>
  43 >> -- [[jerojasro]]
  44
  45 well. I've rewritten the whole thing, to take into account:
  46
  47   * file matching ignoring case (MyPage matches mypage.mdwn)
  48   * checking all the way down (up) to the root of the wiki (if there is a link `\[[foo]]` on `a/b/page`),
  49   try `a/b/page/foo`, then `a/b/foo`, and so on, up to `foo`
  50   * the alternate name for a page: when looking for the file for `\[[foo]]`, try both `foo.mdwn` and `foo/index.mdwn`
  51
  52 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.
  53
  54 the plugin has, as of now, two problems:
  55
  56   * doesn't work with wikilinks that take more than one line (though this isn't really that bad)
  57   * it assumes that the root of the wiki is the first directory down the filesystem hierarchy that
  58   has a `.ikiwiki` folder on it. If your copy of the wiki doesn't have it, you must create it for
  59   the plugin to work
  60
  61 -- [[jerojasro]]
  62
  63 > 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]]
  64
  65 >> when I wrote the plugin I also considered the possibility of creating files (and their dirs, if necessary)
  66 >> from new wikilinks; the changes needed to get that working are fairly small -- [[jerojasro]]
  67
  68 > Seems about ready for me to think about pulling it into ikiwiki
  69 > alongside [[tips/vim_syntax_highlighting/ikiwiki.vim]]. If you'll
  70 > please slap a license on it. :) --[[Joey]]
  71 >
  72 >> GPL version 2 or later (if that doesn't cause any problems here). I'll add it
  73 >> to the file --[[jerojasro]]
  74 >>
  75 >>> I see you've put the plugin on vim.org. Do you think it makes sense to
  76 >>> also include a copy in ikiwiki? --[[Joey]]
  77 >>>
  78 >>>> mmm, no. There would be two copies of it, and the git repo. I'd rather have
  79 >>>> a unique place for the "official" version (vim.org), and another for the dev
  80 >>>> version (its git repo).
  81 >>>>
  82 >>>> actually, I would also suggest to upload the [[`ikiwiki.vim`|tips/vim_syntax_highlighting]] file to vim.org --[[jerojasro]]
  83 >>>>>
  84 >>>>> If you have any interest in maintaining the syntax highlighting
  85 >>>>> plugin and putting it there, I'd be fine with that. I think it needs
  86 >>>>> some slight work to catch up with changes to ikiwiki's directives
  87 >>>>> (!-prefixed now), and wikilinks (able to have spaces now). --[[Joey]]
  88
  89 <a id='syn-maintenance'>
  90
  91 >>>>>
  92 >>>>>> I don't really know too much about syntax definitions in vim. But I'll give it a stab. I know it fails when there are 2 \[[my text|link]] wikilinks in the same page.
  93 >>>>>> I'm not promising anything, though ;) --[[jerojasro]]
  94 >
  95 > Also, I have a possible other approach for finding ikiwiki's root. One
  96 > could consider that any subdirectory of an ikiwiki wiki is itself
  97 > a standalone wiki, though probably one missing a toplevel index page.
  98 > The relative wikilinks work such that this assumption makes sense;
  99 > you can build any subdirectory with ikiwiki and probably get something
 100 > reasonable with links that work, etc.
 101 >
 102 > So, if that's the case, then one could say that the directory that the
 103 > user considers to be the toplevel of their wiki is really also a subwiki,
 104 > enclosed in a succession of parents that go all the way down to the root
 105 > directory (or alternatively, to the user's home directory). I think that
 106 > logically makes some sense.
 107 >
 108 > And if that's the case, you can resolve an absolute link by looking for
 109 > the page closest to the root that matches the link.
 110 >
 111 >> I like your idea; it doesn't alter the matching of the relative links, and
 112 >> should work fine with absolute links too. I'll implement it, though I see
 113 >> some potential (but small) issues with it --[[jerojasro]]
 114 >
 115 > It may even make sense to change ikiwiki's own handling of "absolute"
 116 > links to work that way. But even without changing ikiwiki, I think it
 117 > would be a reasonable thing for vim to do. It would only fail in two
 118 > unusual circumstances:
 119 >
 120 > 1. There is a file further down, outside what the user considers
 121 >    the wiki, that matches. Say a `$HOME/index.mdwn`
 122 > 2. An absolute link is broken in that the page linked to does
 123 >    not exist in the root of the wiki. But it does exist in a subdir,
 124 >    and vim would go to that file.
 125 >
 126 > --[[Joey]]
 127 >
 128 >> your approach will add more noise when the plugin grows the page-creation
 129 >> feature, since there will be no real root to limit the possible locations for
 130 >> the new page. But it is far better than demanding for a `.ikiwiki` dir --[[jerojasro]]