[HN Gopher] Otter Wiki: A minimalistic wiki powered by Python, M...
___________________________________________________________________
Otter Wiki: A minimalistic wiki powered by Python, Markdown and git
Author : thunderbong
Score : 206 points
Date : 2024-10-05 13:28 UTC (4 days ago)
(HTM) web link (otterwiki.com)
(TXT) w3m dump (otterwiki.com)
| Terretta wrote:
| Not many wiki site engines based on Markdown work directly from
| git as cleanly as this.
|
| There's a few of them though, such as this old Ruby lang standby
| with a decade's worth of features that a decade ago was a way to
| host your same GitHub Pages site locally, supporting SSO:
|
| https://github.com/gollum/gollum
|
| https://github.com/gollum/gollum/wiki/Gollum-via-Rack-and-CA...
| oarsinsync wrote:
| Wikmd is another git / markdown / plain text file storage wiki.
|
| https://github.com/Linbreux/wikmd
|
| I can't remember why I switched from gollum to wikmd. I suspect
| installed size might be why.
| jauntywundrkind wrote:
| https://tina.io/ tinacms is very modern & well built, git
| markdown typescript. and headless or with template components.
|
| it's such an epic feat, how programmers have grown up to manage
| source over time & changes. i very much hope this richness cam
| extend beyond code some day, stop being arbitrary UI we craft &
| become good data structures that transcend each application.
| AlphaWeaver wrote:
| We actually switched from Gollum to OtterWiki!
| gglitch wrote:
| I really enjoyed Gollum for awhile, but I'm not a Rubyist, and
| past a certain point, every time I tried to run it or Jekyll I
| got dependency problems that I'd eventually solve, but without
| understanding. It was undoubtedly user error; I should
| definitely have learned and used rvm or something.
| dijksterhuis wrote:
| gitlab wikis -- separate repos to the main project repo that
| folks can clone/edit/push just like any repo.
|
| personally i prefer confluence though. just find it faster to
| dump things out.
| c0balt wrote:
| It should be noted that goolum is AFAIK still the backend
| behind GitLabs Wikis. It works quite well Ime and was easy to
| setup/use for basic Markdown Documents.
| ptman wrote:
| Ikiwiki is nice. It's also a static wiki compiler and tries
| very hard to minimize the amount of rebuilding for each edit.
| fiddlosopher wrote:
| An even older one is my gitit, started in 2008!
|
| https://hackage.haskell.org/package/gitit-0.15.1.2
|
| It doesn't limit itself to markdown, nor to git (you can use
| darcs, hg, or even sqlite). A bit long in the tooth, though --
| I stopped working on it once spam started to make self-hosted
| public wikis untenable.
| az09mugen wrote:
| The "Edit an Example!" link goes to Forbidden.
| babyoil wrote:
| If you login, you can edit
| apricot13 wrote:
| I've been playing around with dokuwiki recently but this looks
| promising.
|
| The irony I'm having is that I store some single file html
| documents alongside my notes and none of these engines (or
| obsidian) will render them!
| al_borland wrote:
| We use Confluence at work. It has the option to render HTML
| embedded in the page. I haven't tried to render a whole file
| attached to a page, but there might be a way to do that.
|
| I've used it a bit to add my own forms into pages to create
| little tools for people in docs.
|
| In the past we used Jive, and I had a rather involved HTML
| paged embedded there. I had to be careful with my CSS, as using
| any generic attribute level CSS would break the platform. I
| hope Confluence has protections against that, but haven't
| tested it, as I got in the habit of avoiding that issue all
| together.
| Tallain wrote:
| Every new wiki / knowledge management system I always compare
| against Confluence. I get the advantage of keeping your
| content in plaintext for portability but when I look back on
| how many times I've actually ported wiki content it's...
| maybe once? Most systems these days are handily capable of
| this, in any case.
|
| Anyway, Confluence for all its flaw has so much power, is so
| much more pleasant to use, your business folks won't balk at
| it. As often as not, we have people from all parts of the
| company in there, reading and writing both, and it needs to
| be usable to people of all technical levels. Markdown wikis
| and their editors don't often meet this criterion, or they're
| missing on some key features (tables!!).
|
| To me, Confluence's only real down side is that it's an
| Atlassian product. I wish I could find something to scratch
| the itch without feeling the need to buy into that whole
| ecosystem.
| oarsinsync wrote:
| > I get the advantage of keeping your content in plaintext
| for portability
|
| Portability is secondary for me. For me, the primary reason
| for keeping content in plain text is disaster recovery.
|
| When my systems are down, when my applications aren't
| working, if my documentation is also inaccessible, this
| makes things a lot harder.
|
| If my documentation is primarily in plain text / markdown,
| it's really easy to be able to read those docs again, even
| when everything else has fallen over.
| al_borland wrote:
| I've made some of my tools with this in mind, because
| they are for a team that has to keep functioning during a
| disaster recovery situation.
|
| I stubbornly kept the main page as HTML. All libraries
| are download and sourced locally, instead of using a CDN.
| I use as little server side as possible, and just use
| basic PHP when I must. The idea being that in a worst
| case scenario the users can simply open the index.html on
| their desktop had have 95% of the functionality. If they
| run something like xampp, they can get 100%. This app is
| basically their map to the rest of the infrastructure,
| with some helper tools. They'd be lost if it went down
| when they needed it most. That said, it's never come to
| this in 15 years and there have been several big DR
| events in that time. I still like having it as an option
| in my back pocket.
|
| I recently handed it off to someone else to manage. I
| should probably share this part of my philosophy as it
| seems like they are trending toward adding complexity and
| dependencies, because they're hip and cool.
| vaseko wrote:
| do you know a wiki where one can add metadata to the pages?
|
| I used https://foswiki.org and it was great for combining
| structured and non structured information
| SpecialistK wrote:
| I use Dokuwiki with the Struct plugin.
| prmoustache wrote:
| Isn't "poweredy by python" kind of defeating the purpose of using
| markdown and git? Well I don't mean python as a language, but
| python as running as a web service/app.
|
| Usually when your website is hosted on git as markdown files,
| that is because you'd rather have the website generation
| separated from serving the actual content to the public, i.e.
| having a secure and dead simple static website.
|
| If you start having to run a service/container, that generate the
| content on the fly and plan to edit the website using the
| browser, I don't really see the advantage of hosting the content
| on git vs a database. That database can be as simple and easy to
| host/backup/manage as a simple sqlite3 file and would still be
| more efficient than a git repo as a storage backend.
| suprjami wrote:
| No, this isn't always true.
|
| I have hated every WYSIWYG intranet my employer has used. I
| just want to write Markdown.
|
| Luckily, we also had access to a file server with ~/public_html
| and httpd with PHP.
|
| So I just threw PHP Markdown Extra and a htaccess file up, now
| I can write in Markdown and it magically works. If that was
| done with Python I wouldn't care either.
|
| (that old webserver has since been retired and the new one
| doesn't have PHP, so now I render locally with Pandoc and rsync
| my HTML files directly, sigh)
| emj wrote:
| I agree, there are two things I miss with markdown:
| import/export of text + media, multi user editing. This is
| always an extra step when you do not have and editing builtin
| in the Wiki that handles that. The "paste" image into
| document feature is one of the most useful features of a wiki
| if you want to write a fast bare bones tutorial.
| Tepix wrote:
| > _That database can be as simple and easy to host
| /backup/manage as a simple sqlite3 file and would still be more
| efficient than a git repo as a storage backend._
|
| With git you will have the latest version of the file in the
| filesystem, that must be more efficient than retrieving it from
| sqlite3, mustn't it?
| prmoustache wrote:
| I am not sure that retrieving it is the correct word. In term
| of efficiency you have to take into account the overhead of
| multiple files, some in cache, some not vs 1 single probably
| already cached file
|
| Also https://www.sqlite.org/fasterthanfs.html
| twic wrote:
| The purpose of using markdown is to make editing simple. The
| purpose of using git is to use a well-known and rock-solid
| history-preserving file store. Both of those purposes are
| orthogonal to method of delivery and tech stack used. So no.
|
| In general, i agree that static site generation is preferable
| to dynamic rendering where possible, because it makes for a
| much simpler and more secure deployment. But a wiki has to
| support editing of pages in the browser, and authentication of
| users before they can edit, and you need a backend for that.
| Also, if you want to support browsing of page history, a static
| site generator would need to render every version of the page
| upfront, which feels like a bad idea to me.
| Twisell wrote:
| It's minimalist until you read the installation part...
|
| As a backend SQL guy I always feel overwhelmed by "minimalist"
| software that actually depend on me knowing ho to deploy safely
| on docker or mastering N dependencies before actually having
| something to try. Long are gone the lamp days... they had their
| own set of problems (wrong versions!) but it was a simpler time
| where you felt a little bit more in control.
|
| Old man yell at the clouds I guess...
| castlec wrote:
| Its comprehensive. It is not complex. They just show all of the
| typical ways one would want to deploy.
| al_borland wrote:
| I often feel the same way. I had someone ask me to make a
| microservice on some platform she built. I was told it would
| take 10 minutes. In reality, it took a couple weeks, and then
| every week for a year I was getting told something was changing
| and I had to mess with this or that, and also attend daily
| meetings about the project. 10 minutes turned into 30% of my
| whole year. The whole platform she built lasted maybe 2 years
| before it was decided we needed to move on from it. It was a
| total waste of time.
|
| Meanwhile, I have a little LAMP project that is used
| significantly more than the micro service, that I've run for 15
| years that I only have to touch when it needs feature updates.
| The platform itself just works. Occasionally I'll need to move
| to a newer OS, which takes a few hours to get the new server
| built, run the job to configure it (doing it manually doesn't
| take too much longer), then submit a request to change the load
| balancer to point to the new servers.
|
| Granted, some of this comes down to experience. However,
| needing to know all the tools involved for the microservice was
| much more annoying and they broke half the time.
| klaussilveira wrote:
| Boring technology just works. That's why it is boring and not
| appealing to younger developers.
|
| https://boringtechnology.club/
| rcarmo wrote:
| I can't see any issue with what's in the installation part. It
| all looks very straightforward for _each_ installation method.
| SansGuidon wrote:
| come on, you just need to teach a bit of
| git/k8s/docker/tls/proxies/storage/vault/markdown/linux/apt and
| then your family will be autonomous at managing this wiki _IF_
| you are allowed to take vacations.
| simonw wrote:
| I got it running locally like this, using uv to manage
| dependencies: git clone
| https://github.com/redimp/otterwiki.git cd otterwiki
| mkdir -p app-data/repository git init app-
| data/repository echo "REPOSITORY='${PWD}/app-
| data/repository'" >> settings.cfg echo
| "SQLALCHEMY_DATABASE_URI='sqlite:///${PWD}/app-data/db.sqlite'"
| >> settings.cfg echo "SECRET_KEY='$(echo $RANDOM |
| md5sum | head -c 16)'" >> settings.cfg export
| OTTERWIKI_SETTINGS=$PWD/settings.cfg uv run --with
| gunicorn gunicorn --bind 127.0.0.1:8080 otterwiki.server:app
|
| I filed an issue here suggesting that for the docs
| https://github.com/redimp/otterwiki/issues/146 - and also that
| it would be great if getting started could be as simple as
| this: pip install otterwiki otterwiki
| \ --repository app-data/repository \
| --sqlite app-data/db.sqlite \ --secret-key secret1 \
| --port 8080
| oarsinsync wrote:
| And to think people used to think ./configure
| ---prefix=/home/user/appname make make install
|
| was too complicated
| rcarmo wrote:
| I got it to work under Piku (https://piku.github.io) in much
| the same way (since I support uwsgi, that bit was trivial).
|
| I did have to hardcode the data path, and I think having some
| form of export/snapshot would help as well, but submitting a
| patch might be a fun weekend project.
| mock-possum wrote:
| Yeah I'm with you. I cannot stand having to jump through hoop
| after hoop just to get started - things to download, command
| line utils to install, line after line after line to copy into
| the terminal, layers and layers of dependencies, possibly with
| version incompatibilities that the "getting started" page was
| never updated to reflect... it's a nightmare.
|
| Sometimes you just want to sit down and write code and see it
| working.
| nine_k wrote:
| But deploying on Docker _is_ simpler than LAMP! All
| dependencies included. All binaries included. You can even just
| tell systemd run it (also usually included).
| tripple6 wrote:
| Is there anything git-based like this having semantic web stuff
| support similar to Semantic MediaWiki?
| rcarmo wrote:
| I like it. My site (taoofmac.com) is also git/python-backed,
| although not live editable.
| joedevon wrote:
| I ran https://wave.webaim.org/ against the homepage, saw 11
| errors right off the bat, and decided not to look at further.
|
| Particularly for this kind of project, though as an accessibility
| person I'd argue every project, accessibility is table stakes.
| rcarmo wrote:
| You could, perhaps, consider filing an issue or fixing some
| low-hanging fruit.
| diggan wrote:
| Is there something similar but instead of being minimalistic
| mediwiki alternative, it's a minimalistic wikibase alternative?
| emanuele-em wrote:
| quite sure that is my limit but what is the difference between
| this and other "md compiler" projects (or ssr) like
| <https://github.com/rust-lang/mdBook>? Anyway this seems to work
| very well, so congrats!
| strunz wrote:
| I love this, but so many of these are missing or have a half
| baked Annotations feature. I've been looking for something that
| that for years and none of them work well for this purpose.
| Mediawiki, Dokuwiki, Xwiki, etc.
| com wrote:
| Can you explain what you need in annotations that doesn't exist
| in these wikis?
| atebyagrue wrote:
| I was literally building my own version of this with madness this
| morning to go from Obsidian to web in my workflow. Thanks for
| speeding things up for me. Great work!
| bityard wrote:
| Huh! This is really nice! If I had run across this sooner, I
| might not have wrote my own very similar wiki.
| (https://github.com/cu/silicon)
|
| Otter is much nicer, though.
| Tepix wrote:
| Looks good. I like the small memory footprint a lot!
|
| It would be nice to have a WYSIWYG text editor for the markdown
| or to have a live preview next to the markdown.
| Workaccount2 wrote:
| I have a hard time using the word "minimalisitc" to describe any
| site that requires javascript to function.
| regisso wrote:
| I've been using it for while, recommended.
| zhynn wrote:
| Or you could just use fossil...
| neves wrote:
| Here's why I didn't access the link: I'm never interested in any
| product that the main feature is the technology it uses.
|
| Which problem does it solve? Not how it is made.
| nine_k wrote:
| Why, how it's made is also its interface, and its operational
| requirements. Both are important.
|
| - Markdown: widely used, readable, well-supported by other
| tools.
|
| - Git: ubiquitous, well-supported, likely already present and
| set up.
|
| - Python: ubiquitous, well-supported, easy to read and hack on;
| sometimes a pain to deploy.
|
| If the above is not relevant for you, well, you'd be better
| served with opaque one-click-installable apps from App Store.
| Not bad, just different.
| simonw wrote:
| The title here was an editorial choice by the person who
| submitted this link to Hacker News.
| INTPenis wrote:
| My definition of minimalistic is a SSG where you use Github's
| WYSIWYG editor and push changes to trigger a pipeline that
| rebuilds the page and uploads it to a cloud service with S3
| support.
| nine_k wrote:
| Involving GitHub and setting up its actions is only minimalist
| from a very particular point of view.
| INTPenis wrote:
| Well, in real life this setup uses Gitlab but I referenced
| Github because I assumed they have better WYSIWYG options
| than Gitlab.
|
| And why that matters is because I can run the pipeline from
| my own laptop with gitlab-runner.
|
| But we all have our own view of minimalistic and mine is "the
| less code is running, the more minimalistic it is". To be
| abundantly clear, the less code is running that I have to
| operate or maintain. Obviously Github, S3 and a SSG generator
| is a lot of code.
| ElectricalUnion wrote:
| If you're really going for "minimalistic", why not ignore the
| whole build/SSG and just directly link to a markdown file
| inside a github repository?
| candleknight wrote:
| > First of all, there are no otters here. I'm utterly sorry about
| that.
|
| incredibly important suggestion: replace "utterly" with "otterly"
| monacobolid wrote:
| I see no backlinks, no "what links to here" section.
___________________________________________________________________
(page generated 2024-10-09 23:01 UTC)