- Managing pages in git/other vcs as plain text, using any editor I choose. I can commit pages using git or other vcs, don't have to use the browser to add pages.
- Writing pages in some markup language, maybe not markdown, as it is not expressive enough in some areas. Maybe markdown is possible for simple pages and the wiki knows it is markdown from the file extension, but the wiki also allows more powerful formats like restructuredText, which can be extended by the user.
- Server-side rendering of pages, that can easily be cached (since pages are files, one could easily check the shasum of the file to determin cache validity), which makes display of pages almost instant, as opposed to laggy shitty confluence.
Not quite the same use case, but I've been really enjoying using https://nextra.site/ to create a static documentation site for one of my projects.
It's managed to strike a good balance of getting out the way and letting me mostly just write plain markdown, whilst being able to fall back to react components if needed.
With CD to GitHub pages on merge to main I think it's a pretty good experience
Why would you need a tool like this if you’re writing markdown docs outside the browser and version controlling them with Git? Doesn’t that defeat the entire purpose?
Or is it just you want a developer-native workflow to upload docs intended for the rest of the non-developer team?
In general, I would say that's a really bad idea. If you’re dumping this self-hosted (and probably bug filled MVP, as all are) on your team, yet never having to deal with the UI layer that everyone else does…it’s a recipe for revolt and tool churn.
I’ve seen this mistake a million times from technical founders. Same thing will happen with your marketing website CMS, after you realize static site + markdown + git doesn’t scale to non-dev humans and the headless CMS you picked (but never interact with) is actually trash in daily use.
> Or is it just you want a developer-native workflow to upload docs intended for the rest of the non-developer team?
This. I am so annoyed by all the quirks and silly dysfunctional behavior of confluence, when all I need is a developer friendly workflow, that actually motivates to keep documents up to date and allows diffing easily and quickly and blaming and all that good stuff you get when you have git or other capable vcs.
> In general, I would say that's a really bad idea. If you’re dumping this self-hosted (and probably bug filled MVP, as all are) on your team, yet never having to deal with the UI layer that everyone else does…it’s a recipe for revolt and tool churn.
I don't see how. Users of the UI could, without explicitly knowing, save pages creating commits themselves. Maybe it could be difficult to square that with collaboratively working on a document in realtime though. If I had to choose between the two, I would pick git workflows any day of the week though and it is not so often the case in my experience, that people really work collaboratively on wiki pages of documentation.
> I’ve seen this mistake a million times from technical founders. Same thing will happen with your marketing website CMS, after you realize static site + markdown + git doesn’t scale to non-dev humans and the headless CMS you picked (but never interact with) is actually trash in daily use.
That is, why I am suggesting my points as additional, not as replacement. The non-devs can have their clicky bunty UI, but please let me use efficient workflows as a developer and don't create a sluggish experience in the browser, that will never motivate any dev to maintain documentation inside of it.
Also markdown does not do the job. It does not have some of the necessary building blocks. It is good for simple pages and perhaps a readme, but when it gets to proper technical documents, I would rather have something more capable. For example restructuredText, where you can define custom directives and so on. I used that before to make a little wiki with document interlinking functionality when rendering and used it to write a thesis. It is very capable. But there are others like org-mode format, and asciidoc and more. All more capable than standard markdown. (And yet, confluence has already issues with standard markdown, lol.)
An alternative is, of course, not to force devs to use confluence for documentation. Keep confluence to the marketting and sales fluff, and let engineers use efficient tooling, that they are already familiar with and that accompanies the code, instead of dividing documentation out into confluence, where it will quickly become unmaintained and forgotten.
As the parent post observes, I've also yet to see a GUI that works with Markdown and static site generators. This doesn't mean it's a bad idea. It has to be good enough to dogfood.
It'd be nice to implement the non-technical workflow as producing a pull request via a branch. Each save (even autosave after N minutes) could be its own commit.
The user could see their changes from their branch in near realtime. Markdown isn't an issue, it's a benefit, although explicit support for images and diagrams is needed.
The GUI workflow could see if an automatic merge works, if not, it is fine to require manual intervention. Another option is to swap branches, copy main branch, rollback main branch to the place before any conflicts emerged, and then apply changes.
Bonus points for using CRDT for handling multiple users working together on a page during a conference call on the same branch.
man I have a hard enough time coaching new grads and juniors through borked rebases and merges, I would do anything to not be the one trying to automate that for HR and accounting people using what looks to them like any other word processor.
We use Jekyll for this at work, build the site using GitHub actions, and host through GitHub pages. Works a treat. Supports mermaid diagrams, mathml, ...
Just another vote against Markdown. Markdown is OK for simple docs, but very poor for wiki where inter-page links are the Magic Sauce. Creole markup is a lot better for wikiing imho.
I wouldn't store the file format in the file extension; rather store metadata properly as metadata. Chances are that the application wants to hold a lot more metadata anyway, so you're going to need a metadata storage scheme anyway. (Yes, I am a lone crusader for eliminating metadata from filenames.)
- Managing pages in git/other vcs as plain text, using any editor I choose. I can commit pages using git or other vcs, don't have to use the browser to add pages.
- Writing pages in some markup language, maybe not markdown, as it is not expressive enough in some areas. Maybe markdown is possible for simple pages and the wiki knows it is markdown from the file extension, but the wiki also allows more powerful formats like restructuredText, which can be extended by the user.
- Server-side rendering of pages, that can easily be cached (since pages are files, one could easily check the shasum of the file to determin cache validity), which makes display of pages almost instant, as opposed to laggy shitty confluence.