oxaliq.net/README

138 lines
6 KiB
Text
Raw Permalink Normal View History

2023-10-30 20:42:28 +00:00
--------------
2024-01-15 02:06:09 +00:00
| λ oxaliq.net |\
2023-10-30 20:42:28 +00:00
\--------------\ \
\______________\|
it's my personal home page.
it's for putting stuff on the web.
it's written in racket and serves (mostly) static html pages. there's some little
javascript in there - https://htmx.org/
why's there some javascript? because javascript is still kinda important to me??
mostly cause i think this htmx project is neat and allows me to do some cool things
without sending several megabytes. and the pages still work without allowing scripts.
so
________________
|----------------|
| HOW IT'S BUILT |
|----------------|
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
it's a racket web server that uses xml library to generate some valid html.
2023-12-14 03:14:10 +00:00
i write my little posts in xml-like s-expressions. (not for everyone! but i like the
expressivity!) someday, i might turn it into a proper dsl with support for htmx's
~funky~ syntax and a little more distance from it's host language, but not this day.
i make generous use of `racket/web-server` with a dispatcher for `hx/` prefixed content
(snippets of html), and plain `/` (for rendering full pages.) handlers build the
2024-01-22 01:14:54 +00:00
content from the little sexpr .scm files (they're not valid racket on they're own,
2023-12-14 03:14:10 +00:00
they get read and evaluated as data.) it's all real small and everything, but i figured
why not save the generated html in a `static/` directory so it doesn't need to be built
on each request? so that's what happens.
that's the server! it's compiled and hosted on bunk.computer. it's all very cute.
2023-10-30 20:42:28 +00:00
_________________
|-----------------|
| WHAT'S ON THERE |
|-----------------|
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
so, yea, it's all running over there and it's serving up some html (with a little dash
of javascript.) so what's on it?
2024-01-22 01:14:54 +00:00
right now, the plan's for
2023-10-30 20:42:28 +00:00
2024-01-22 01:14:54 +00:00
~UNSETTLED THOUGHTS~
2023-10-30 20:42:28 +00:00
it's like a blog. just thinking out loud. or talking about projects that aren't
ready to get their "tires kicked" yet
~SETTLED THOUGHTS~
it's like a portfolio. links to stuff. deployed stuff. pictures of stuff. a
2023-12-14 03:14:10 +00:00
home for everything that's done enough to need a home. or projects with
"minimally kickable tires"
2023-10-30 20:42:28 +00:00
2023-12-14 03:14:10 +00:00
~THOUGHTS ABOUT THOUGHTS?~
there's some "root" resources. yr typical about page, y'know with some
biographical information, or whatever. "errata" like:
~a page about the site itself.
~maybe a link page with some links to things i like or do as a person with other people
in the world
~a tag index and indices for tags
2023-10-30 20:42:28 +00:00
the structure of things is such that: there's no templating per se. if the request
has the path prefix "/hx/" you just get little snippets of html. the htmx is there to
stitch that stuff together. make sure yr browser insesrts the response where it
belongs in the page and i wipe my hands of the the thing. otherwise you get a page
stitched together from all the bits and bobs.
so don't be surprised if yr response is just an ~unsettled thought~ without any header
or footer or any of that fanciness.
_____________
|-------------|
| HOW TO POST |
|-------------|
¯¯¯¯¯¯¯¯¯¯¯¯¯
2023-12-14 03:14:10 +00:00
let's talk about the posting. so you write up a little bit of s-expressified xml-like
plain text works of astounding eloquence; how do you get the server to generate some
stuff for you? i wrote a little utility for that. it's called "publish" and it uses a
#lang package a friend made for making cli tools called
[cli](https://docs.racket-lang.org/cli/index.html)
the tool is called "publish" and it needs some flags to build a thing right.
2023-10-30 20:42:28 +00:00
```
2023-12-14 03:14:10 +00:00
$ publish -i in-progress/ex.txt \ # -i is for the input (i keep em in in-progress/")
-r unsettled \ # -r is for the resource "type" (see "WHAT'S ON THERE?")
-t ecology,art,computer \ # -t is for comma separated tags
-l "An Example Text" \ # -l is for head_l_ine (it means title)
-d "a short description-like a sentence long ideally"
# there's also an "-x" flag to do a "test run" before publishing. it'll generate
# stuff in publish-test/ including a "staging database" (it's csv files)
2023-10-30 20:42:28 +00:00
```
2023-12-14 03:14:10 +00:00
there's a couple things this'll do.
- first it'll take yr post and do some processing, add a footer with metadata and tags.
- it'll also update the "database" of csv files for the resource type and for all of
the associated tags.
- this generates new index files for the resource type, and the tags.
- if the post introduces a new tag, a new tag index gets made.
- the atom feed gets updated with the uri and the relevant info about the post.
(it's on the to-do list to embed the post in the feed, cause i like to read my rss
in cli, but i'm also a hypocrite that wants people to visit my page!)
- finally it moves the input file to an archive folder.
(in the future i'll make an update tool for posting updates to existing stuff!)
so that's simple enough.
2023-10-30 20:42:28 +00:00
2024-01-15 02:06:09 +00:00
______________________
|----------------------|
| HOW TO MODIFY A POST |
|----------------------|
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
so, some things aren't done til yr dead. some of those things might be posts. `publish`
is always going to move yr text into archive/ and you'll be able to move that file back
to in-progress/ when yr ready to start working on it again.
2023-10-30 20:42:28 +00:00
2024-01-15 02:06:09 +00:00
then you can use the "modify" tool. here's how it works
```
$ modify -i in-progress/ex.txt \ # -i is for the input
-r unsettled \ # -r is for the resource type
-l "An Example Text" \ # -l is for the head_l_ine (title)
```
you can't currently change the description or the tags on existing posts.
what this does:
- update the csv files for the resource type
- rebuilds the source with footer and metadata and tags
- update the atom feed, but this time with a "updated" tag in the entry
if at any point the script encounters a problem, any changes will be rolled back
2024-01-15 02:17:04 +00:00
2024-01-22 01:14:54 +00:00
_________
| LICENSE |
¯¯¯¯¯¯¯¯¯
the source code is available under GNU AGPLv3 : /LICENSE
the content (in source directory) is available under
CC-BY-SA-4.0 : static/license/license.txt
2024-01-15 02:17:04 +00:00