Update READMEs for repo & astro-ao3-loader

README.md

@@ -1,10 +1,35 @@
 # FujoCoded Plugins
 
-A repository of plugins for true webdev fujin. Includes plugins for:
+<div align="center">
 
-- Remark
-- Rehype
-- Zod
-- Astro
+<!-- Do we have a banner we want to add here? Or do we want to make individual ones for each plugin? -->
 
-You can learn about each plugin by looking at the `README.md` file within their directories.
+A repository of plugins for true webdev fujin.
+
+<!-- Add the <a> so IMGs will stay on the same line -->
+<a href="https://fancoders.com/">
+    <img src="https://img.shields.io/badge/fandom-coders-ff69b4" alt="Fandom Coders badge"/>
+</a>
+</div>
+
+## What is `fujocoded-plugins`?
+
+This repo includes a collection of plugins for [remark](https://remark.js.org/), [rehype](https://github.com/rehypejs/rehype), [Zod](https://zod.dev/), and [Astro](https://astro.build/).
+
+You can learn more about each plugin by looking at the `README.md` file in its directory.
+
+- [`astro-alt-text-toolkit`](/astro-alt-text-toolkit/README.md) - (WIP) Makes it easier to manage alt text on your Astro site, and beyond.
+- [`astro-ao3-loader`](/astro-ao3-loader/README.md) - Uses [AO3.js](https://github.com/fujowebdev/ao3.js) to load data from AO3 to your Astro site.
+- [`astro-authproto`](/astro-authproto/README.md) - Adds ATproto authentication to your Astro site.
+- [`astro-dev-only`](/astro-dev-only/README.md) - Renders pages to your Astro site during development (`npm run dev`), and removes them from the final build (`npm run build`).
+- [`astro-rehype-html-headings`](/astro-rehype-html-headings/README.md) - Returns Astro headings from an `.md` or `.mdx` including their rendered HTML.
+- [`astro-remark-collect-components`](/astro-remark-collect-components/README.md) - Adds a list of attributes from Astro components to the `remarkFrontmatter` property for later use.
+- [`astro-smooth-actions`](/astro-smooth-actions/README.md) - Makes Astro Action smoother by persisting <u>form</u> action results in the session.
+- [`expressive-code-caption`](/expressive-code-caption/README.md) - Allows adding captions to [`expressive-code`](https://github.com/expressive-code/expressive-code) code blocks.
+- [`expressive-code-output`](/expressive-code-output/README.md) - Allows separating code in [`expressive-code`](https://github.com/expressive-code/expressive-code) code blocks from the output.
+- [`rehype-code-params`](/rehype-code-params/README.md) - Styles param values in inline code.
+- [`remark-alt-text-files`](/remark-alt-text-files/README.md) - Allows loading alt text from a file.
+- [`remark-capitalize-titles`](/remark-capitalize-titles/README.md) - Transforms all Markdown titles using [title.sh](https://github.com/zeit/title).
+- [`remark-excalidraw`](/remark-excalidraw/README.md) - Allows loading [Excalidraw](https://github.com/excalidraw/excalidraw) files in Markdown.
+- [`remark-jsx-auto-slug`](/remark-jsx-auto-slug/README.md) - Automatically adds slugs to Astro components.
+- [`zod-transform-socials`](/zod-transform-socials/README.md) - Applies a Zod transformation to a list of social contacts to surface the appropriate website, username, and icon name.

astro-alt-text-toolkit/README.md

@@ -1,4 +1,6 @@
-# @fujocoded/astro-alt-text-toolkit
+# `@fujocoded/astro-alt-text-toolkit`
 
-A WIP bundle of ALT text utilities to make the ALT text of your
-Astro site (and beyond) easier to manage
+> [!WARNING]
+> This plugin is a work in progress.
+
+A bundle of utilities that make the alt text of your Astro site (and beyond) easier to manage.

astro-ao3-loader/README.md

@@ -1,70 +1,91 @@
-# Astro AO3 loader
+# `@fujocoded/astro-ao3-loader`
+
+<div align="center">
+
+Load data from Archive of Our Own to your Astro site.
+
+  <!-- Add the <a> so IMGs will stay on the same line -->
+  <a href="https://choosealicense.com/licenses/mit/">
+    <img alt="NPM license" src="https://img.shields.io/npm/l/%40fujocoded%2Fastro-ao3-loader" />
+  </a>
+  <a href="https://fancoders.com/">
+    <img src="https://img.shields.io/badge/fandom-coders-ff69b4" alt="Fandom Coders badge"/>
+  </a>
+  <a href="https://npmjs.com/package/@fujocoded/astro-ao3-loader">
+    <img src="https://badge.fury.io/js/%40fujocoded%2Fastro-ao3-loader.svg" alt="Np PM version badge"/>
+  </a>
+  <a href="https://codespaces.new/FujoWebDev/fujocoded-plugins">
+    <img src="https://github.com/codespaces/badge.svg" alt="Open in GitHub Codespaces" style="height: 20px"/>
+  </a>
+</div>
+
+## What is `@fujocoded/astro-ao3-loader`?
 
 > [!WARNING]
-> This is an experimental library with only basic functionality. If you
-> want to help us expand it, contact us via GitHub, Fandom Coders, or at
-> contacts@fujocoded.com.
+> This is an experimental library with only basic functionality. If you want to help us expand it, you can reach out via GitHub, Fandom Coders, our socials, or contacts@fujocoded.com.
 >
-> If you've never joined an open source project before, this is an excellent
-> first place to contribute!
+> If you've never joined an open source project before, this is an excellent first place to contribute!
 
-A AO3 data loader for Astro using the experimental content layer and
-[AO3.js](https://github.com/fujowebdev/ao3.js) to load data from AO3 to your
-Astro website.
+This library makes it easy to use the [Content Loader API](https://docs.astro.build/en/reference/content-loader-reference/) and [AO3.js](https://github.com/fujowebdev/ao3.js) to load data from [Archive of Our Own](https://archiveofourown.org/) to your [Astro](https://astro.build/) website.
 
-You can see an example of its usage [in our sample
-repository](https://github.com/FujoWebDev/ao3-content-layer-example).
+## What can `@fujocoded/astro-ao3-loader` do?
 
-## Installation
+You can use this library to easily grab data about content hosted on [Archive of Our Own](https://archiveofourown.org/) to use in your [Astro](https://astro.build/) site—however you wish to. ✨
 
-```sh
-npm install @fujocoded/astro-ao3-loader
-```
+The library includes the following loaders:
 
-## Usage
+| **Loader**     | **Description**                                                                              | **Data file**                 |
+| -------------- | -------------------------------------------------------------------------------------------- | ----------------------------- |
+| `worksLoader`  | Loads data from a set of works hosted on [Archive of Our Own](https://archiveofourown.org/). | `src/content/ao3/works.yaml`  |
+| `seriesLoader` | Loads data from series hosted on [Archive of Our Own](https://archiveofourown.org/).         | `src/content/ao3/series.yaml` |
 
-This package requires Astro 4.14.0 or later. You must enable the experimental
-content layer in Astro unless you are using version 5.0.0-beta or later. You can
-do this by adding the following to your `astro.config.mjs`:
+## How to use `@fujocoded/astro-ao3-loader`
 
-```javascript
-export default defineConfig({
-  // ...
-  experimental: {
-    contentLayer: true,
-  },
-});
-```
+> [!TIP]
+> Want to see some examples? Take a look around the [examples folder](/astro-ao3-loader/__examples__/). 👀
 
-Currently, this package contains only a single loader called `worksLoader`,
-which loads the details of a series of works whose id is listed in the
-`src/content/ao3/works.yaml` file.
+### Prerequisites
 
-First add the configuration in `src/content/config.ts`:
+This library requires [Astro](https://astro.build/) 5.0.0 or later, and Astro's built-in [Content Loader API](https://docs.astro.build/en/reference/content-loader-reference/). Astro 4 isn't currently supported, but if you'd like to use the library on an older version, [open an issue](https://github.com/FujoWebDev/fujocoded-plugins/issues/new?labels=ao3-content-loader) to let us know!
 
-```typescript
-// src/content/config.ts
-import { defineCollection } from "astro:content";
-import { feedLoader } from "@fujocoded/astro-ao3-loader";
+### Installation
 
-export const collections = {
-  fanfictions: defineCollection({ loader: worksLoader }),
-};
+```bash
+npm install @fujocoded/astro-ao3-loader
 ```
 
-Then create your `src/content/ao3/works.yaml` file:
+### Configuration
 
-```yaml
-- 38226814
-- 49238326
-- 59988091
-- 41160522
-- 11728554
-- 12928950
-- 58869805
-```
+The configuration steps are the same for each [loader](#what-can-fujocodedastro-ao3-loader-do). In this example, we'll use the `worksLoader` to get information from a list of works specified in `src/content/ao3/works.yaml`.
+
+1. Set up [a content collection](https://docs.astro.build/en/guides/content-collections/#defining-collections) in `src/content/config.ts` that uses your chosen loader.
+
+   ```ts
+   import { defineCollection } from "astro:content";
+   import { worksLoader } from "@fujocoded/astro-ao3-loader";
+
+   export const collections = {
+     fanfictions: defineCollection({ loader: worksLoader }),
+   };
+   ```
 
-You can then use this like any other collection in Astro:
+2. Create `src/content/ao3/works.yaml` and add a list of work IDs to the file.
+
+   ```yaml
+   - 38226814
+   - 49238326
+   - 59988091
+   - 41160522
+   - 11728554
+   - 12928950
+   - 58869805
+   ```
+
+> [!TIP]
+> This file uses the YAML data format to list work IDs. If you're running into issues, check your syntax using one of the many YAML validators out there.
+
+Once configured, you can use the collection created with `astro-ao3-loader` like you
+would any other [Astro content collection](https://docs.astro.build/en/guides/content-collections/#using-content-in-astro-templates).
 
 ```astro
 ---
@@ -76,14 +97,18 @@ const fanfictions = await getCollection("fanfictions");
 <h1>Hello fujin</h1>
 <ul>
   {
-    fanfictions.map((fic) =>
-      fic.data.locked ? (
-        <li>Locked</li>
-      ) : (
-        <li>{fic.data.title} by {fic.data.authors[0].pseud} ({fic.data.rating})
+    fanfictions.map((fic) => {
+      if (fic.data.locked) {
+        return <li>Locked</li>;
+      }
+      return (
+        <li>
+          {fic.data.title} by {fic.data.authors[0].pseud} ({fic.data.rating})
         </li>
-      )
-    )
+      );
+    })
   }
 </ul>
 ```
+
+For a more complete example, you can take a look at [our example page](/astro-ao3-loader/__examples__/works-list/src/pages/index.astro).

astro-ao3-loader/__examples__/works-list/README.md

@@ -0,0 +1,38 @@
+# `@fujocoded/astro-ao3-loader` Example
+
+<center>
+    <img 
+    alt="A list of works from AO3 as shown in this example. Features title, author, ratings and relationships" 
+    src="./works-list.png" 
+    style="max-width: 500px; margin: 15px;"
+    />
+</center>
+
+This example shows the `@fujocoded/astro-ao3-loader` library in action. Inside, you'll see (among others) the following folders and files:
+
+```text
+/
+├─ ...
+├─ src/
+│  └─ content/
+│     └── ao3/
+│         └── series.yaml
+│         └── works.yaml
+│     └── config.ts
+│  └─ pages/
+│     └── index.astro
+└─ package.json
+```
+
+Explore at your leisure, and feel free to open an Issue if you have any questions.
+
+## Commands
+
+The following commands are Astro's built-in functionality. You can run these from a terminal pointing to your project's root.
+
+| **Command**       | **Action**                                    |
+| ----------------- | --------------------------------------------- |
+| `npm install`     | Install dependencies.                         |
+| `npm run dev`     | Start a local dev server at `localhost:4321`. |
+| `npm run build`   | Build your production site to `./dist/`.      |
+| `npm run preview` | Preview your build locally before deploying.  |

astro-ao3-loader/__examples__/works-list/src/content/config.ts

@@ -0,0 +1,17 @@
+import { defineCollection } from "astro:content";
+import { worksLoader, seriesLoader } from "@fujocoded/astro-ao3-loader";
+
+/**
+ * You can configure content collections in Astro by exporting
+ * "collections" from `src/content/config`, like you see here.
+ *
+ * This loader exports two collections:
+ * - fanfictions, which uses our worksLoader
+ * - series, which uses our seriesLoader
+ *
+ * Learn more: https://docs.astro.build/en/guides/content-collections/#defining-collections
+ */
+export const collections = {
+  fanfictions: defineCollection({ loader: worksLoader }),
+  series: defineCollection({ loader: seriesLoader }),
+};