a guide to this gibberish
from @self's admin shit
welcome to gibberish.awful.systems, a platform for long-form writing and blogging hosted on awful.systems and running on WriteFreely. this is a place where users of our Lemmy instance can host text that would be clumsy as a Lemmy post, or which would benefit from the permanence of a blog.
if you're an awful.systems regular reading this and you don't have a gibberish account, contact me to get invited.
getting started
to get started, the WriteFreely writer's guide is ok. it covers some of the oddities of WriteFreely, like the first line of a post being the title (and also optional). another notable oddity is excerpt tagging by adding a <!--more-->
HTML comment to your document. there's a slightly better-organized writer's guide available too, but some of the functionality it describes (like image uploads) only apply to WriteFreely's paid flagship instance.
blog visibility
blogs and their posts are unlisted by default on this instance, meaning they won't show up on the instance Reader or be pushed to ActivityPub until you change your blog's visibility in its Customize page. this can be confusing since there's nothing telling you this is the case otherwise; check there first if something isn't showing up where it should.
writing drafts
WriteFreely has a drafts feature. it works fine for basic drafts, but has a number of drawbacks; see this post for a summary of those drawbacks and a workaround. drafts can also be used to make anonymous public posts, because WriteFreely loves spam and thinks we should have more of it.
customizing the fuck out of this thing
our instance has a unique feature: PRs merged into this repository cause our deployment to pull the files that make up its frontend from that repo. this can let us rapidly change how our instance looks and functions and fix a lot of jank. since this is for the frontend only, most of the files in the repo are irrelevant and are only there so we can easily merge upstream's changes back in. the relevant files for us are:
.woodpecker/push-to-prod.yaml
: check this out to see how we push to prod, and which Less files get compiled.pages
: this is a set of Gohtml/template
files defining some of the pages that make up the WriteFreely frontend.templates
: this is another set of Gohtml/template
files that defines a set of reusable templates that make up other pages, and the rest of the pages that make up the frontend.less
: these stylesheets are written in Less and get compiled by our CI before they get pushed to gibberish.static
: these static files get exposed verbatim by WriteFreely; this is where the CSS, Javascript, fonts, images, and (on the deployment end) compiled Less stylesheets used by the frontend live.
it's janky (we'll be saying that a lot), but one trick WriteFreely instances do for image hosting is put them in static/img
. we can do that within reason (our instance doesn't have a ton of disk space free, and eventually git will start to hate all the images), and maybe eventually just get a system working for uploading images to object storage.
the roadmap
being able to modify the frontend gives us quite a bit of flexibility. here are some ideas we can expand into if there's demand:
- full federation: WriteFreely itself only supports one-way federation, in that it knows how to push articles to ActivityPub but not how to pull in comments, boosts, or other events. there are a few somewhat easy ways to get full federation with just frontend changes to WriteFreely; one example is Hatsu.
- automatic dark/light theme switching
- less confusing navigation
- maybe some premade themes?
- your ideas here! no not really, go to the repo and put them there instead