I am going to do a simple install and set up of Gollum on an Ubuntu 16.04 Server.

What is Gollum? It's a git based wiki engine used by github. https://github.com/blog/774-git-powered-wikis-improved [1]

I have gotten used to using markdown and using the git wiki interface for making quick notes that I have decided it's time I figured out how to set up a Gollum wiki at home to use for my personal server documentation.

Install Ruby

The github repo for Gollum can be found at https://github.com/gollum/gollum [2] according to the documentation here the easiest way to install gollum is via RubyGems.

So with that in mind I am going to install ruby via RVM on my Ubuntu 16.04 server. I am following an rvm install guide I found at https://www.digitalocean.com/community/tutorials/how-to-install-ruby-on-rails-with-rvm-on-ubuntu-16-04 [3]

Grab the key

> gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3

Use curl to pull down the rvm.sh script

> curl -sSL https://get.rvm.io -o rvm.sh

Cat its output to bash

> cat rvm.sh | bash -s stable --rails

At some point it will ask for your user password.

Now source the script that should be installed in your home directory

> source /home/patman/.rvm/scripts/rvm

Now test it by listing them

> rvm list known

Now install a ruby version

> rvm install 2.4

Then list which ruby installations you have

> rvm list

Install Gollum Gem

> gem install gollum

Which gave me an error…

ERROR: Error installing gollum:

ERROR: Failed to build gem native extension.

Let me see if I can fix it by install libicu-dev

> sudo apt-get install libicu-dev

Try to install it again

> gem install gollum

Now there should be a gollum command available

> which gollum

Running Gollum

Test it out

Make a new repo

> mkdir wiki-test
> cd wiki-test

> git init --bare

> gollum

Gollum runs a simple web server at port 4567. Open up the wiki http://192.168.0.77:4567/ (Change the address to match your server)

I get this error Gollum::InvalidGitRepositoryError

OK that was just me being stupid I should not have used git init --bare.

Let me clean it up and start over again

> rm -r *

> git init .

> gollum

Open the gollum web server again

http://192.168.0.77:4567/create/Home

Hey look I have something.

Let me try and create a few pages and see what I get.

Preview looks fine.

If I look at the log I can see that it was commited to the local git repo.

> git log

I believe I just made the home page.

Let me make another page.

Click on New

Give it a name and hit OK.

I put the following in it and saved it

#Test Page

Testing an empty link

[[ Test | new-page ]]

Looks like it made a red link to the non-existing page I referenced.

If I click on it I do get a new page.

OK so I got it basically working. What I really want to do now is work on the interface. I would like to get it to look a lot more like a guthub wiki interface. Let me see how far I can get.

Sidebar?

First Can I make a sidebar. Looking around I found this page https://github.com/gollum/gollum/wiki#subpages [4]

Let me see if I can create a sidebar from the interface. Create a new page and call it _Sidebar.md

Place the following it as a test

#10x13 Docs

###Servers

[[ Gollum | gollum-server ]]

I do not think that worked out so well _Sidebar.md turned into Sidebar-dot-md.

I think I have to add this by hand.

Stop the Gollum server and create the _Sidebar.md file

> vi _Sidebar.md

And place the following in it

#10x13 Docs

###Servers

[[ Gollum | gollum-server ]]

Then add it to the git repo and commit it

> git add --all

> git commit -m "Added sidebar"

Oops looks like I need to add my user.email and user.name

> git config user.email "me@example.com"
> git confit user.name "Your name"

Now commit it again

> git commit -m "Added sidebar"

Start Gollum again and see what we get.

> gollum

OK that is a start.

But how do I edit it now? Let me first see if I can customize the header on each page.

If I look at the header used by github

I can see it's much simpler just a page name and then an edit and New page button. I like and I am going to try and see if I can repeat it.

I tried to add a _Header.md file which creates a result like this.

Which adds a new header… not what I want in this case.

Custom Templates

It looks like you can override the default template using

--template-dir [PATH]
with a custom mustache template

Current templates are at https://github.com/gollum/gollum/tree/master/lib/gollum/templates

Make a new directory

> mkdir -p ~/gollum-custom/templates

Now download the gollum repo and copy the templates folder to this folder.

> cd

> git clone https://github.com/gollum/gollum.git

> cp -r gollum/lib/gollum/templates/* \

~/gollum-custom/templates/

Start gollum with the --template-dir [PATH]

> cd ~/wiki-test
> gollum --template-dir \

/home/patman/gollum-custom/templates

Open the wiki

http://192.168.0.77:4567/Home

It should be the same since the template files are the same.

Now edit the page.mustache file (leave gollum running)

> cd ~/gollum-custom/templates/
> vi page.mustache

Do a search for "Latest Changes" and alter it

Save the file and reload the page.

And it has been altered!

Fix vim syntax

Before I go too far I want to fix the syntax highlighting in vim for mustache files.

I found this https://github.com/mustache/vim-mustache-handlebars [5]

> cd

> git clone git://github.com/mustache/vim-mustache-handlebars.git mustache.vim

> mkdir -p .vim/syntax .vim/ftdetect .vim/ftplugin

> cp -R mustache.vim/syntax/* ~/.vim/syntax/

> cp -R mustache.vim/ftdetect/* ~/.vim/ftdetect/

> cp -R mustache.vim/ftplugin/* ~/.vim/ftplugin/

Re-open the page.mustache file

> cd ~/gollum-custom/templates/
> vi page.mustache

Yeah highlighting!

Edit page.mustache

> vi page.mustache

Here is how I edited mine

Mousetrap.bind(['e'], function( e ) {

e.preventDefault();

window.location = "/edit" + window.location.pathname;

return false;

});

</script>

<h1>{{page_header}}</h1>

<li class="minibutton"><a href="{{base_url}}/edit/{{escaped_url_path}}"

class="action-edit-page" id="minibutton-edit-page"> >Edit</a></li>

</ul>

</div>

{{{toc_content}}}

</div>

{{{sidebar_content}}}

</div>

{{{header_content}}}

</div>

{{{content}}}

</div>

{{{footer_content}}}

</div>

<br/>

</div>

And here is the results

For now I will not fiddle with the last edited part (since I am going to be the only one editing these pages. The last thing I am going to do to this page is to get the New Page button to be green. To do that I think I need some custom css.

Use the mini-button-new-page ide

How do I get custom css in Gollum?

Custom css

Stop gollum and create a custom.css file in the git repo.

> vi custom.css

Place the following in it

#minibutton-new-page

{

color: #fff;

text-shadow: 0 -1px 0 rgba(0,0,0,0.15);

background-color: #6cc644 ;

border: 1px solid #5aad35 ;

}

#minibutton-new-page:hover

{

background-color: #55a532 ;

border-color: #519d30 ;

}

#minibutton-edit-page

{

color:#333;

}

#minibutton-edit-page:hover

{

text-decoration: none;

background-color: #ddd;

border-color: #ccc;

color:#333;

}

Add it and commit it

> git add --all

> git commit -m "Updated custom css"

Run gollum with this command.

> gollum --css --template-dir \

/home/patman/gollum-custom/templates

Now it does look like you do not need to add the custom.css to the repo to get it to work. So you are free to tweak it and reload the page.

Wahoo green is working.

More tweaks

It looks like I can tweak the _Sidebar.md file if I go to http://192.168.0.77:4567/edit/_Sidebar directly.

With that in mind I think I can tweak the page.mustache file and create a link to it within the sidebar.

First I need an icon. I use https://www.iconfinder.com/ a lot for getting free icons and on occasion buying one or two for a buck each.

Here is one that looks good enough

https://www.iconfinder.com/icons/353430/checkbox_edit_pen_pencil_icon#size=32

I am going to download this file and put it in an images folder in my git wiki

> mkdir images

> cd images

> wget https://www.iconfinder.com/icons/353430/download/png/32

> mv 32 edit_Pencil.png

Add it to my git repo

> git add --all

> git commit -m "Added pencil edit image"

Edit custom.css again

> vi custom.css

Here is my updated custom.css file

#wiki-wrapper

{

min-width: 1200px;

}

#wiki-body

{

min-width: 910px;

}

#minibutton-new-page

{

color: #fff;

text-shadow: 0 -1px 0 rgba(0,0,0,0.15);

background-color: #6cc644 ;

border: 1px solid #5aad35 ;

}

#minibutton-new-page:hover

{

background-color: #55a532 ;

border-color: #519d30 ;

}

#minibutton-edit-page

{

color:#333;

}

#minibutton-edit-page:hover

{

text-decoration: none;

background-color: #ddd;

border-color: #ccc;

color:#333;

}

#wiki-sidebar

{

width: 230px;

color: #333;

background-color: #fff;

}

#sidebar-content

{

padding: 5px;

position: relative;

}

#head

{

margin-top: 5px;

min-width: 1200px;

position: relative;

}

#icon-img

{

margin-left: 40px;

margin-top: 15px;

}

.actions

{

position: absolute;

bottom: 0;

right: 0;

}

#edit-sidebar

{

position: absolute;

top: 0;

right: 0;

}

#sidebar-content:first-child

{

margin-top:0px;

}

Now edit page.mustache in the custom templates

> vi page.mustache

Here is my file contents.

Mousetrap.bind(['e'], function( e ) {

e.preventDefault();

window.location = "/edit" + window.location.pathname;

return false;

});

</script>

<h1>{{page_header}}</h1>

<li class="minibutton"><a href="{{base_url}}/edit/{{escaped_url_path}}"

class="action-edit-page" id="minibutton-edit-page">Edit</a></li>

</ul>

</div>

{{{toc_content}}}

</div>

{{{sidebar_content}}}

</div>

{{{header_content}}}

</div>

{{{content}}}

</div>

{{{footer_content}}}

</div>

<br/>

</div>

Now I have a little edit icon there. Click it and edit the sidebar

Emojis

I am not getting emojis like I want :smile: is not working.

> gollum --emoji --css --template-dir \

/home/patman/gollum-custom/templates

Just need to start it with the --emoji tag

Here is a good page for a cheat sheet on emojis

https://www.webpagefx.com/tools/emoji-cheat-sheet/

Then I edited a file to prove it works

:smile:

:small_airplane:

:small_blue_diamond:

:heart:

:ghost:

:us:

:one:

:two:

:arrow_right_hook:

:white_check_mark:

:x:

:bangbang:

:interrobang:

Worked

But not the same icons on the emoji-cheat-sheet

I wonder if I can update them?

Tables

I am having issues with Markdown tables in gollumm

|ONe | two | three |

|:--- |:--- |:--- |

|there | 192.168.0.199/32 | here is info |

| here | 0.0.0.0/0 | more stuff |

This simple MarkDown table is not working

This is my first time installing gollum, does it have a problem with MarkDown Tables?

Poking around ….

In the gollum githup wiki I see this note …

Since all markups are rendered by the github-markup gem, you can easily add support for other markups by additional installation:

Looking a litter further I see

By default, Gollum ships with the kramdown gem to render Markdown. However, you can use any Markdown renderer supported by github-markup. The thing to remember is that the first installed renderer from the list will be used. So, for example, redcarpet will NOT be used if github/markdown is installed.

If I go over and look at https://github.com/github/markup/blob/master/lib/github/markup/markdown.rb I think this is the order they are talking about.

Let me try and install the redcarpet gem and see if it changes anything.

> gem install redcarpet

Restart gollum

> gollum --emoji --css --template-dir \

/home/patman/gollum-custom/templates

OK that did not help. In fact in this case some of the emojis that were working are no longer working.

I am going to remove this gem.

> gem uninstall redcarpet

Something odd is up I am just going to reinstall everything and see where I can get

Gollum install version 2

Going to do this without rvm this time

> sudo apt-get install ruby ruby-dev make \

zlib1g-dev libicu-dev build-essential git cmake

> sudo gem install gollum

Create a new repo and run gollum

> mkdir wiki-test

> cde wiki-test

> git init .

> gollum

Now for a test

| One | Two |

|:---|:---|

| one | two |

And save it.

Sigh…. No table

That is odd because if I send the file directly to kramdown

> kramdown Home.md

I get a table

One last try to install github-markdown

> sudo gem install github-markdown

Then restart gollum

> gollum

Wahoo that worked

Ok I think that is enough gollum for now.

I have a lot more to tweak on it. Like getting

· Emojis to look like githubs emojis

· Get auto sync of git repo to remote repo

· Set up nginx as a front with systemd starting gollum?

· Better preview tool

And many more….

References

[1] Git-powered wikis improved

https://github.com/blog/774-git-powered-wikis-improved
Accessed 4/2017

[2] Gollum github repo

https://github.com/gollum/gollum
Accessed 4/2017

[3] How To Install Ruby on Rails with RVM on Ubuntu 16.04

https://www.digitalocean.com/community/tutorials/how-to-install-ruby-on-rails-with-rvm-on-ubuntu-16-04
Accessed 4/2017

[4] Gollum wiki page subpages

https://github.com/gollum/gollum/wiki#subpages
Accessed 4/2017

[5] Vim Mustach handlebars github

https://github.com/mustache/vim-mustache-handlebars
Accessed 4/2017

Install and Configure gollum on Ubuntu 16.04

Posted on Sunday, April 2, 2017

Install Ruby

Install Gollum Gem

Running Gollum

Sidebar?

Custom Templates

Fix vim syntax

Edit page.mustache

Custom css

More tweaks

Emojis

Tables

Gollum install version 2

References

1 comment: