I have been building a CMS for Hugo for a while and plan on launching this spring, although it’s not Hugo-centric enough to really call it a Hugo Admin Interface, more of a Markdown CMS.

My business (Graphia Ltd) is focussed on making it easier for companies to write their internal documentation (SOPs, handbooks, instructions, guides, runbooks, etc) in a web-friendly manner, to allow them to save their documents in a open format that doesn’t require heavy, slow, inefficient and ugly tools (cough Sharepoint) that make reading a strain for users; rendering a word processor in a browser to read a file is beyond pointless.

How it works

The backend is written in Go and the frontend in Vue.js, importantly, the content is written to and read from a git repository. The database is only used to hold user credentials, everything else is in git.

Creating a document actuallycreates a bundle, so all images are stored with the content - really important when you’ve got hundreds of operating procedures full of images, diagrams and charts!

Every time a directory or document is created, saved or deleted, the CMS actually creates a Git commit.

As expected, the full history for every file is easily viewable through the frontend although in fairness the UI here could do with some polish!

Some nice features

Frontmatter is automatically dealt with by the editor, fields are placed alongside the document and everything’s put back together server-side prior to commit.

Advanced authors/users can upload their SSH public key (as they would on GitHub, Gitlab etc) and clone the repository, push commits etc.

Designers can do the same with the Hugo theme to customise at will

The CMS works with Hugo’s Multilingual Mode and makes creating translations of documents easy. Thanks to the bundling, all translations live in a single directory and can share assets. The CMS won’t ever do auto-translation but will (at some point!) automatically generate XLIFF files that can be sent to translators.

What it isn’t designed to do

File-based user permissions

The web UI will be aimed at regular business folks and will have no knowledge of branches and merging

What it doesn’t do yet

There is no UI to edit Hugo settings

Take enough advantage of Hugo’s shortcodes (yet). I want to be able to (and have some ideas on) allow users to drag in CSV or .dot files and let users configure charts, graphs and tables. But that’s in phase two with the new ‘block’ based editor.

Auto completion for links, this is next on my todo list

Auto publish on commit

Long term goals

If there is any interest in it as a product, I would love to open source the CMS and shift my company’s focus to the onboarding process - definitely the biggest hurdle for most companies. Getting decades of poorly-formatted Word docs into consistent Markdown is quite a big task and not for the feint of heart.

If there is any interest in it as a product, I would love to open source the CMS and shift my company’s focus to the onboarding process - definitely the biggest hurdle for most companies.

The target market for this product, IMO, would be folks not using text editors, folks who are stuck with Word and/or Confluence. And that’s a huge market… unfortunately.

Products like these give me a little hope that documentation in future will be all plain text.

Getting decades of poorly-formatted Word docs into consistent Markdown is quite a big task and not for the feint of heart.

So much this! I am currently working/promoting for development of new documents in plain text (Org mode erm, better than Markdown… but Markdown is still waaay much better than Word docs ). It’s a slow process, but eventually will get there… Though, need to fight the new evil: Confluence “documents”… which are ephemeral web pages, and not even documents.

Completely agree on the Confluence thing @kaushalmodi mentions . We moved away from it, because it was similar lock-in to using Word, since the whole thing was in a DB (and, java which was a horrific nightmare to self-host; oh, the headaches!).

I’m not sure if anyone on here knows about DITA, which was originally developed by IBM to store their incredibly massive library of documentation. Even if you never use it, it’s an interesting technology to learn
a bit about.

When I was researching “future proof documentation” a few years ago, I came across DITA, and various editors for it. A company called Codex had developed an editor for a subset of the DITA spec, and this editor was by far the easiest to use among the ones I tried (DITA can be pretty complex). The CMSs being developed for Hugo and/or generic sets of text documents, mentioned here, especially given the new concept of “bundles” in Hugo, reminded me of this foray of mine into the DITA world.

We took a pretty odd approach in my company to getting away from Word, which was not DITA (in the end), but rather to author our documents in markdown, and store them in a table in our home-grown ERP database. Most people are authoring in a markdown text editor and pasting a version into the textarea in the ERP’s UI.

I back up all the various data in this DB a few times a day, and stick the output files into a git repo. It’s not pure markdown, but, it’s at least accessible in a text editor and, in a repo so I can diff them. The biggest itch my staff have is, images and attachments are not very easy to upload to these documents.

I love the idea of having a simple editor that can work with Hugo bundles, so I might convert our process yet again.

The target market for this product, IMO, would be folks not using text editors, folks who are stuck with Word and/or Confluence. And that’s a huge market… unfortunately.

Thank you for your feedback.

Essentially the CMS web interface is straightforward enough for people used to Word or Confluence to grasp. Navigating to a document, editing it and saving it with a commit message (that will probably be renamed to “describe your changes” or similar) are all trivial, the process and workflow are all familiar to anyone who has used a CMS.

For advanced users (IT folks, developers) the notion of supplying a SSH key and cloning the repo and using <editor> shouldn’t be a problem.

The problem area is that some authors will find the web editor too limiting and the cloning process too complicated. I know that the long term answer to this is to build a better web editor, but that’s a mammoth task and I want to launch with a basic editor first to ensure the concept is sound.

The quicker approach is to make cloning and working locally easier, which isn’t too bad on a Unix/Unix-like OS, but setting up SSH keys on Windows was a ballache last time I tried it. Plus, git’s stage→commit→push workflow really isn’t straightforward.

Thankfully, the rise in popularity of Visual Studio Code with built-in git and the fact that Windows is getting SSH should hopefully make this much simpler.

Since I started this topic, I actually went away and built the thing that I needed, which may end up being useful for a subset of y’all, too. It’s pretty basic, but does what I need, which is: something that enables collaboration on static sites without needing to educate writers on Git. My target audience is folks who are used to MS Word or Google Docs, trying to ease their transition. The idea would be that a more technical person does the more complicated parts of the setup of Hugo using whatever tools they prefer, but then the writers and editors have something more specialized to their needs.

The software is called Drax (because it’s meant to go alongside Hugo, and Hugo Drax was a heck of a Bond villain.) It’s open source, and designed to be easily deployable to cheap hosting, so if you need to customize it or don’t like tying yourself to third-party websites, you have options.

It only does GitHub as a backend, and intentionally abstracts away a lot of Git. Editors and collaborators can annotate text, and the annotations are stored as separate files. (This can lead to problems if the main files are modified outside of Drax, but it does its best to sync up annotations based on diffing with Git, and lets you know if they might be out of whack.) You can also add a .drax/config.json file to the repository and set a “content root” so that writers only have to deal with the less-scary (for them) directories.

The editor itself was built from scratch with CodeMirror; I didn’t love SimpleMDE’s formatting operations, and spent a while getting it to feel right. CodeMirror’s Markdown parsing isn’t quite perfect (though I’ve submitted some patches there), so there’s something to be desired, but it’s close enough for the moment.

It doesn’t as yet do an HTML preview (mainly because the “styled plaintext” does most of the job I need it to do), support image uploads, or Hugo shortcodes. It intentionally doesn’t handle users, access control, or any of that kind of thing, just punting it all over to GitHub. I know this makes it unsuitable for some people’s uses, but that’s ok!

It ain’t the slickest design, but has a minimalism that keeps it from being too offensive.

Anyway, it’s a thing I made for my own needs and is getting a workout from a small group, but if anyone else finds it useful, feel free to give it a go! There are almost certainly bugs lurking about, but there shouldn’t be anything at the “OMG” level.

Since the application is developed using Electron, it should run on Windows, Linux and Mac.
I think I just need to generate the binaries. I’ll do that for Linux as soon as possible, but it will take some time (my wife won’t let me do that in this weekend).