highly WIP initial commit

15 files changed, 668 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..90e9798
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+.obsidian
+.DS_Store
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d4d59ef
--- /dev/null
+++ b/README.md
@@ -0,0 +1,7 @@
+# hsmusic-docs
+
+Hey hi! This is an extremely WIP project right now. Since the actual organization of the whole thing is still very much in flux, you're basically on your own exploring this. Check out any of the Markdown files in the file browser and enjoyyyy!
+
+Proper organization coming... soon... but probably not before most of the main content is done...
+
+See the #documentationification channel in the community Discord server.
diff --git a/documents/album.md b/documents/album.md
new file mode 100644
index 0000000..adf0e0c
--- /dev/null
+++ b/documents/album.md
@@ -0,0 +1,88 @@
+# Album Format
+
+Album documents are stored each in its own file, alongside all the tracks associated with that album, at `album/<directory>.md`. Albums are represented by the first document in an album file, with all the rest being track (or track section) documents.
+
+A typical album file will, in its entirety, look something like this:
+
+```yaml
+# /path/to/data...   /album/homestuck-vol-7.yaml
+Album: 'Homestuck Vol. 7: At the Price of Oblivion'
+Directory: homestuck-vol-7
+Date: May 31, 2011
+---
+Section: Main album
+---
+Track: Black Rose / Green Sun
+Artists:
+- Malcolm Brown
+# ...
+---
+Track: At The Price of Oblivion
+# ...
+---
+Section: Bonus tracks
+---
+Track: Maplehoof's Adventure
+Artist: Michael Guy Bowman
+# ...
+```
+
+## Album documents
+
+Referenced as `album:directory`; extra links: `[[album-commentary:directory]]`, `[[album-gallery:directory]]`.
+
+### Essential info fields
+
+* `Album`: album name
+* `Directory`: unique identifier among other albums
+  * This is used for the URL the album will be accessed at: https://hsmusic.wiki/album/DIRECTORY/
+  * Groups and other wiki objects reference an album by its directory: `album:DIRECTORY`.
+  * This is usually generated automatically from the album's name. [Learn more.](../guidelines/common-fields.md#directory-field)
+  * Just for albums, the directory should match the filename, e.g. *Homestuck Vol. 5* automatically gets the directory `homestuck-vol-5` and its data is saved in the file `album/homestuck-vol-5.yaml`. (The filename isn't actually processed for any data purposes, it's just easier to navigate if it matches the directory.)
+* `Date`: album release date
+* `Cover Art Date`: date cover art created/added, if different from album release date
+* `Date Added`: date album added to wiki
+* `Color`: theme color representing album
+* `URLs`: web URLs for album playback or purchase
+
+### Content fields
+
+* `Commentary`: album-wide commentary from anyone involved in making it
+  * Learn more
+* `Additional Files`: bonus files associated with the album, e.g. album booklet, sheet music, credits files
+
+### Configuration & layout
+
+* `Has Cover Art`: display album main cover art (default: true)
+* `Has Track Art`: display unique art for each track, instead of inheriting from the album cover (default: true)
+* `Has Track Numbers`: display track numbers in main track listing and sidebar (default: true)
+* `Listed on Homepage`: include this album in automatically generated listings on the main homepage (default: true)
+* `Listed in Galleries`: include this album in automatically generated group gallery pages (default: true)
+* `Default Track Cover Art Date`: date track art created/added, if different from album release date; provides default which may be overridden by a track's `Cover Art Date` field
+* `Cover Art File Extension`: corresponds to media file (`cover.jpg`, `cover.png`)
+* `Track Art File Extension`: corresponds to media files; provides default which may be overridden by a track's `Cover Art File Extension` field
+
+### Relational fields
+
+* `Artists`: compositional artists who were largely responsible for the entire album, usually used for solo albums
+* `Wallpaper Artists`: visual artists who created the album's wallpaper art; setting this enables displaying custom wallpaper art for the album
+	* `Wallpaper Style`: CSS property/values to apply to the wallpaper for light tweaks of the original asset
+	* `Wallpaper File Extension`: corresponds to media file (`bg.jpg`, `bg.png`)
+* `Banner Artists`: visual artists who created the album's banner art; setting this enables displaying a banner for the album
+	* `Banner Style`: CSS property/values to apply to the banner for light tweaks of the original asset
+	* `Banner File Extension`: corresponds to media file (`banner.jpg`, `banner.png`)
+	* `Banner Dimensions`: precise dimensions of banner image file e.g. `1100x158` (used to avoid layout shift when loading album page)
+* `Cover Artists`: visual artists who created the album's cover artwork
+* `Default Track Cover Artists`: visual artists who were largely responsible for the entire album's track artworks; may be overridden by a track's `Cover Artists` field
+* `Groups`: links album to group documents, which generally represent bands, online communities, specific projects, etc
+* `Art Tags`: art tags representing characters or features present in the album's cover artwork
+
+## Track section documents
+
+* `Group`: track section name
+* `Color`: color-codes track sections if specified
+* `Date Originally Released`: default applied to tracks in this section
+
+## Track documents
+
+See [Track Format](track.md).
diff --git a/documents/art-tag.md b/documents/art-tag.md
new file mode 100644
index 0000000..fbfaf7e
--- /dev/null
+++ b/documents/art-tag.md
@@ -0,0 +1,12 @@
+# Art Tag Format
+
+Art tag documents are stored all in one file, `tags.yaml`, one document (entry) per tag.
+
+## Art tag documents
+
+Referenced as `tag:directory`.
+
+* `Tag`: art tag name
+* `Directory`: unique identifier among other art tags
+* `Color`: theme color representing art tag
+* `Is CW`: specify to identify tag as a content warning
diff --git a/documents/artist.md b/documents/artist.md
new file mode 100644
index 0000000..38fa1ad
--- /dev/null
+++ b/documents/artist.md
@@ -0,0 +1,17 @@
+# Artist Format
+
+Artist documents are stored all in one file, `artists.yaml`, one document (entry) per artist.
+
+## Artist documents
+
+Referenced as `artist:directory`; extra links: `[[artist-gallery:directory]]`.
+
+* `Name`: artist name
+* `Directory`: unique identifier among other artists
+* `URLs`: web URLs where the artist can be visited
+* `Context Notes`: pertinent info about the artist
+
+* `Has Avatar`: enable displaying avatar (from `artist-avatars` in media directory)
+* `Avatar File Extension`: corresponds to media file
+
+* `Aliases`: list of earlier or non-primary names the artist has gone by
diff --git a/documents/common-fields.md b/documents/common-fields.md
new file mode 100644
index 0000000..658b786
--- /dev/null
+++ b/documents/common-fields.md
@@ -0,0 +1,76 @@
+# Common Fields
+
+## `Directory` field
+
+[*See also: Guidelines for the Directory field.*](../guidelines/common-fields#directory-field)
+
+When **declaring** a wiki object...
+
+* A directory is the unique identifier for a given wiki object, differentiating it from other objects of the same type.
+  * It's possible for two objects of *different* types to have the same directory, e.g. a group's eponymous album, or an art tag which incidentally has the same name and directory as an unrelated artist.
+
+* Directories are important to actual page generation: they tell what subdirectory a given wiki object's page will be served at / written to. (Hence the name!)
+  * For example, Land of Fans and Music 4's directory is `lofam4`, so anybody can access this album's wiki webpage at [https://hsmusic.wiki/album/<b>lofam4</b>/](https://hsmusic.wiki/album/lofam4/).
+
+* Directories can be manually specified, and inherit from a wiki object's name otherwise. Best practice is generally to write them in "kebab-case", which means words are all lowercase and joined together by dashes / "minus" signs (`-`).
+  * If a directory isn't specified manually, it follows this algorithm:
+    1. Replace the spaces (` `) in the object's name with dashes (`-`).
+    2. Replace any instances of "&" with "and".
+    3. Discard any characters that aren't alphanumeric (or dashes).
+    4. Replace consecutive dashes with just one dash (such as between strings of characters that were entirely removed).
+    5. Discard dashes at the start or end.
+    6. Make all remaining alphabet characters lowercase.
+  * There are two main circumstances when a directory should be written manually: when there are multiple similarly named objects which need unique directories to differentiate them, and when an object's name doesn't lend well to the English-centric "`getKebabCase`" algorithm.
+    * The way otherwise identical directories are differentiated will vary for each wiki (and often by further context). Some options include: differentiate tracks by shorthand album name, like `frost-vol6` vs `frost-medium`; differentiate albums by artist/band or year, like `homestuck-swagazaki`; differentiate artists by a longer unique username, like `kobacat` vs `kobacake`.
+    * `getKebabCase` doesn't even try to support languages outside English effectively. If a name includes accents or punctuation which have a particular "ascii-fied" variant that is appropriate, that should be specified by hand. Lots of examples in HSMusic's artist data, e.g. `magnus-palsson` (Magnus Pålsson), `pokemon` (Pokémon), `satoru-kosaki` (Satoru Kōsaki).
+
+When **referencing** a wiki object...
+
+* Directories are used to create links between wiki objects. Most references take effect in both directions, but are only declared in one direction.
+  * Example: A track page links to the track's artists, and those artists' pages each link back to the track; but those bidirectional references are only written in data files once, as the track lists its own artists, and each artist automatically computes which tracks include that artist in their artist lists.
+
+* Most references are listed with an *object reference type*, a colon (`:`), and the object's directory.
+  * Example: The album "Homestuck Vol. 6: Heir Transparent" has a manually written directory, `homestuck-vol-6`. YAML fields will reference this album as `'album:homestuck-vol-6'`. (Quotation marks are needed so it isn't treated as a YAML object, i.e. `{"album": "homestuck-vol-6"}`.)
+  * Example: The track "Let's All Rock the Heist" doesn't have a manual directory, so it inherits from its name. YAML fields will reference this track as `'track:lets-all-rock-the-heist'`.
+
+* When linking to an object from commentary and other static content, the same basic syntax is used, but with double square brackets (`[[hello world]]`) surrounding the reference. You can also use a pipe / vertical bar symbol (`|`) to show different link text than the object's actual name.
+  * Example: `[[album:homestuck-vol-6]]`, `[[track:lets-all-rock-the-heist]]`
+  * Example: `[[group:umspaf|UMSPAF]]` (shows "UMSPAF" instead of "Unofficial MSPA Fans")
+  * Some wiki objects are represented by multiple pages (one of each type, e.g. info, gallery). See object format pages for info; replace the object reference type with the special string, for exmaple: `[[group-gallery:fandom]]`. When using the plain object reference type, the default is generally the "info" page.
+
+* References may generally also be written as just the object's name. This is accepted as long as it's not ambiguous; if two objects (of the same type) share the same name, HSMusic will output an error letting you know to replace it with a `type:directory`-style reference.
+  * In commentary and other static content, this works for tracks only, e.g. `[[Creata (Canon Edit)]]`.
+
+## Static content
+
+* A variety of fields across wiki data objects represent longer blocks of text, which are called "static content" or "multiline content". YAML has a number of ways to represent multiline strings, but generally a pipe and dash (`|-`) followed by a line break and the content indented is the way to go.
+
+```yaml
+Lyrics: |-
+    Hello, world
+    Hello, world
+    Oh! hello, world
+```
+
+* Content tags can be used to insert links and (build-time) dynamic content. These usually use double square brackets, a "replacer tag", and a value. More complex syntax can be used for tags which take a variety of arguments.
+
+```
+This song is by [[artist:rick-astley]].
+Want to listen to [[track:stone-halation|my favorite track]]?
+
+[[string:artistPage.contributedDurationLine
+  * artist = [[artist:quasar-nebula]]
+  * duration = not even a moment]]
+```
+
+* Line breaks in static content generally represent paragraph breaks, with the exception of `Lyrics` fields, where a full empty line is used to split verses.
+
+* Static content also supports very basic (non-nesting) block styling.
+  * Put `> ` at the start of a series of lines to turn them into a blockquote.
+  * Put `* ` to turn them into items of an unordered list.
+
+## Commentary
+
+* Commentary is [static content](#static-content).
+
+* A given commentary field can contain multiple artists' commentary; each artist's commentary should have the header `<i>Artist Name:</i>`. This string is automatically matched and displayed on the artist's info page.
diff --git a/documents/flash.md b/documents/flash.md
new file mode 100644
index 0000000..96ac9a1
--- /dev/null
+++ b/documents/flash.md
@@ -0,0 +1,57 @@
+# Flash Format
+
+Flash documents are stored all in one file, `flashes.yaml`, one document (entry) per flash. They're grouped by flash act documents.
+
+The website section for flashes is called "Flashes & Games". Apart from this, these data objects are always called flashes.
+
+The flashes file will, in its entirety, look something like this:
+
+```yaml
+Act: Act 1 - The Note Desolation Plays
+Anchor: a1
+Color: '#7799ff'
+Jump: Side 1 (Acts 1-5)
+Jump Color: '#4ac925'
+---
+Flash: 'John: Examine games on CD rack.'
+Page: '31'
+Date: April 16, 2009
+Featured Tracks:
+- Problem Sleuth Theme
+# ...
+---
+Act: Act 6 Intermission 3 - Ballet of the Dancestors
+Anchor: a6i3
+Color: '#b536da'
+---
+Flash: '[S] ACT 6 INTERMISSION 3'
+Page: '5263'
+Date: August 31, 2012
+Contributors:
+- Killian Ng (art)
+- Xamag (art)
+# ...
+```
+
+## Flash documents
+
+Referenced as `flash:directory`.
+
+* `Flash`: flash name
+* `Directory`: unique identifier among other flashes (inherits from Page before Name)
+* `Page`: page number on https://homestuck.com
+* `URLs`: web URLs for flash playback (or game purchase)
+
+* `Date`: flash posting/release date
+* `Cover Art File Extension`: corresponds to media file
+
+* `Featured Tracks`: tracks that play (in full or part) as part of the flash
+* `Contributors`: artists who contributed directly to flash, e.g. art media, programming
+
+## Flash act documents
+
+* `Act`: act name
+* `Color`: theme color representing act
+* `Anchor`: unique identifier among other acts
+* `Jump`: title of quick link on Flashes & Games index
+* `Jump Color`: color of quick link on Flashes & Games index
diff --git a/documents/group.md b/documents/group.md
new file mode 100644
index 0000000..e65f9fe
--- /dev/null
+++ b/documents/group.md
@@ -0,0 +1,44 @@
+# Group Format
+
+Group documents are stored all in one file, `groups.yaml`, one document (entry) per group. They're further categorized by group category documents.
+
+The groups file will, in its entirety, look something like this:
+
+```yaml
+Category: HSMusic
+Color: '#0088ff'
+---
+Group: Official Discography
+Directory: official
+# ...
+---
+Group: Fandom
+# ...
+---
+Category: Fan-musician groups
+Color: '#ffec14'
+---
+Group: Homestuck Gaiden
+URLs:
+# ...
+---
+Group: Unofficial MSPA Fans
+URLs:
+# ...
+```
+
+## Group documents
+
+Referenced as `group:directory`; extra links: `[[group-gallery:directory]]`.
+
+* `Group`: group name
+* `Directory`: unique identifier among other groups
+* `Description`: any-length description of the group (use `<hr class="split">` for paragraphs beyond the brief summary)
+* `URLs`: web URLs where the group can be visited
+
+* `Featured Albums`: optional list of "featured" albums; if present, displayed in a carousel on group gallery page
+
+## Group category documents
+
+* `Category`: group category name
+* `Color`: color for category and all included groups
diff --git a/documents/homepage-layout.md b/documents/homepage-layout.md
new file mode 100644
index 0000000..c8ee45e
--- /dev/null
+++ b/documents/homepage-layout.md
@@ -0,0 +1,64 @@
+# Homepage Layout Format
+
+The homepage layout file has a header document describing details about the overall homepage structure, then a document for each "row" in the main content area.
+
+Homepage layout documents affect only the homepage. Refer to [Wiki Info Format](wiki-info.md) for options that customize the appearance or behavior of an entire wiki.
+
+The homepage layout file will, in its entirety, look something like this:
+
+```yaml
+Sidebar Content: ...
+Navbar Links: ...
+---
+Row: Official Discography
+Type: albums
+Display Style: carousel
+# ...
+---
+Row: New Additions
+Type: albums
+Display Style: grid
+# ...
+```
+
+## Homepage layout - header document
+
+* `Sidebar Content`: multiparagraph text/content to be show in homepage sidebar box
+  * This supports content links, image embeds, etc just like any other multiline content area.
+  * The special text `[[news]]` will be replaced with a small section for the latest news entries.
+
+* `Navbar Links`: links to show in homepage navigation bar
+  * These must all be inline links without any additional text (the title of the link can be customized, though).
+  * Examples: `[[static:discord]]`, `[[listing-index:-|Listings]]`
+
+## Homepage layout - row documents
+
+All row documents accept the following options:
+
+* `Row`: title to display above row contents
+* `Color`: custom color for links in content
+
+* `Type`: specify basic kind of content being displayed & access additional related fields
+  * There's currently only one supported row type, `albums`. More will probably be added in the future.
+
+### `Type: albums` row documents
+
+* `Display Style`: `grid` (default) or `carousel`
+  * `grid` displays albums with the same basic layout as gallery pages.
+    * The grid layout on the homepage is currently hard-coded in CSS. Sorry!
+    * 2 rows of 3 larger grid items, then any number of rows of 4 smaller grid items.
+  * `carousel` shows a slowly wrap-scrolling, shorter but wider grid of albums.
+    * Carousel reels have some niche sizing particulars (see `carouselLayoutMap`), but basically fit 4 to 18 items and display them across 1 to 3 rows (preferring 2) and 4 to 6 columns (avoiding blank space).
+    * The items in a carousel scroll automatically but all of them are always visible at once. The left edge wraps precisely "around the back" to the right edge.
+
+* `Group`: group to pull most recent albums from if paired with `Count`; special values: `new-releases`, `new-additions`
+  * Special value `new-releases`: pull the latest albums chronologically released (by `Date`), regardless of when they were added to the wiki
+  * Special value `new-additions`: pull the albums most recently added to the wiki (by `Date Added to Wiki`), regardless of when they were chronologically released
+* `Count`: number of albums to pull (if paired with `Group`)
+
+* `Albums`: manual list of albums to display
+  * If both (dynamic) `Group`/`Count` and (manual) `Albums` are specified, the (manual) `Albums` will show up at the end of the list. They don't count towards `Count`, i.e. if you want 12 albums in total and two of them are manually specified, set `Count` to 10.
+
+* `Actions`: list of quick links to display at end of grid or below carousel
+  * Like `Navbar Links` in the header document, these must all be inline links.
+  * Example: `[[group-gallery:official|Explore Official!]]`
diff --git a/documents/news.md b/documents/news.md
new file mode 100644
index 0000000..b019572
--- /dev/null
+++ b/documents/news.md
@@ -0,0 +1,12 @@
+# News Format
+
+News documents are stored all in one file, `news.yaml`, one document (entry) per news entry.
+
+## News entry documents
+
+Linked as `[[news-entry:directory]]`.
+
+* `Name`: news entry name
+* `Directory`: unique identifier among other news entries
+* `Date`: date of news entry posting
+* `Content`: news entry body (use `<hr class="split">` for "read more" link)
diff --git a/documents/static-page.md b/documents/static-page.md
new file mode 100644
index 0000000..e47a0c5
--- /dev/null
+++ b/documents/static-page.md
@@ -0,0 +1,13 @@
+# Static Page Format
+
+Static page documents are stored each in its own file, at `static/<directory>.md`.
+
+## Static page documents
+
+Linked as `[[static:directory]]`.
+
+* `Name`: static page name
+* `Short Name`: for use in e.g. homepage navigation bar
+* `Directory`: unique identifier among other static pages
+* `Style`: extra CSS pertinent to this page's content
+* `Content`: full content of static page
diff --git a/documents/track.md b/documents/track.md
new file mode 100644
index 0000000..f4af6a0
--- /dev/null
+++ b/documents/track.md
@@ -0,0 +1,93 @@
+# Track Format
+
+Track documents are stored in album files; after the album header document, use `Track: (Track Name)` to start a track document.
+
+> Certain fields inherit from the album the track is part of. **Save time by using the corresponding album field, if most of the tracks in an album share the same value** (differing from wiki default):
+>
+> * track's `Artists` inherits from album's `Artists`
+> * track's `Cover Artists` inherits from album's `Default Track Cover Artists`
+> * track's `Cover Art Date` inherits from album's `Default Track Cover Art Date`, default: album release date
+> * track's `Cover Art File Extension` inherits from album's `Track Art File Extension`, default: `jpg`
+> * track's `Has Cover Art` inherits from album's `Has Track Art`, default: `true`
+
+## Track objects
+
+Referenced as `track:directory`.
+
+* `Track`: track name
+  * See [Album & Track Guidelines](../guidelines/albums-and-tracks.md#name-field).
+
+* `Directory`: unique identifier among other tracks
+  * This is used for the URL the track will be accessed at: https://hsmusic.wiki/track/DIRECTORY/
+  * Tracks and other wiki objects reference a track by its directory: `'track:DIRECTORY'`.
+  * If this isn't provided, it will automatically be generated from the title similarly to how Bandcamp works. It's tuned for English titles, so most other languages are best off specifying the directory manually.
+  * Guideline: Use all lowercase, avoid non-ASCII characters, and reflect how a human reads the title: "Riches to Ruins Movements I & II", `riches-to-ruins-movements-i-and-ii`. Exercise some leeway for troll typing quirks: "We Are +og3th3r", `we-are-tog3th3r`.
+  * Guideline: Directories are always unique for each of a given type of document. If two tracks would have the same directory, distinguish by album or else artist: `disc-1-lofam4`, `i-dont-want-to-miss-a-thing-aerosmith`.
+  * Note: We don't currently have set guidelines for Japanese and other non-Latin scripts. (Compare: 暗闇の中の光, `light-in-the-darkness`, and がんばってＤＡＶＩＤさん, `vaporwave-2016-track11`.)
+
+* `Duration`: track listening duration
+  * **Examples:**
+    * `0:57` (57 seconds)
+    * `4:13` (4 minutes, 13 seconds)
+    * `3:05:20` (3 hours, 5 minutes, 20 seconds)
+  * If this isn't provided, track listings will display as `(_:__)`, and the track will be treated as zero seconds long (no duration).
+  * Guideline: If a track doesn't have a clear-cut duration (e.g, dynamic loops ripped from old console games), it's probably best to leave it as unset.
+
+* `Date First Released`: date of original release for tracks that were made available prior to album release (and other special cases)
+  * Guideline: This is pretty much exclusively for organization purpose on artist pages, where it doesn't make sense to chronologically position a track at one time when it was first released years earlier. At this point, it's mostly defunct, since we have the "Originally Released As" feature for cataloguing specific releases (which displays more cleanly in the artist chronology, too). However, it may still be used in certain cases where there isn't another album release that has the relevant date.
+    * For example, compilation album [The Funk McLovin Homestuck Experience](https://hsmusic.wiki/album/the-funk-mclovin-homestuck-experience/) uses `Original Date` for each track's earlier release on YouTube.
+    * The 2019 re-release of [One Year Older](https://hsmusic.wiki/album/one-year-older/) includes a bonus track, [it's good to see you again](https://hsmusic.wiki/track/its-good-to-see-you-again/). Rather than create a whole new album with basically the same structure, an additional group ("2019 release") was added with the single new track, which is `Original Date`'d as a *later* date than the rest of the album, placing it correctly in Erik Scheele's track chronology.
+    * All this is subject to change according to whatever form the upcoming "multiple releases" feature takes.
+
+* `Cover Art Date`: date cover art created/added, if different from track/album release date
+  * If left unspecified, inherits from the track's *manually specified* `Date First Released`; or the album's `Default Track Cover Art Date` field; or the album's original date.
+  * This is displayed on track info pages only when different from the track's own release date.
+  * Guideline: This is mostly used for digital track art anthologies, where fans come together to add original artworks to an album released without art.
+  * Subject to change with upcoming "multiple artworks" feature.
+
+* `Cover Art File Extension`: corresponds to media file
+  * Don't include the "." separator: `Cover Art File Extension: png`, not `.png`.
+  * If left unspecified, inherits from the album's `Track Art File Extension` field (*not* the album's `Cover Art File Extension`), or `jpg` by default.
+
+* `Has Cover Art`: disable to inherit from album cover art, or enable for one track with unique art amongst an album mostly without
+  * If left unspecified, inherits from the album's `Has Track Art` field, which is true by default.
+
+* `Lyrics`: vocal lyrics
+  * Guideline: Include the whole lyrics verbosely, instead of shorthands like "[2x Chorus]".
+  * Guideline: Insofar as vocal lines can be discerned from instruments, try to transcribe everything, including non-"music" lines, quiet vocals, optionally echo effects, etc
+  * Guideline: Just ask Niklink for decision making on any lyrics, he's to credit for pretty much all lyrics present on the site ATM lol
+
+* `Commentary`: commentary from track artists and others related
+  * See (TODO) Commentary Format
+
+* `Additional Files`: bonus files associated with the track, currently unused
+  * See (TODO) Additional Files Format
+
+* `Originally Released As`: links track to its earliest release
+  * Generally, this should be used instead of `Date Originally Released`, not alongside.
+  * Tracks with this field are displayed on the wiki as "re-releases", dimmed out a little in chronological listings (such as the list of tracks that an artist composed).
+  * Subject to change with upcoming "multiple releases" feature.
+
+* `Referenced Tracks`: links track to musical references, usually by leitmotif
+  * Guideline: List references by the order they are first present in the track; don't list an identical reference twice.
+  * Often these are listed on Bandcamp pages already, and can be sourced from there, especially if you aren't familiar with the musical material being referenced.
+
+* `Sampled Tracks`: links track to direct audio samples, often (but not exclusively) vocal clips
+  * This feature is mostly unused right now.
+
+* `Artists`: links track to its compositional artists
+  * May include parenthical descriptions, e.g. `'L. L. Zamenhof (lyrics)'`.
+  * Guideline: The line between "artists" and "contributors" is grey, and internally, it's an arbitrary distinction. "Artists" generally refers to people who played a major role in composing the track, while "contributors" tends to center on performance. See [`track:harlequin-rock-version`](https://hsmusic.wiki/track/harlequin-rock-version/) for an example.
+
+* `Contributors`: links track to other contributors, e.g. vocalists, performers
+  * May include parenthical descriptions, e.g. `'Willow Ascenzo (orchestra, choir)'`.
+  * See `Artists` for guidelines.
+
+* `Cover Artists`: links track to visual artists who created its artwork
+  * May include parenthical descriptions, e.g. `'Kait Linney (lines)'`.
+  * Visual and musical artists are the same document type, and some tracks actually have a shared composer and cover artist.
+  * Format subject to change with upcoming "multiple artworks" feature.
+
+* `Art Tags`: links track to art tags representing characters or features present in its artwork
+  * Guideline: On HSMusic, we have two general categories of tags - characters and settings - and many tracks have both. Don't be afraid to create new tags for characters present in fanventures, etc (though we currently only tag *settings* from Homestuck proper).
+  * Format subject to change with upcoming "multiple artworks" feature.
diff --git a/documents/wiki-info.md b/documents/wiki-info.md
new file mode 100644
index 0000000..1ce39b2
--- /dev/null
+++ b/documents/wiki-info.md
@@ -0,0 +1,24 @@
+# Wiki Info Format
+
+The wiki info document covers options that customize the appearance or behavior of an entire wiki. It is one document (entry) stored in one file, `wiki-info.yaml`.
+
+## Wiki info document
+
+### Essential info fields
+
+* `Name`: full name of the wiki
+* `Short Name`: shorter wiki name (for use in page titles, navbar, etc)
+* `Color`: default theme color to apply across the wiki
+* `Description`: short description for use in web search results
+* `Footer Content`: text and links to include in footer on most wiki pages
+* `Default Language`: main language for wiki content; content pages for other languages are written as subdirectories
+* `Canonical Base`: base URL where site is published (used for search engine optimization)
+
+### Features
+
+* `Divide Track Lists By Groups`: list of groups for which referenced track lists should be divided, e.g. Official Discography, Fandom, Beyond
+* `Enable Flashes & Games`: generate pages related to flash documents
+* `Enable Listings`: generate listing pages, e.g. tracks sorted by name, artists sorted by contributions
+* `Enable News`: generate news entry pages and index
+* `Enable Art Tag UI`: generate content and pages related to art tags (content warning tags are still usable if disabled)
+* `Enable Group UI`: generate UI for navigating between groups
diff --git a/guidelines/albums-and-tracks.md b/guidelines/albums-and-tracks.md
new file mode 100644
index 0000000..c4cfbae
--- /dev/null
+++ b/guidelines/albums-and-tracks.md
@@ -0,0 +1,9 @@
+# Album & Track Guidelines
+
+## `Name` field
+
+### Name albums and tracks according to Bandcamp release
+
+Generally, HSMusic uses Bandcamp as the primary reference for album listings. Many albums which have been released across multiple platforms have slight differences in track naming (e.g. capitalization) — we prefer the naming on Bandcamp first. We also do our best not to editorialize here. Even if different tracks follow different capitalization rules seemingly arbitrarily, we leave that as-is!
+
+When there hasn't been a Bandcamp release, track and album naming can be a bit of a throw. Prefer another music streaming platform first, or whichever platform has the most complete track listing (e.g. if SoundCloud is missing a few tracks while YouTube has the full release, then pull names from YouTube). If the tracks haven't been officially released on *any* platforms, use whatever comes closest to "official" naming: titles as credited in video games, a title the artist passingly called the work when referencing it from some other commentary, etc.
diff --git a/guidelines/common-fields.md b/guidelines/common-fields.md
new file mode 100644
index 0000000..2dce433
--- /dev/null
+++ b/guidelines/common-fields.md
@@ -0,0 +1,150 @@
+# Common Field Guidelines
+
+These guidelines are sorted alphabetically. Some link back to other sections in the guidelines area, so this is a good place to start browsing if you're just getting started with the data format and looking for details on any commonly occurring fields.
+
+### `Additional Files` field
+
+Additional files are extra files pertinent to a particular album or track — usually ones which come with the album download or are "companion" files, like album booklets, desktop wallpapers, included lyrics files, etc. The format for `Additional Files` is a little more involved than most other fields. Here's an example:
+
+```
+Additional Files:
+- Title: Album Booklet
+  Files:
+  - Gristmas Carols.pdf
+- Title: Bandcamp Banner and Background
+  Files:
+  - banner.png
+  - bg.jpg
+```
+
+The `Title` is a human-readable name clearly identifying what you'd be downloading, and `Files` is a list of available files. Often times there's only one file associated, but if a few files are clearly related to each other, they can be bunched up under the same title.
+
+The actual files are stored in the wiki's `media` folder, under `album-additional` (which is adjacent to `album-art`). They're grouped together by album (according to the album's directory, like track art). For example:
+
+```
+data/
+  albums/
+    gristmas-carols.yaml
+
+media/
+  album-art/
+    gristmas-carols/
+      cover.png
+      track1.png
+      (etc)
+  album-additional/
+    gristmas-carols/
+      Gristmas Carols.pdf
+      banner.png
+      bg.jpg
+```
+
+You can use the `Sheet Music Files` and `MIDI Project Files` fields, which follow the same exact format, to collect those files under a more particular field, which will make them get a specialized look on the wiki and show up in listings like "Tracks - with Sheet Music". (Media files listed in these fields are stored in the same folder under `album-additional`.)
+
+### `Color` field
+
+Colors are always represented with hexadecimal values on the wiki. We don't support "special" colors like `red`, `blue` or `turquoise`, nor alternative color formats like `hsl` and `lch`. Colors are three- or four-channels (red, green, blue, optionally alpha) and each channel gets one or two digits:
+
+* `#rrggbb` format: `#f8d4a0` is a bright pastel orange.
+* `#rgb` format: `#88a` is the same as `#8888aa` (cold grey).
+* Alpha channel (transparency) is supported too: `#rrggbbaa`, `#rgba`.
+
+Colors are used all over the wiki, but generally speaking every data object is associated with one color, and that's used as the basis for colors displayed on any associated pages, as well as for most links to the object. Some objects will inherit the color from a "parent" object by default, for example tracks of an album or groups under the same category. If no color is specified and there's not a relevant "parent" object with its own color, objects take the color from the [Wiki Info document](../documents/wiki-info.md).
+
+If you're running your own wiki, you can apply whatever colors you like or selectively tag certain objects but not others. On HSMusic, we apply custom colors to every instance of these kinds of objects:
+
+* Albums
+* Group categories (but not individual groups)
+* Flash acts (but not individual flashes)
+* Art tags
+
+On HSMusic, we try to choose a color for each album (for example) which matches the art and design for that album. There's some room for creative liberty here (for example, choosing an accent color rather than the most prevalent color in a design). Some examples to consider:
+
+* [Ancestral](https://hsmusic.wiki/album/ancestral/): red from the blood across the moon (rather than one of the purples or blue-greens making up the misty colors in the background)
+* [Shortcuts](https://hsmusic.wiki/album/shortcuts/): muted blue-grey reflecting the calmer, more down-to-earth feel of the album (it's roughly pulled from the album wallpaper; the cover itself has similarly muted colors, without an obvious "primary" color behind its design)
+* [DELTARUNE Chapter 1 OST](https://hsmusic.wiki/album/deltarune-ch1-ost/): bright cyan pulled from the "empty town" wallpaper (rather than the heart red in the logo, which would just be repeated for each chapter's album)
+
+On HSMusic, for accessibility purposes, we also aim to keep each color clearly visible against a dark background. Troll-related art tags and tracks are colored according to their caste, for example, but since indigo-blue blood in Homestuck is very dark (for text visible against a white background), a different brighter blue is used instead. Use a tool like [Accessible Colors](https://accessible-colors.com) to check for AA compliant colors (contrast ratio at least 4.5 and, on the wiki, usually a fair bit higher; make sure to set the background color around `#222`).
+
+### `Commentary` field
+
+Artists often share their thoughts on their music and other artworks! These can be chronicled in the `Commentary` field on albums and tracks.
+
+Commentary fields contain multiple lines of text. To represent that in YAML, put `|` and `-` together at the end of the line with `Commentary:`, then put the same number of spaces (generally 4) before each line in the commentary field. For example:
+
+```
+Track: A Very Merry Gristmas Indeed
+Artists:
+- ndividedbyzero
+Commentary: |-
+    <i>ndividedbyzero:</i>
+    When I set out to make my first song for this album I only had two things in mind. The first was to make at least part of it feel like one of those classic 80s Christmas songs that everyone loves, a la Wham!. The second was to make it feel like the in-betweens of the holiday experience: after the unwrapping of presents or whichiver main celebration applies, in the midst of the gathering, before everyone's said their goodbyes and while the spirit of holiday cheer still remains. A theme you could have a cup of hot chocolate to while engaging a seldom-seen relative in lighthearted conversation.
+    Whether I succeeded in these things is up to you. But in any case, I had a whole lot of fun making this!
+---
+Track: You're A Mean One, Mr. Slick
+...
+```
+
+(You can include blank lines to make reading the YAML file easier, but on the site, they're just skipped: every line is considered a separate paragraph, so include all the text in a paragraph on one line and enable soft word wrap in your text editor to make editing easier.)
+
+Commentary will often reference other tracks, albums, or artists. You can make the wiki display a clickable link using special square-bracket tags:
+
+```
+Track: Sburban Cascantdown
+Artists:
+- Noisemaker
+Commentary: |-
+    <i>Noisemaker:</i>
+    To be completely honest it's just [[track:cascante]] from [[album:cool-and-new-voulem1|Voulem 1]]. I regret not using my otamatone but at least [[artist:bambosh]] got some [[track:backyard-dumb|sweet use]] out of it.
+```
+
+If the name of the track you're linking (for example) is already how the commentary author wrote it, you just include it as `[[track:`, then the directory of the track, then `]]`. If the author wrote it differently or referenced it as some natural part of the sentence, add a `|` symbol after the directory, then fill the words in before `]]`.
+
+If something has multiple commentary entries (from different artists), put them together in the same field, using a `<i>Artist Name:</i>` line to differentiate each entry:
+
+```
+Album: Homestuck Vol. 10
+Commentary: |-
+    <i>Robert J! Lake:</i> (project manager)
+    This almost didn't happen.
+    As of release day, it's been exactly four full years since the last numbered Homestuck volume, with only one full album between then and now.
+    (more commentary)
+
+    <i>Marcy Nabors:</i> (co-organizer, mastering engineer)
+    Homestuck Volume 10, the big 1-0!
+    (more commentary)
+    Enjoy the tunes!
+
+    <i>Lexxy:</i> (cover artist)
+    Homestuck will always hold a warm, nostalgic place in my heart, so despite drafting up a handful of concepts - from the graphic and representational to the tongue-in-cheek referential - I ultimately ended up going with the one that expressed that affection the most.
+```
+
+### `Directory` field
+
+[*See also: Behaviour details about the Directory field.*](../documents/common-fields#directory-field)
+
+The directory field identifies what address an object will be accessed at online, and how a particular data object will be referenced by other objects on the wiki (and text content). Almost every kind of object on the wiki has a directory!
+
+Directories are calculated automatically based on data object names, but they can also be specified by hand when necessary. If two objects of the same sort share a name (or have names which are similar enough to make the same directory), the wiki software will report that you need to give at least one of them a custom directory and resolve the conflict. Also, the algorithm for generating a directory is only tuned for English, and fails on just about anything besides the standard Latin/ASCII script. You'll want to specify a directory by hand in these cases.
+
+<!-- On a technical level, directories are necessary for differentiation, but they're also meant to be read and written by humans - you'll deal with directories a lot as you enter data, and they're the identifying part of wiki page URLs too. That means directories should always be clearly legible, and should be descriptive when you need to specify one manually to resolve a conflict. For example, don't give Light from *Homestuck Vol. 5* the directory `light` and Light from *Medium* the directory `light-2`; instead, give them `light-vol5` and `light-medium`. -->
+
+Some examples of when you might manually set a directory:
+
+* Resolving a conflict: name three tracks named "Penumbra Phantasm" need to be distinguished somehow! On HSMusic, we usually distinguish by album: [`penumbra-phantasm`](https://hsmusic.wiki/track/penumbra-phantasm/) for the original, [`penumbra-phantasm-act-8`](https://hsmusic.wiki/track/penumbra-phantasm-act-8/) from Act 8 Volume 1, and [`penumbra-phantasm-aspect-clock`](https://hsmusic.wiki/track/penumbra-phantasm-aspect-clock/) from ASPECT/CLOCK. When tracks are from the same album or aren't associated with a specific album (on the wiki), we use the artist instead: [`i-dont-want-to-miss-a-thing`](https://hsmusic.wiki/track/i-dont-want-to-miss-a-thing/) from the official album Homestuck Vol. 6, and [`i-dont-want-to-miss-a-thing-aerosmith`](https://hsmusic.wiki/track/i-dont-want-to-miss-a-thing-aerosmith/) for the movie original it's based on.
+
+* "Vaporwave" style titles with spaces between each letter - the directory algorithm turns "a e s t h e t i c a d e" to `a-e-s-t-h-e-t-i-c-a-d-e`, but it's just more useful in URLs and wiki data to refer to it as `aestheticade`, for example.
+
+* Complete bullshit titles! "kis da boy #<3 #<3 #otp #aaAAAAAA #OMFG #!!!" is turned into `kis-da-boy-3-3-otp-aaaaaaaa-omfg`. This is awful (those hearts have nothing to do with the number 3, to say the least), so you could assign it a more reasonable directory like [`kis-da-boy`](https://hsmusic.wiki/track/kis-da-boy/).
+
+* Non-latin scripts in titles get skipped altogether by the directory algorithm, so these titles need to either be romanized or translated manually. (On HSMusic, this usually depends on how English speakers typically refer to the title in question.)
+
+* Similar to the above, accented Latin letters also need to be handled manually. For example, "Funiculì, Funiculà" would automatically be assigned the directory `funicul-funicul`; instead we manually specify it as [`funiculi-funicula`](https://hsmusic.wiki/track/funiculi-funicula/).
+
+* Same deal for variant Latin scripts like small-caps: "ᴀsᴘᴇᴄᴛ/ᴄʟᴏᴄᴋ" would get a totally empty directory according to the algorithm! It's specified manually as [`aspect-clock`](https://hsmusic.wiki/album/aspect-clock/).
+
+* In the most extreme cases, you may need to resort to violence. `『H☯MESTUCK VAP☯RWAVE 2016 RUH-RUH-RUH-ＲＥＭＩＸ』アンドレア・ヒューシー・グーグル翻訳` is not `h-omestuck-vap-rwave-2016-ruh-ruh-ruh` but `vaporwave-2016`, and `ＳジＢャＵンＲグＢル` is not an empty directory but `vaporwave-2016-track5`.
+
+### `Name` field
+
+- [Name albums and tracks according to Bandcamp release](./albums-and-tracks.md#name-field)