Repurposing Hugo as a wiki | Hacker News Reader

Repurposing Hugo as a wiki

justinmiller.io

123 pointsincanus7756 comments

I use something conceptually similar-ish. I use iA Writer as my PKM[0], complete with wikilinks between docs, embedded images, etc. Then I have a Python script that slurps in all those Markdown files, changes the wikilinks to Hugo's own intra-site link format, and changes the Writer-formatted image tags to Hugo's. Then there's a Justfile that runs the Python script, runs Hugo to build the site, and then runs rsync to upload the whole mess to my webserver. A cron job does all that regularly.

My main website[1] doesn't use a lot of internal linking. There are a few links but not a lot. I have a separate private website full of family stories that I've written down for my kids, and it's very heavily cross-linked. From the authoring end of it, I'm just writing a bunch of Markdown in Writer and then it magically shows up online later.

I like it. Each piece of that process is simple and self-contained, and once up and running it Just Works.

[0]: https://en.wikipedia.org/wiki/Personal_knowledge_management

[1]: https://honeypot.net

How do you manage your private website? I had the very same idea recently, also with the blog for our travels. I wanted to share it all only with the family (not all the members live in one house). I had been thinking of WireGuarding to my local network where the website is available via the machine’s IP address and port.

I just stuck it on a public server, behind a Basic Auth login. It’s not fancy but gets the job done in the easiest way for my family.

How does it work? Are all of them have just one password, or is it login and password for each member? Is it Hugo built-in?

Clickbait. Author is using the word wiki while all he wants and actually do is a ... regular website (which obviously hugo is fit for).

The essence of a wiki is to be a collaborative website while author is expressly mentionning he doesn't want to use a wiki software because he doen't need collaborative functions.

There are many personal wikis out there, with the emphasis on interconnectedness rather than multiuserness. I think ruling out single-user setups is too narrow.

Then “personal wiki” would be a contradiction in terms, which it however isn’t.

Well it is. The fact some people do things doesn't mean said things are smart.

I use a bunch of Python scripts to publish interlinked notes written with Obsidian[1] and, more recently, SiYuan[2] with Hugo. For me, this presents the best of both worlds. Obsidian and SiYuan are very nice to write and review notes. Hugo is good for publishing to the web. Having script automation to bridge the two means you can use the strengths of each tool without having to bend it for a use case it wasn’t designed for.

[1]: https://sagar.se/notes/computers/hugo/digital-garden/publish...

[2]: https://sagar.se/notes/computers/hugo/digital-garden/publish...

I love SiYuan Note. When I discovered that exported Markdown files weren't interlinked, I wrote a Python script that uses the API and links them all together and published it on their forum.

I assume you did the same?

Yes, I did the same. I actually posted on the SiYuan user forum[1] and thanked you for the example code you posted, since I built on it:)

[1]: https://liuyun.io/article/1702364516248

Thank you! I was looking into doing something like this myself, but hadn't taken much effort yet to figure it out.

Backstory: I've been using Joplin as my primary note taking system / personal information manager for a few years. While I'm generally happy with it, I do wish I could just use the filesystem itself rather than an abstraction layer on top of it, as I'd love to be able to perform bulk operations using standard *nix tools, and perform versioning with git. Since I'm using Hugo for my personal homepage and looking to use it with a few other projects, I find myself doing a lot of copypasta between when an idea becomes enough of a "thing" to warrant becoming a post or page. I think something like this could help me bridge that gap.

I looked at every note taking app out there and finally decided to just write arbitrary text files and sync them with Syncthing. I am using the Kate editor on a Linux for this. (I don't use it for anything else) My requirements was that it had a search interface that can go into directories and that it displays a simple directory/file view. It does both great. On Android I use a similarly capable simple app called Markor which gives me a view into the exact same directory tree. Markor also has a good search.

It would really be hard to convince me to use any proprietary format for notes now.

What do you use, if anything, for linking between your notes? I'd ideally like to move to just plain markdown/text files, but being able to link notes together seems like an essential feature. Vimwiki seems to have support for linking and navigating between notes within markdown, but then I don't think Markor would be able to handle them, and it doesn't seem like there's any automated way to update references if a link is moved. I've considered writing some small scripts to automate the gaps, but then it starts to feel like I'm just designing another note app.

Frankly I haven't even thought about linking. I am a very light user. Though since markdown supports links and both editors support markdown, there might be a way. I literally just write notes then find them mostly by search even though I do have a basic directory structure and sensible file names.

Exactly. I'm a huge fan of CLI tools for text/data management as well, so I figured I was future-proofing myself a little by keeping things in Markdown files.

I know this sort of undermines this post, but just incase anyone is actually in search of a good markdown to wiki generator, use Quartz. (https://quartz.jzhao.xyz)

It's basically Obsidian Publish but free.

(not made by me)

Does anyone know how to realize versioned articles with Hugo? The visitors of an article should be able to see different edits and diff them. (this has nothing to do with git)

seems like a weird thing to want from hugo, a simple a static website generator, vs linking to gitlab/github/etc from pages

Honestly at that point you might be looking at something custom. Honestly, I'm seriously considering making my own SSG instead of hacking 11ty at this point, it's not actually a particularly difficult task, the hard part is suiting it to other's needs.

I spent 2 weeks trying to do this recently and got decently far. I learned there is an ungodly amount of yak shaving that goes into this process and that most SSG maintainers will have done it better.

I went with Astro in the end, but I loved reading this series.

https://kimmo.blog/posts/2-diy-gatsby-part-i/

It's very much a yak shaving task, and yet, with how customized my 11ty solution is, I found myself hacking around it's structure constantly. At some point, my supposed "monkey patching" was blocked with a kind message (in some 2.0 beta), and so my project has been fixed to that version for a year now. I've been told the feature I needed has now been implemented, but it's so frustrating to have all this be out of your control.

Regarding Astro, that was the original build tool I was using, early in the astro project's development. I received a community award in 2020. It didn't work for something, frankly I forget what, but it's entirely possible that it's gotten a whole lot better now.

This could be done with Hugo using Git

If you want to stick to more natural Markdown syntax, I believe you should be able to use a Hugo render hook[0] to change how normal Markdown links are rendered instead of using a custom shortcode.

[0] https://gohugo.io/templates/render-hooks/

Slick, this is news to me. I like the flexibility. It seems like Hugo's docs are quite complete, but not super optimized for either discoverability or for thinking in terms of the process that actually happens in the rendering process. I thought I've gone all over them, but I never noticed this.

If you cannot edit via the browser, it's not a wiki

I have to say that I enjoy reading about stuff like this. That you for posting this.

Whoa. This is entirely too much markup to deal with. I’ve had several stabs at getting Hugo to work for me in this scenario years ago and gave up (and stuck to my own engine) because it just wouldn’t do it in a simple, straightforward way (i.e., minimal markup, preferably none).

This is wonderful, thank you!

One little edit I made was to add this after class="missing":

title="Nothing here, yet."

I would like to use this. I have used Hugo only once and was only half successful in creating a webpage, because I am not so familiar with html and css. Do you have a ready to use GitHub repo somewhere? That would be really nice.

The deviations from a stock Hugo install, other than content pages in `content/pages/*.md` is really entirely summarized in the post. It's just the shortcode HTML file, an addition to the theme CSS (should be independent of theme), and the config file edits.

Is there any SSG that output tons of PDFs ? I have need for product documentation, with every permutation it counts upward of 10000, with mostly similar data, will it be possible to use some SSG for the same ?

I did it in the past with `wkhtmltopdf`. Upside is that it's SSG-agnostic; downside is it's a really heavy dependency with the entire browser engine.

If I were to try again I would try to wire up a Jekyll `document` `pre_render` hook to Hexapdf:

- https://jekyllrb.com/docs/plugins/hooks/

- https://hexapdf.gettalong.org/documentation/document-creatio...

In a round about way, I would suppose:

1. Having these documentation as webpages, with proper print CSS

2. SSG them into a bunch of HTML files

3. Serve them quickly with a web server (e.g., python -m http.server)

4. Run a headless Chrome, iterate, and print as PDF

There are a bunch of tools for generating PDFs from HTML documents. https://print-css.rocks/ has a list, along with CSS compatibility test results and special CSS features you can use for print documents. You could use your favorite HTML generator, then throw the result into one of those using a shell script.

I'd use Nanoc for this kind of thing.

It's more of a SSG kit and it's dead easy to write a rule + filter that, for example, takes every markdown doc in a directory and builds a pdf with Pandoc.

https://www.nanoc.app

I've had luck doing this (in mkdocs) with:

https://github.com/orzih/mkdocs-with-pdf

Mkdocs is honestly amazing for this use-case and in my experience easier to setup.

Quick guide here: https://ryan-schachte.com/blog/docs_with_mkdocs/

That's single user wiki but you can have a high performance multi-user wiki (kind of) with TinaCMS and Docusaurus namely Tinasaurus [1].

[1] Tinasaurus:

https://github.com/tinacms/tinasaurus

I feel like wikis can be made so much simpler by using Git + Markdown + Hugo (or whatever it is).

Wikis may have become complex beasts, but in the original 1995 design they were pretty much just finding CamelCasedWords and turning them into hyperlinks; minimal wikis could be a dozen lines of code...

I wish Obsidian used git instead of its own sync protocol and service. I've used it, and it wasn't bad, but I didn't feel comfortable using a third party proprietary and undocumented protocol for notes that I felt were important.

I thought it'd be okay to use the community-maintained Obsidian git plugin, but as fate would have it, my original fears actually came to pass. I lost over a month of notes due to how badly behaved its git merge heuristics are. It force pushes and rewrites history and will step on other machines with different updates. It took me a little while to catch on to the fact my notes were disappearing, and there was nothing I could do to recover.

I ultimately threw up my hands and abandoned Obsidian outright.

I just use Google drive to sync across devices, which also keeps a file history of all changes over the last 30 days (up to 100 versions per file).

I've hit that "git plugin is crap" problem with obsidian too. You've just made me think I should try unison. Also been thinking about a SSG backed with obsidian, sooooo...

Or just use MediaWiki

It's its own beast to maintain. A lot is hiding behind your "just".

If the use case is single user wiki and the user is technical enough, MediaWiki requires more resources and is also more work than Git + Markdown + a static site generator if you are already comfortable with static site generators. No specific web server config, no tricky configuration files, no database to maintain, not difficulties to upgrade the server…

Now, one could argue that "single user wiki" just means "regular website" because the essence of the wiki is gone. Wiki means "quick" (friction-less?) edits by multiple users, possibly anonymous [1]). What the author of the post did is convenient handling of internal links. Which is still a good idea, but I would do it differently: I would not create a <a href="..."> tag for missing pages, that not very nice to users. If you do this, you are intentionally creating broken links that can only be distinguished with styling, which is not very accessible. Red links are useful in an actual wiki where users can actually create the page, but on a regular website, I'd use something like <span class="missing" title="Dedicated page coming"> or so (+ whatever is needed for the title text to be accessible).

[1] https://en.wikipedia.org/wiki/Wiki

> A wiki is a form of online hypertext publication, collaboratively edited and managed by its own audience, using a web browser

is there a replacement for ikiwiki, the wiki compiler?

Just curious - why do you want to move away from ikiwiki? Wondering if there are issues or major flaws?

What is a wiki?

An interlinked documentation system, usually with some form of backlinking

I think "visitors/users can edit" (not just the site admin) is also an essential part of the definition.

https://en.wikipedia.org/wiki/Wiki

https://www.merriam-webster.com/dictionary/wiki

A self hosted editor is the key component.

Given the number of “personal wiki” applications that exist, and the conceptual viability of it (a Wikipedia-like maintained by a single person for solely their own usage — a wiki representing their own knowledge base — is perfectly sensible), I find this definition to be excessively constrained.

And from that webster’s definition, roughly any site with user comments can be called a wiki. If you change the OR to an AND, the only thing stopping HN from being a wiki is the “corrections” component — which definitely does not correctly capture the difference between the two.

Wikipedia’s definition is also awkwardly constrained — hypertext and web browsers are obviously just an artifact of current implementations; if you managed it through markdown files and an app, does it seize to be a wiki? Is an offline read-only dump of Wikipedia passed around on a USB by bicycle no longer a wiki?

> Given the number of “personal wiki” applications that exist [...] Wikipedia’s definition is also awkwardly constrained

It's neither awkward nor overly constrained. It's just defining what a wiki actually is.

I find the questions at the end of your comment strange; they have correct answers that you'd probably find surprising, given the fact that you're asking in a way that suggests you think constitutes a sound argument for your side. For example, your last one:

> Is an offline read-only dump of Wikipedia passed around on a USB by bicycle no longer a wiki?

Uh, yes? Wikipedia remains a wiki, certainly. Your offline dump of it is not. What you have there is an encyclopedia. And that exemplifies what's really at issue.

The word "wiki" being thrown around inappropriately is the product of shallow thinking about wikis, encyclopedias, and the relationship between the two. People who are in the audience for the tools described here and that you are talking about are simply not talking about wikis.

These people are not building a personal wiki—they're building a personal encyclopedia. That's what they're doing. An "encyclopedia of me". But because of a failure to grok how portmanteaus work and likely their only exposure to wikis being through Wikipedia, they have a debased understanding of what the "wiki" part of Wikipedia denotes. (Or perhaps they just think "wiki" sounds cooler than the far less hip suffix -pedia, and so they have contorted their thinking and their arguments around trying to defend saying one instead of the other at the expense of the rest of the world—the "I missed my turn, but that's okay, I'll just make everyone around me pay for it"-style of thinking.)

It's like if you lived your whole life in a part of the world where iced coffee isn't consumed (and other types of coffee only rarely), then when it's introduced to your people it's to great fanfare, and for no good reason a subset of your countrymen start calling all sorts of unrelated things "ice", whether ice is involved or not. Their sole motivation? The thing they're referring to is a coffee product. So someone asks, "Have you checked out the ice?" — at a diner where the only type of coffee comes poured from a pot of the hot stuff. "We're really getting into icemaking" — after having just bought a new countertop espresso machine. "I got some ice candies from Barter Jack's" — referring to chocolate-covered coffee beans.

> does it seize to be [...]?

The correct word is "cease", but I suppose you'd argue that that's overly prescriptive and a constraint that needs changing, too.

It's much more. See Ward Cunningham's definition, somewhere on the site linked in emmelaich's sibling comment.

It's open, grows organically by design, and much more.

See https://wiki.c2.com/ especially https://wiki.c2.com/?WikiHistory

A website that anyone can update. "Wikiwiki" is Hawaiian for quick.

Reply on news.ycombinator.com