docs: 📝 add README

2025-06-26 20:23:47 +02:00 · 2025-06-26 20:23:47 +02:00 · 33e603cf05
commit 33e603cf05
parent 54882773a2
1 changed files with 107 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,107 @@
+# Character Ref Pages
+
+Reference pages for all of the OCs (original characters) of [Sebin Nyshkim].
+
+These reference pages are intended to provide artists with extensive info and reference material for commissions.
+
+## Technologies
+
+This project is built using [11ty] with [WebC]. It builds a (mostly) static website that's easy to serve with any webserver, no backend necessary.
+
+WebC allows for easily composable components that get compiled to standard HTML elements (with the option to have them compiled to native [web components]).
+
+For normal content pages, Markdown is used. Since Markdown allows the inclusion of HTML in `md` files, this is used to include WebC components in content pages.
+
+## Get up and running
+
+After cloning the repo, install the required NPM dependencies:
+
+```bash
+npm install
+```
+
+11ty comes with an integrated web server with hot reloading for local development. To start it, simply:
+
+```bash
+npm run start
+```
+
+> [!NOTE]
+> There currently seems to be an issue with the way hot reloading and transformation works when using WebC and Markdown together in the same project. If the page doesn't update as expected after having made changes, restart the local dev server.
+
+To build the project, simply:
+
+```bash
+npm run build
+```
+
+This puts the finished page into the `public` directory. All files can be deployed to a webserver as-is.
+
+## Project structure
+
+Per the `eleventy.config.js` file, all input files are located in the `src` directory. All other directories defined in the `config` object at the end of the config file are relative to the `src` directory.
+
+### Layouts
+
+Pages are mostly comprised of two layouts: `base` and `character`. The `base` layout provides the basic HTML structure with the `<head>` and `<body>` elements. The character pages all use the `character` layout.
+
+When adding a new character, make sure to add a corresponding directory data file with the same name as the character, i.e. `[character]/[character].11tydata.json` with the following content:
+
+```json
+{
+  "layout": "character.webc"
+}
+```
+
+### Components
+
+WebC components in 11ty encapsulate HTML, CSS and JavaScript in a single file (similar to how Vue.js [SFCs] work). This greatly helps maintainability and separation of concerns.
+
+The modularized nature of WebC allows for a composable structure of 11ty websites, with their ability to use the `<slot>` element, which this project makes extensive use of. Together with special WebC extensions, like `webc:if` and `webc:for`, markup can be dynamically generated. Additionally, `<script webc:setup>` allows for pre-processing of data passed to a component before transformation into HTML.
+
+WebC also enables bundling of CSS and JS, causing only the relevant parts of it to be loaded for any given page to reduce load times.
+
+CSS can be scoped to a WebC component with `<style webc:scoped>` attribute. This gives the component a randomized class name to prevent style collisions across components. Additionally, if a name is passed to `webc:scoped` WebC will instead use that as the class name instead of a randomized string. Using the CSS `:host` selector binds styles to either the randomized or chosen class name. So this:
+
+```html
+<style webc:scoped="my-component">
+  :host {
+    background-color: rebeccapurple;
+    color: white;
+  }
+</style>
+```
+
+Will transform into:
+
+```css
+.my-component {
+  background-color: rebeccapurple;
+  color: white;
+}
+```
+
+> [!WARNING]
+> Style encapsulation is very strict! In order to account for selector changes *outside* of the component, the nesting operator `&` should be used, as it will be kept as-is and the selector logic will work as expected.
+
+### Character pages
+
+The project makes heavy use of 11ty's [data cascade]. For this reason, it is essential to keep data about the characters in their respective directories harmonized, i.e. keeping property, variable and function names in the `[character].11tydata.js` files the same across characters. This way, pulling in data into components and pages stays relatively easy and straight-forward.
+
+> [!NOTE]
+> You might be wondering why there's both a `json` and `js` 11ty data file in each of the character's directories. This is because `json` data files cannot hold functions to provide processed data to components in the data cascade that lends itself better to consumption by components. The data defined in `json` files is also not accessible to functions in `js` files. In order to keep page configuration, character data and content separate, this approach was chosen.
+
+### Image processing
+
+Images are processed by the 11ty [image plugin]. It comes with its own component `<eleventy-image>`. Images passed to it will get processed into different formats according to the options in `eleventy.config.js`, making the use of responsive images across the site significantly easier and more pleasant. File names in the `img` sub-directory follow the same structure as the character pages: each character has their own sub-directory according to their first name. At minimum, there needs to exist a `avatar.png` file for display on the front page and in the sidebar on the character page. Any other images can be added as needed.
+
+> [!NOTE]
+> This site allows characters to have both SFW and NSFW versions of reference images. Setting the `nsfw` attribute on a `<ref-img>` component to `true` causes the component to attempt to load an additional image with the same base name as `src` with an additional suffix of `-nsfw` at the and of the file name.
+
+[Sebin Nyshkim]: https://sebin-nyshkim.net
+[11ty]: https://www.11ty.dev/
+[WebC]: https://www.11ty.dev/docs/languages/webc/
+[web components]: https://www.webcomponents.org/
+[SFCs]: https://vuejs.org/guide/scaling-up/sfc.html
+[data cascade]: https://www.11ty.dev/docs/data-cascade/
+[image plugin]: https://www.11ty.dev/docs/plugins/image/