Project: Vimwiki+Gollum Integration

This project is somewhat Retired. I'll continue to check back here from time to time....

Author: Karl N. Redman

This is a guide and tutorial, with tools and 'out of the box' examples, for integrating Vimwiki with Gollum Wiki on Linux systems. The aim of this project is to provide a fairly easy installation and setup for a working Vimwiki + Gollum workflow.

With this project I endeavor to document the process for integrating the various components that make a fairly complete wiki system for personal use. I've added some tools and a mock up wiki installation to get you started.

Note:

This project works with Gollum v4.x/gollum-lib v4.x. I'll update the documents and installation examples when Gollum v5.x is released. Gollum v5.x has some big changes on the way. For this reason I am suspending further work on this project until the Gollum v5.x release. This project's support of Gollum v4.x is considered to be "complete enough" at this time. See 5.0 release notes for further information.

Also Note: This is a short version of the documentation. Please see the Extended documentation for more in depth information.

Features:

• All the features outlined on the Gollum Wiki Home Page.
• Tutorial with a working example 'mockwiki' directory structure (drop in).
• Edit wiki pages through Vimwiki using github mardown.
• Edit vimwiki pages through the Gollum Web Interface.
• TOC works in _Sidebar.ext and _Footer with the included monkypatched config.rb
• Regex Searches of Wiki content through the Gollum Web Interface.
  • Enables git grep on the backend.
  • Requires Gollum's Grit Git Adapter (default adapter for Linux)
  • See the search documentation for specific information about the improved search capabilities.
• PlantUML Server integration with Gollum.
  • Supports inline markdown (i.e Class Diagrams)
  • GitHub !includeurl format supported (see git - How to integrate UML diagrams into GitLab or GitHub - Stack Overflow)
• File uploads to the Vimwiki/Gollum repository from the Gollum web interface.
• Custom startup/shutdown scripts
• Cron script for automatically updating Gollum readable diary indexes.
• Extended documentation to support the entire integration process.
• A shell script is provided to help with keeping links consistent between Gollum and Vimwiki.

Special Note about internal link/tag consistency:

There is no easy way to synchronize the behavior for internal links and tags between Gollum v4.x and Vimwiki. The two systems, by way of their purpose and use cases, handle links from different perspectives. In an effort to provide the most consistent behavior between the two systems I've created a script (genSymlinks.sh)that generates symlinks with a comprehensive list of restrictions. Without some major alteration of one or both systems it seems that symlinks are as good as it's going to get until the next release of Gollum. Please see the script for more detail. There are notes in the mockwiki that detail the reluctant decision making process that went into using symlinks to solve a very complicated problem.

If you follow the 'Example Installation / Tutorial' then running the genSymlinks.sh script should work ok for you on a linux based system.

• Use the script at Your Own Risk

• Please look at the code first before running it.

• I run exactly this script from cron several times per day.

• For best results with Gollum v4.x use forward looking links as much as possible (i.e. '[[PersonalWiki/diary/2017-07-31]]' as opposed to [[2017-07-31]])

Example Gollum (v4.x) Wiki Installation / Tutorial

1. Install dependencies and their respective dependencies:

• Vim v8.0+
  • Suggested link: Vim 8.0 Released! How to install it in Ubuntu 16.04 - Tips on Ubuntu
• Git Version Control System

sudo apt-get install git

• Vimwiki vim plugin
• Pandoc

sudo apt-get install pandoc

• Gollum (v4.x)
  • ...using Github's Gollum Grit Adapter (installed by default for ubuntu systems)

[sudo] gem install gollum -v 4.1.2

* Note: For system level installs, if you get an error for '[charlock_holmes](https://github.com/brianmario/charlock_holmes)' relative to [ICU](http://site.icu-project.org/) then you need to install the unicode library and ruby dev files.
```
sudo apt-get install libicu-dev
sudo apt-get install ruby-dev
```

* For System level installs, if you are also using RVM make sure you are installing with system ruby:
```
rvm use system
```

• PlantUML Server
  • The startup script expects this to be installed at $HOME/3rdparty/plantuml-server
  • see Install local PlantUML server for installation instructions.
  • The startup script from this project starts plantuml server for you
  • You will likely need to install maven + dependencies

  sudo apt-get install maven
  

2. Add the following to your '.vimrc' configuration file:
   • Adjust the 'path:' references in your '.vimrc' 'vimwiki_list' as needed.
   • Note: if you are already a Vimwiki user then you'll want to comment out your vimwiki section in your .vimrc for this example.

let g:vimwiki_list = [
\ {'path': '~/mockwiki/Vimwiki-Gollum/', 'path_html': '~/public_html/vimwiki/Vimwiki-Personal', 'syntax': 'markdown', 'ext': '.vimwiki'},
\ {'path': '~/mockwiki/PersonalWiki/', 'path_html': '~/public_html/vimwiki/PersonalWiki', 'syntax': 'markdown', 'ext': '.vimwiki'},
\ {'path': '~/mockwiki/HouseholdWiki/', 'path_html': '~/public_html/vimwiki/HouseholdWiki', 'syntax': 'markdown', 'ext': '.vimwiki'},
\ {'path': '~/mockwiki/AnotherWiki/', 'path_html': '~/public_html/vimwiki/AnotherWiki', 'syntax': 'markdown', 'ext': '.vimwiki'},
\ ]

"" set preferred settings
"let vimwiki_folding='syntax'
let g:vimwiki_folding='list'
autocmd FileType vimwiki setlocal tabstop=4 expandtab

3. Setup wiki directory structure and initialize the repository:

   1. Clone this project:

   git clone https://github.com/karlredman/Vimwiki-Gollum-Integration.git

   2. Copy the mockwiki directory structure to your home directory:

   cp -r [path to]/Vimwiki-Gollum-Integration/mockwiki ~/

   3. Initialize the mockwiki directory as a git repository and check in the files

   cd ~/mockwiki
   git init
   git add -A
   git commit -am "initializing wiki directory structure"

4. Edit the startup script as needed

vim ~/mockwiki/gollum_admin/start_gollum.sh

5. Start Gollum

[sudo] ~/mockwiki/gollum_admin/start_gollum.sh

6. Start using the wiki: http://127.0.0.1:4567/

   • The index page for mockwiki will show links for the wiki repository

7. Check out additional demo pages on your system (http://127.0.0.1:4567/Vimwiki-Gollum/index)

   • Explore the 'Vimwiki-Gollum' wiki for information pertaining to this project

8. Try the searches suggested on the search documentation page for the example wiki.

9. Use Vimwiki to edit files in your wiki.

   • Vimwiki Cheetsheet

vim -c VimwikiIndex

11. Customize as needed.

• Gollum + PlantUML Server start and stop scripts (under mockwiki/gollum_admin)
  • configure start_gollum.sh for the path of your wiki repository, ports for Gollum and PlantUML, etc.
  • stop_gollum.sh just stops the servers based on the behavior from the start script.
• The Gollum config file is under mockwiki/gollum_admin
• GenGollumDiaryIndexes.sh
  • This is a cron safe script that generates vimwiki diary indexes (diary.vimwiki files) and then reformats them for Gollum -saving the results in an index.vimwiki for each [wikiname]/diary directory. This is necessary in order to be least intrusive for vimwiki operations while providing useful links through Gollum. Also, Vimwiki's formatting for the diary index doesn't work out of the box for Gollum.
  • I run the script once per day via cron. Generally that's all I need. Also, the script adds a 'Today' link on the diary index page for Gollum whether the file has been created or not. This way we also don't interfere with vimwiki if a diary index (diary.vimwiki) is regenerated.
  • Examples of the before and after:
    • Before: diary.vimwiki
    • After: index.vimwiki
  • Cron Setup:
    • You need to have your git credentials for your local repository setup for this to work properly.
    • The script will need to be run under your user account.

    crontab -e
    

    • I run the script at 1:05am every night because of daylight savings switches:

    5 1 * * * /home/karl/mockwiki/gollum_admin/genGollumDiaryIndexes.sh > /tmp/wtf 2<&1
    

• In order to keep link and tag behavior consistent between Gollum and Vimwiki use forward looking links along with my genSymlinks.sh script to create (eep! use at your own risk!) symlinks in (mostly) appropriate subdirectories of your repository. Obviously you'll have to commit the symlinks on your own because the script doesn't muck with git at all.