diff --git a/README.md b/README.md new file mode 100644 index 0000000..d286487 --- /dev/null +++ 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 `` and `` 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 `` 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, `