info.yaml-format-info.md

@@ -1 +1,167 @@
-h
+confession time: i think yaml is actually ok for human-written structured data. which is what this is.
+
+upfront notes:
+- the string values are raw html so you have to escape <,>,& characters or whatever.
+- individual galleries specify whether they contain nsfw content or not and if they don't everything related to that is totally hidden. that's why nsfw things are marked everywhere.
+- hsyaml parses yaml 1.2 so bool fields have to be [case insensitive] true/false, not yes/no or whatever else used to be supported.
+
+the top level fields are ("?" means that that field is optional):
+
+- [`date`](#date)
+- [`sort`](#sort)? (string)
+- [`updates`](#updates)?
+- [`show-updated`](#show-updated)? (bool)
+- `title` (string)
+- [`artist`](#artist)?
+- [`nsfw-only`](#nsfw-only)? (bool)
+- [`tags`](#tags)? (list of strings)
+- [`nsfw-tags`](#tags)? (list of strings)
+- [`desc`](#desc)?
+- [`nsfw-desc`](#desc)?
+- [`images`](#images)
+- [`thumb`](#thumb)? (string)
+- [`bg`](#bg)? (string)
+- [`links`](#links)?
+- [`extras`](#extras)?
+
+## date
+
+exact dates are formatted `YYYY-MM-DD`. approximate dates can be either `YYYY-MM-DD?` for "somewhere around this date" or just `YYYY-MM` if all you remember is some time that month.
+
+for sorting, a `?` is ignored, and a month-only date is put at the start of that month.
+
+## sort
+
+an extra sort key, for if there are multiple posts on one day and you care what order they're listed in. if this isn't present then posts on the same day are sorted by title.
+
+## updates
+
+if you update a post you can say what changes you made and when. or you can just change the `date` field, im not your mother.
+
+anyway, the `updates` field is a mapping from dates (same format as [`date`](#date) above) to either strings or maps with fields `desc`, `nsfw`?, and `ignore-sort`?. examples:
+
+```yaml
+updates:
+  2021-08-24: tweak colours
+  2021-08-25: {desc: add lewd version, nsfw: true}
+  2021-08-26:
+    desc: |
+      this post will have the 25th in the gallery view
+      (or 24th in a sfw gallery)
+    ignore-sort: true
+```
+
+unlike most mapping fields this is just a normal map instead of a list of pairs (no `-`s), because the updates are sorted by date.
+
+## show-updated
+
+if present and set to `false`, then the gallery page will never treat this post as being updated, even if the `updates` field is present. it'll still have the date of the latest relevant update though.
+
+## artist
+
+if absent, it's you. otherwise, either just a single string for their name, or a map with name and url like:
+
+```yaml
+artist:
+  name: niss
+  url:  https://yummy.cricket
+```
+
+## nsfw-only
+
+if present and `true`, then only list this post in nsfw galleries, even if it has some sfw images. sometimes something is a bit borderline, idk
+
+## tags & nsfw-tags {#tags}
+
+a list of strings like `[colour, niss, nisse]`. gallery views let you filter by tag, so put anything in here that might be useful for that probably.
+
+## desc & nsfw-desc {#desc}
+
+the full form of these fields is as a map from arbitrary headings to html contents. for example on a character info page it might start:
+
+```
+desc:
+  name: niss
+  pronouns: she/her
+  height: 9 ft (275 cm)
+  # etc
+```
+
+if nsfw content is being shown, and both fields have any headings in common, then the the sfw and nsfw contents are appended together under the same heading.
+
+either or both can also be just an html string, in which case they are put under a heading "about".
+
+```
+# equivalent:
+desc: |
+  blablabla
+desc:
+  about: |
+    blablabla
+```
+
+## images
+
+ok so this one's complicated. i wanted to make it possible to say a lot, but leave it out when it's unnecessary.
+
+### image (singular)
+
+in its fullest form, a single image is a pair of a label and an object containing these four fields:
+
+```yaml
+- ':qtpats:':
+    path: qtpats.png
+    download: qtpats.svg
+    nsfw: false
+    warning: null
+```
+
+all the subfields except `path` are optional, and when they are all left out, then the value of the pair can be just the bare path:
+
+```yaml
+- transparent: taurex-t.png
+```
+
+the label is *also* optional. if it's left out then it's taken from the path, with the extension removed and all _ and - replaced with spaces:
+
+```yaml
+- normal.png
+```
+
+### categories
+
+an image list can be split into categories by having it be a list of name/list pairs, like:
+
+```yaml
+images:
+  - nisse: [1.png, 2.png]
+  - niss:  3.png
+```
+
+or the `images` field can just be a single list of uncategorised images. any of these image lists can just be a bare image if there only is one, like the `niss` category above. at its most basic, the entire `images` field can be a single filename.
+
+## thumb
+
+a single filename for the thumbnail used in gallery views. if left off, then the first sfw image listed is cropped to a square and used.
+
+## bg
+
+anything that can be the value of a css `background` property. a colour, a gradient, another image listed in `extras`, several of those, whatever. obviously if you go too crazy it starts becoming part of the image itself but whatever. it's optional, since it only matters for images with transparency.
+
+## links
+
+some links to whatever's relevant, like the original artist's post (if that's not what this is), art meme template, original for a paintover, or... :shrug:
+
+a list of pairs from title to url, or to `{url, nsfw}`:
+
+```yaml
+links:
+  - artist post: https://twitter.com/...
+  - artist post (lewd):
+      url: https://twitter.com/...
+      nsfw: true
+```
+
+## extras
+
+a list of other files that need to be uploaded. like images used in the description.