Hugo

My tips to turn a github wiki into hugo website

I’m happy to see the internal shortcode for cross-referencing, which enables me to make cross-referencing links similar to the [[term]] grammar in the GitHub wiki.

So I tried to turn an existing GitHub wiki (based on markdown) into a Hugo website and I’m happy with the result.

I’ve searched in this community and found related discussions like this one
and this one
but not much was covered. So I hope my writeup can be of some help.

The steps are pretty simple:

  1. clone the GitHub wiki and copy the source files into Hugo source content/. I use the following script.
#!/bin/bash
echo "...working on wiki"

wikipath=/yoursite/content/wiki/
mkdir -p /tmp/_mywiki
mkdir -p $wikipath

git clone https://github.com/project/project.wiki.git /tmp/_mywiki
cp /tmp/_mywiki/*.md $wikipath
rm -rf /tmp/_mywiki
  1. use regex to convert [[term]] to {{<ref “term” >}}
#!/bin/bash
# https://stackoverflow.com/questions/1103149/non-greedy-reluctant-regex-matching-in-sed
# sed doesn't support non-greedy

perl -pi -e 's|\[\[(.*?)\]\]|[\1]({{< ref "\1" >}})|g' *.md
perl -pi -e 's|\((.*?) "wikilink"\)|({{< ref "\1" >}})|g' *.md

# remove ":en: or :ja:"
perl -pi -e 's|:en:||g' *.md 
perl -pi -e 's|:ja:||g' *.md
  1. customize config.yaml to deal with ref links not found.
# config.toml:
refLinksErrorLevel = "WARNING"
refLinksNotFoundURL = '#'
  1. custom layouts to accommodate Home.md, _Sidebar.md and _footer.md
    using GetPage
#/layouts/wiki/list.html

{{ define "main" }}
<div class="container article-container ">
    <div class="article-rightbar">
        <div class="article-rightbar-child">
            <h3>/{{.Title}}</h1>
        </div>
        <div class="article-rightbar-child">
            {{ with .Site.GetPage "/_Sidebar.md" }}
            {{ .Content }}
            {{ end }}
        </div>
    </div>
    <div class="article-metamain">
        <div class="article-content">
            {{ with .Site.GetPage "/Home.md" }}
            {{ .Content }}
            {{ end }}
        </div>
        <div class="article-content">
            {{ with .Site.GetPage "/_footer.md" }}
            {{ .Content }}
            {{ end }}
        </div>
    </div>
</div>
{{ end }}


Result

the source github wiki

2 Likes

this is awesome and super useful, thanks!

1 Like

btw, which theme are you using @tcgriffith ?

Actually I’m using a homebrew theme created from scratch. It hasn’t been submitted to the theme showcase yet.

You are welcome to clone the repo and play around with it.

Hi, I’ve finally got time to wrap this theme up and submitted to the official showcase.

The theme repo