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:
- 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
- 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
- customize config.yaml to deal with ref links not found.
# config.toml:
refLinksErrorLevel = "WARNING"
refLinksNotFoundURL = '#'
- 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 }}