generated from nhcarrigan/template
feat: document all the fings
This commit is contained in:
@@ -36,11 +36,19 @@
|
||||
],
|
||||
"words": [
|
||||
"Abalise",
|
||||
"Aeris",
|
||||
"Alouette",
|
||||
"Amari",
|
||||
"Amirei",
|
||||
"atproto",
|
||||
"Aurelia",
|
||||
"Aureline",
|
||||
"bannable",
|
||||
"Becca",
|
||||
"Beccalia",
|
||||
"Caelia",
|
||||
"Calenelle",
|
||||
"Callista",
|
||||
"CCPA",
|
||||
"Celestine",
|
||||
"Čeština",
|
||||
@@ -48,6 +56,10 @@
|
||||
"Chibika",
|
||||
"CPACC",
|
||||
"Dansk",
|
||||
"Eirene",
|
||||
"Elaria",
|
||||
"Elowyn",
|
||||
"Elunara",
|
||||
"equivalencies",
|
||||
"escalatory",
|
||||
"excludable",
|
||||
@@ -58,16 +70,24 @@
|
||||
"Gitea",
|
||||
"Hikari",
|
||||
"incentivising",
|
||||
"Isolda",
|
||||
"Italiano",
|
||||
"ITAR",
|
||||
"Iuvo",
|
||||
"Jessara",
|
||||
"KADOKAWA",
|
||||
"LGBTQ",
|
||||
"Lietuvių",
|
||||
"Lyria",
|
||||
"Maribelle",
|
||||
"Meliora",
|
||||
"Meridia",
|
||||
"Mommy",
|
||||
"NAMI",
|
||||
"Nederlands",
|
||||
"Nymira",
|
||||
"OFAC",
|
||||
"Oriana",
|
||||
"Pavelle",
|
||||
"PIPEDA",
|
||||
"Polski",
|
||||
@@ -83,10 +103,18 @@
|
||||
"Suomi",
|
||||
"Svenska",
|
||||
"Taryne",
|
||||
"Tessara",
|
||||
"Thalassa",
|
||||
"Thessalia",
|
||||
"Türkçe",
|
||||
"Umbrelle",
|
||||
"Veluna",
|
||||
"Verena",
|
||||
"Vitalia",
|
||||
"Vivienne",
|
||||
"vtubing",
|
||||
"WCAG",
|
||||
"Zephra",
|
||||
"zirs",
|
||||
"Ελληνικά",
|
||||
"Български",
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
export const navigation = [
|
||||
{
|
||||
label: "About Us",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{
|
||||
label: "Mission Statement",
|
||||
@@ -30,6 +31,7 @@ export const navigation = [
|
||||
},
|
||||
{
|
||||
label: "Legal Information",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{
|
||||
label: "Limitation of Liability and Indemnification Policy",
|
||||
@@ -90,11 +92,12 @@ export const navigation = [
|
||||
{
|
||||
label: "Crisis and Mental Health Management Policy",
|
||||
link: "/legal/crisis-mental-health",
|
||||
}
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
label: "Community Policies",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{
|
||||
label: "Community Code of Conduct",
|
||||
@@ -124,6 +127,7 @@ export const navigation = [
|
||||
},
|
||||
{
|
||||
label: "Development Documentation",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{
|
||||
label: "Contributing Guide",
|
||||
@@ -157,6 +161,7 @@ export const navigation = [
|
||||
},
|
||||
{
|
||||
label: "Project Documentation",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{
|
||||
label: "ESLint Config",
|
||||
@@ -176,7 +181,7 @@ export const navigation = [
|
||||
{
|
||||
label: "Naomi's Blog",
|
||||
link: "/projects/blog",
|
||||
badge: { text: "v0.1.0", variant: "caution" },
|
||||
badge: { text: "v1.0.0", variant: "tip" },
|
||||
},
|
||||
{
|
||||
label: "Celestine",
|
||||
@@ -302,11 +307,242 @@ export const navigation = [
|
||||
label: "Documentation Site",
|
||||
link: "/projects/docs",
|
||||
badge: { text: "v1.0.0", variant: "tip" },
|
||||
},
|
||||
{
|
||||
label: "Data API",
|
||||
link: "/projects/data-api",
|
||||
badge: { text: "v1.0.0", variant: "tip" },
|
||||
},
|
||||
{
|
||||
label: "Nymira",
|
||||
link: "/projects/nymira",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Vitalia",
|
||||
link: "/projects/vitalia",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Octavia",
|
||||
link: "/projects/octavia",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Maribelle",
|
||||
link: "/projects/maribelle",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Verena",
|
||||
link: "/projects/verena",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Thalassa",
|
||||
link: "/projects/thalassa",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Aeris",
|
||||
link: "/projects/aeris",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Thessalia",
|
||||
link: "/projects/thessalia",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Isolda",
|
||||
link: "/projects/isolda",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Meliora",
|
||||
link: "/projects/meliora",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Aurelia",
|
||||
link: "/projects/aurelia",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Eirene",
|
||||
link: "/projects/eirene",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Amirei",
|
||||
link: "/projects/amirei",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Zephra",
|
||||
link: "/projects/zephra",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Oriana",
|
||||
link: "/projects/oriana",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Lyra",
|
||||
link: "/projects/lyra",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Selene",
|
||||
link: "/projects/selene",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Sybil",
|
||||
link: "/projects/sybil",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Calenelle",
|
||||
link: "/projects/calenelle",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Rowena",
|
||||
link: "/projects/rowena",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Alouette",
|
||||
link: "/projects/alouette",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Clarion",
|
||||
link: "/projects/clarion",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Elowyn",
|
||||
link: "/projects/elowyn",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Evangeline",
|
||||
link: "/projects/evangeline",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Theodora",
|
||||
link: "/projects/theodora",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Vivienne",
|
||||
link: "/projects/vivienne",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Elysium",
|
||||
link: "/projects/elysium",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Elaria",
|
||||
link: "/projects/elaria",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Elunara",
|
||||
link: "/projects/elunara",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Aureline",
|
||||
link: "/projects/aureline",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Tessara",
|
||||
link: "/projects/tessara",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Hacksmiths",
|
||||
link: "/projects/hacksmiths",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Meridia",
|
||||
link: "/projects/meridia",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Lucinda",
|
||||
link: "/projects/lucinda",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Liora",
|
||||
link: "/projects/liora",
|
||||
badge: { text: "1.0.0", variant: "tip" },
|
||||
},
|
||||
{
|
||||
label: "Beccalia: Origins",
|
||||
link: "/projects/beccalia-origins",
|
||||
badge: { text: "v0.0.0", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Beccalia: Prologue",
|
||||
link: "/projects/beccalia-prologue",
|
||||
badge: { text: "v1.0.1", variant: "tip" },
|
||||
},
|
||||
{
|
||||
label: "Life of a Naomi",
|
||||
link: "/projects/life-of-a-naomi",
|
||||
badge: { text: "v1.0.0", variant: "tip" },
|
||||
},
|
||||
{
|
||||
label: "Ruu's Goblin Quest",
|
||||
link: "/projects/ruus-goblin-quest",
|
||||
badge: { text: "v1.0.0", variant: "tip" },
|
||||
},
|
||||
{
|
||||
label: "Naomi's Adventure I: An Isekai Story",
|
||||
link: "/projects/naomis-adventure-i",
|
||||
badge: { text: "unreleased", variant: "danger" },
|
||||
},
|
||||
{
|
||||
label: "Amari",
|
||||
link: "/projects/amari",
|
||||
badge: { text: "v1.0.0", variant: "tip" },
|
||||
},
|
||||
{
|
||||
label: "Art4Palestine Bot",
|
||||
link: "/projects/a4p-bot",
|
||||
badge: { text: "v1.0.0", variant: "tip" },
|
||||
},
|
||||
{
|
||||
label: "Naomi's VSCode Themes",
|
||||
link: "/projects/vscode-themes",
|
||||
badge: { text: "v2.2.0", variant: "tip" },
|
||||
},
|
||||
{
|
||||
label: "Boost Monitor",
|
||||
link: "/projects/boost-monitor",
|
||||
badge: { text: "v1.0.1", variant: "tip" },
|
||||
},
|
||||
{
|
||||
label: "TypeScript Config",
|
||||
link: "/projects/typescript-config",
|
||||
badge: { text: "v4.0.0", variant: "tip" },
|
||||
}
|
||||
].sort((a, b) => a.label.localeCompare(b.label)),
|
||||
},
|
||||
{
|
||||
label: "Staff Guidelines",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{
|
||||
label: "Staff Handbook",
|
||||
@@ -334,6 +570,7 @@ export const navigation = [
|
||||
},
|
||||
{
|
||||
label: "Additional Trainings",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{
|
||||
label: "Accessibility Coordination Training for Staff",
|
||||
@@ -386,17 +623,18 @@ export const navigation = [
|
||||
{
|
||||
label: "Technical Contributor Training for Staff",
|
||||
link: "/staff/training/technical-contributor",
|
||||
}
|
||||
]
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
label: "Staff Policy Self-Assessment",
|
||||
link: "/staff/policy-self-assessment",
|
||||
}
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
label: "Miscellaneous Documents",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{
|
||||
label: "Managing Local Music",
|
||||
|
||||
@@ -6,19 +6,7 @@ hero:
|
||||
tagline:
|
||||
This site contains all of the documentation related to NHCarrigan, its Policies, and its Projects.
|
||||
actions:
|
||||
- text: Mission Statement
|
||||
- text: Let's Go!
|
||||
link: /about/mission/
|
||||
variant: secondary
|
||||
- text: Code of Conduct
|
||||
link: /community/coc/
|
||||
variant: secondary
|
||||
- text: Contributing Guide
|
||||
link: /dev/contributing/
|
||||
variant: secondary
|
||||
- text: Software License
|
||||
link: /legal/license/
|
||||
variant: secondary
|
||||
- text: Contact Us
|
||||
link: /about/contact/
|
||||
variant: secondary
|
||||
variant: primary
|
||||
---
|
||||
|
||||
@@ -0,0 +1,892 @@
|
||||
---
|
||||
title: Art for Palestine Bot
|
||||
---
|
||||
|
||||
Art for Palestine Bot (hereinafter the "Application") is a Discord bot designed to facilitate the Art for Palestine charity event. The Application serves as an automated bridge between Airtable, Trello, and Discord to manage art commission requests, artist assignments, delivery tracking, and support tickets for the charity event.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
### 1.1 Getting Started
|
||||
|
||||
The Art for Palestine Bot is available on the [Art for Palestine Discord server](https://discord.gg/kHNyb6Vyf8). Once you join the server, you will automatically be assigned the member role and can begin interacting with the bot's features.
|
||||
|
||||
### 1.2 Requesting Art Commissions
|
||||
|
||||
Art commission requests are submitted through an Airtable form (external to Discord). Once submitted, your request will automatically appear in the designated commission channel where artists can view and claim it. Your request should include:
|
||||
|
||||
- Your name
|
||||
- Preferred contact method (Email, Discord, or Twitter)
|
||||
- Your contact handle/username
|
||||
- Description of the art you would like drawn
|
||||
- Reference images (optional)
|
||||
- Any additional notes or requirements
|
||||
|
||||
### 1.3 Artist Features
|
||||
|
||||
#### 1.3.1 Claiming Art Commissions
|
||||
|
||||
As an artist, you can claim art commissions by reacting to commission posts in the art commission channel (ID: `1172568787330019340`).
|
||||
|
||||
**Important Notes:**
|
||||
- You can only claim up to 2 commissions at a time
|
||||
- Claiming a commission creates a private thread for coordination
|
||||
- The thread will include your mention and the requester's information
|
||||
|
||||
#### 1.3.2 Submitting Completed Artwork
|
||||
|
||||
Once you've completed the artwork:
|
||||
1. Post the completed artwork as an image attachment in the private thread
|
||||
2. The bot will automatically forward your submission to the distribution channel
|
||||
3. Your thread will be archived
|
||||
4. The commission will be removed from your active count
|
||||
|
||||
#### 1.3.3 Art Reminders
|
||||
|
||||
The bot sends automated reminders to help manage workload:
|
||||
- **Unclaimed Art Reminders**: Sent Monday, Wednesday, and Friday at 9:00 AM
|
||||
- **Unfinished Art Reminders**: Sent Saturday at 9:00 AM
|
||||
|
||||
### 1.4 Distribution Features
|
||||
|
||||
#### 1.4.1 Claiming Distributions
|
||||
|
||||
Distribution team members can claim distribution tasks by reacting to posts in the distribution channel (ID: `1173061747737903315`). Similar to art commissions:
|
||||
- Maximum 2 concurrent distributions per member
|
||||
- Creates a private coordination thread
|
||||
- Includes recipient and artwork details
|
||||
|
||||
#### 1.4.2 Confirming Deliveries
|
||||
|
||||
To confirm a distribution:
|
||||
1. Deliver the artwork to the recipient
|
||||
2. Post a confirmation image in the private thread
|
||||
3. The bot will close and archive the thread
|
||||
|
||||
#### 1.4.3 Distribution Reminders
|
||||
|
||||
- **Unclaimed Distribution Reminders**: Sent Monday, Wednesday, and Friday at 9:00 AM
|
||||
- **Unfinished Distribution Reminders**: Sent Saturday at 9:00 AM
|
||||
|
||||
### 1.5 Support Ticket System
|
||||
|
||||
#### 1.5.1 Opening a Ticket
|
||||
|
||||
Users can open support tickets using the ticket button in the designated ticket channel:
|
||||
1. Click the "Open Ticket" button
|
||||
2. Fill out the modal form with your issue description
|
||||
3. A private thread will be created for your ticket
|
||||
4. Support team members will be notified
|
||||
|
||||
#### 1.5.2 Ticket Workflow
|
||||
|
||||
- **For Users**: Describe your issue in the private thread and wait for a support team member to claim it
|
||||
- **For Support Team**: Click "Claim Ticket" to add your mention and take responsibility for the issue
|
||||
- Conversations in the ticket thread are automatically logged
|
||||
|
||||
#### 1.5.3 Closing Tickets
|
||||
|
||||
Support team members can close tickets using the "Close Ticket" button:
|
||||
- A log file of the entire conversation will be generated
|
||||
- The log is sent to the ticket archive channel
|
||||
- The thread is closed and archived
|
||||
|
||||
### 1.6 Moderation Commands
|
||||
|
||||
Moderation team members with the support role (ID: `1173582640843063366`) have access to these commands:
|
||||
|
||||
#### `!mute <user_id> <duration> <reason>`
|
||||
Temporarily timeout a user.
|
||||
|
||||
**Parameters:**
|
||||
- `user_id`: The Discord user ID to mute
|
||||
- `duration`: Duration with unit (e.g., `30m`, `2h`, `1d`)
|
||||
- Supported units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days)
|
||||
- `reason`: Explanation for the timeout
|
||||
|
||||
**Example:**
|
||||
```
|
||||
!mute 123456789012345678 1h Spam in general channel
|
||||
```
|
||||
|
||||
#### `!unmute <user_id> <reason>`
|
||||
Remove a timeout from a user.
|
||||
|
||||
**Parameters:**
|
||||
- `user_id`: The Discord user ID to unmute
|
||||
- `reason`: Explanation for removing the timeout
|
||||
|
||||
**Example:**
|
||||
```
|
||||
!unmute 123456789012345678 Appeal accepted
|
||||
```
|
||||
|
||||
### 1.7 Palestine News Updates
|
||||
|
||||
The bot automatically fetches and posts news updates from Al Jazeera's Palestine live blog:
|
||||
- Updates are checked every 10 minutes
|
||||
- New articles are posted to the news channel
|
||||
- Prevents duplicate posts using article ID tracking
|
||||
|
||||
### 1.8 Getting Help
|
||||
|
||||
If you encounter issues or have questions:
|
||||
- Open a support ticket in the Discord server
|
||||
- Report bugs on [GitHub Issues](https://github.com/naomi-lgbt/nodejs-typescript-template/issues)
|
||||
- Contact via the [chat server](http://chat.nhcarrigan.com) or email at `contact@nhcarrigan.com`
|
||||
|
||||
---
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
### 2.1 Prerequisites
|
||||
|
||||
Before running your own instance, ensure you have:
|
||||
|
||||
- **Node.js**: Version 22 (specified in `package.json`)
|
||||
- **pnpm**: Version 10 (package manager)
|
||||
- **Discord Bot Account**: With a bot token and appropriate permissions
|
||||
- **Airtable Account**: With API access
|
||||
- **Discord Webhooks**: Multiple webhooks configured for different channels
|
||||
|
||||
### 2.2 Required Discord Permissions
|
||||
|
||||
Your Discord bot requires the following Gateway Intents:
|
||||
- `GuildMessages`: Access to guild message events
|
||||
- `Guilds`: Access to guild/server data
|
||||
- `GuildMessageReactions`: Access to message reaction events
|
||||
- `MessageContent`: Privileged intent for full message content access
|
||||
- `GuildMembers`: Access to member data
|
||||
|
||||
### 2.3 Environment Configuration
|
||||
|
||||
Create a `.env` file in the project root with the following variables:
|
||||
|
||||
```env
|
||||
# Discord Bot Configuration
|
||||
TOKEN=your_discord_bot_token
|
||||
|
||||
# Discord Webhooks
|
||||
DEBUG=https://discord.com/api/webhooks/... # Debug/error logging
|
||||
COMM=https://discord.com/api/webhooks/... # Commission notifications
|
||||
DIST=https://discord.com/api/webhooks/... # Distribution notifications
|
||||
NEWS=https://discord.com/api/webhooks/... # Palestine news updates
|
||||
TICKET=https://discord.com/api/webhooks/... # Ticket logs
|
||||
|
||||
# Airtable Configuration
|
||||
AIRTABLE_KEY=your_airtable_api_key
|
||||
AIRTABLE_BASE_ID=your_base_id
|
||||
AIRTABLE_TABLE_ID=your_table_name
|
||||
|
||||
# Server Configuration (optional)
|
||||
NODE_ENV=production # Set to enable HTTPS server on port 10443
|
||||
```
|
||||
|
||||
### 2.4 Hardcoded Configuration
|
||||
|
||||
Several IDs are hardcoded in the `src/config/` directory and must be updated for your server:
|
||||
|
||||
**File: `src/config/Tickets.ts`**
|
||||
- `guildId`: Your Discord server ID
|
||||
- `supportRole`: Your support team role ID
|
||||
|
||||
**File: `src/config/Webhooks.ts`**
|
||||
- `artChannelId`: Channel for art commission posts
|
||||
- `distributionChannelId`: Channel for distribution posts
|
||||
|
||||
**File: `src/config/Trello.ts`**
|
||||
- Trello board, list, and label IDs (if using Trello integration)
|
||||
|
||||
### 2.5 Installation
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/naomi-lgbt/nodejs-typescript-template.git
|
||||
cd nodejs-typescript-template
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
3. Configure environment variables (see section 2.3)
|
||||
|
||||
4. Build the TypeScript code:
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
|
||||
### 2.6 Running the Bot
|
||||
|
||||
Start the bot in production mode:
|
||||
```bash
|
||||
pnpm start
|
||||
```
|
||||
|
||||
This will:
|
||||
- Load environment variables from `.env`
|
||||
- Execute the compiled JavaScript from `prod/index.js`
|
||||
- Connect to Discord
|
||||
- Initialize event listeners and scheduled tasks
|
||||
- Start the HTTP server on port 10080 (HTTP) or 10443 (HTTPS if `NODE_ENV=production`)
|
||||
|
||||
### 2.7 Development Workflow
|
||||
|
||||
For development and testing:
|
||||
|
||||
**Linting:**
|
||||
```bash
|
||||
pnpm lint
|
||||
```
|
||||
Runs ESLint and Prettier to check code style and formatting.
|
||||
|
||||
**Testing:**
|
||||
```bash
|
||||
pnpm test
|
||||
```
|
||||
Runs Mocha test suite with TypeScript support (timeout: 10 seconds).
|
||||
|
||||
**Building:**
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
Compiles TypeScript files from `src/` to JavaScript in `prod/`.
|
||||
|
||||
### 2.8 Architecture Overview
|
||||
|
||||
#### 2.8.1 Project Structure
|
||||
|
||||
```
|
||||
a4p-bot/
|
||||
├── src/
|
||||
│ ├── index.ts # Main entry point, bot initialization
|
||||
│ ├── config/ # Configuration files (channels, webhooks, Trello)
|
||||
│ ├── events/ # Discord event handlers
|
||||
│ ├── modules/ # Core business logic
|
||||
│ │ ├── buttons/ # Button interaction handlers
|
||||
│ │ ├── messages/ # Message processing logic
|
||||
│ │ ├── modals/ # Modal form handlers
|
||||
│ │ └── reminders/ # Scheduled reminder tasks
|
||||
│ ├── interface/ # TypeScript interfaces and types
|
||||
│ ├── server/ # Express HTTP server
|
||||
│ └── utils/ # Utility functions
|
||||
├── prod/ # Compiled JavaScript output
|
||||
├── logs/ # Ticket conversation logs (runtime)
|
||||
└── .env # Environment variables (not committed)
|
||||
```
|
||||
|
||||
#### 2.8.2 Core Components
|
||||
|
||||
**Discord Bot (src/index.ts:1)**
|
||||
- Initializes Discord.js client with required intents
|
||||
- Registers event listeners for messages, reactions, interactions, and member joins
|
||||
- Creates webhook clients for different notification types
|
||||
- Starts HTTP server for monitoring
|
||||
|
||||
**Event Handlers (src/events/)**
|
||||
- `onReady.ts:1`: Initializes scheduled jobs, caches messages, sends startup notification
|
||||
- `onMessageCreate.ts:1`: Handles commands (!mute, !unmute) and ticket message logging
|
||||
- `onInteractionCreate.ts:1`: Routes button clicks and modal submissions
|
||||
- `onReactionAdd.ts:1`: Manages art commission and distribution claims
|
||||
- `onMemberAdd.ts:1`: Auto-assigns member role to new joiners
|
||||
|
||||
**Scheduled Tasks (node-schedule)**
|
||||
- Runs every 60 minutes: Check Airtable for new form submissions
|
||||
- Runs every 10 minutes: Fetch and post Palestine news updates
|
||||
- Monday/Wednesday/Friday 9 AM: Send unclaimed art and distribution reminders
|
||||
- Saturday 9 AM: Send unfinished art and distribution reminders
|
||||
|
||||
**Ticket System (src/modules/)**
|
||||
- `buttons/ticketOpen.ts:1`: Opens modal form for ticket creation
|
||||
- `modals/handleTicketModal.ts:1`: Creates private thread and initializes log file
|
||||
- `buttons/ticketClaim.ts:1`: Adds support member's mention to thread
|
||||
- `buttons/ticketClose.ts:1`: Generates log file, sends to archive, closes thread
|
||||
- `logTicketMessage.ts:1`: Appends messages to log file in real-time
|
||||
- `generateLogs.ts:1`: Reads log file and creates Discord attachment
|
||||
|
||||
**Airtable Integration (src/modules/checkAirtableRecords.ts:1)**
|
||||
- Polls Airtable API for new form submissions
|
||||
- Tracks latest record ID to avoid duplicate processing
|
||||
- Extracts form fields (name, contact info, request details, reference images)
|
||||
- Posts formatted messages to commission channel via webhook
|
||||
|
||||
**News Feed (src/utils/getNewsFeed.ts:1)**
|
||||
- Fetches latest articles from Al Jazeera Palestine live blog via GraphQL
|
||||
- Tracks last posted article ID to prevent duplicates
|
||||
- Sends new updates to news webhook channel
|
||||
|
||||
#### 2.8.3 Data Flow
|
||||
|
||||
```
|
||||
User Action (Discord) → Event Listener → Event Handler → Module Logic
|
||||
↓
|
||||
External API / Webhook Call
|
||||
↓
|
||||
Response/Notification
|
||||
↓
|
||||
Logging (Winston + Debug Webhook)
|
||||
```
|
||||
|
||||
```
|
||||
Scheduled Task → External API (Airtable/Al Jazeera) → Parse Response
|
||||
↓
|
||||
Send to Discord Webhook
|
||||
↓
|
||||
Update Cache/State
|
||||
```
|
||||
|
||||
### 2.9 Database
|
||||
|
||||
While Prisma ORM is installed as a dependency, the Application does not currently use a database. All state is managed in memory using cache objects attached to the extended Discord client:
|
||||
|
||||
- `bot.ticketLogs`: Maps channel IDs to log file message IDs
|
||||
- `bot.lastArticle`: Tracks the most recent news article ID
|
||||
|
||||
Ticket conversation logs are temporarily stored as text files in the `logs/` directory and deleted after being sent to the archive channel.
|
||||
|
||||
### 2.10 API Integrations
|
||||
|
||||
#### 2.10.1 Airtable REST API
|
||||
|
||||
**Endpoint:** `https://api.airtable.com/v0/{BASE_ID}/{TABLE_ID}`
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Headers:**
|
||||
```
|
||||
Authorization: Bearer {AIRTABLE_KEY}
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `maxRecords=100`: Limit results
|
||||
- `sort[0][field]=Created`: Sort by creation time
|
||||
- `sort[0][direction]=desc`: Newest first
|
||||
|
||||
**Response Structure (src/interface/AirtableResponse.ts:1):**
|
||||
```typescript
|
||||
{
|
||||
records: [{
|
||||
id: string;
|
||||
createdTime: string;
|
||||
fields: {
|
||||
Name: string;
|
||||
"Contact Method": "Email" | "Discord" | "Twitter";
|
||||
Handle: string;
|
||||
"What would you like us to draw?": string;
|
||||
"Anything Else?": string;
|
||||
Reference?: { url: string }[];
|
||||
}
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.10.2 Al Jazeera GraphQL API
|
||||
|
||||
**Endpoint:** `https://www.aljazeera.com/graphql` (inferred from code)
|
||||
|
||||
**Operations:**
|
||||
- `SingleLiveBlogChildrensQuery`: Fetch live blog structure
|
||||
- `LiveBlogUpdateQuery`: Fetch latest blog updates
|
||||
|
||||
The bot extracts article content and posts to the news webhook channel.
|
||||
|
||||
### 2.11 HTTP Server
|
||||
|
||||
The Application includes a minimal Express server (src/server/serve.ts:1):
|
||||
|
||||
**Endpoints:**
|
||||
- `GET /` - Returns HTML landing page with project information
|
||||
|
||||
**Ports:**
|
||||
- HTTP: 10080 (default)
|
||||
- HTTPS: 10443 (when `NODE_ENV=production`)
|
||||
|
||||
Note: The server file includes a TODO comment suggesting deletion after Trello integration is complete.
|
||||
|
||||
### 2.12 Logging
|
||||
|
||||
The Application uses Winston for structured logging (src/utils/logHandler.ts:1):
|
||||
|
||||
**Log Levels:**
|
||||
- `info`: General information (bot startup, scheduled task execution)
|
||||
- `error`: Error conditions (API failures, Discord errors)
|
||||
|
||||
**Log Format:**
|
||||
```
|
||||
[TIMESTAMP] LEVEL: MESSAGE
|
||||
```
|
||||
|
||||
**Log Destinations:**
|
||||
- Console (stdout)
|
||||
- Debug webhook (errors only)
|
||||
|
||||
### 2.13 Error Handling
|
||||
|
||||
All errors are caught and:
|
||||
1. Logged to console via Winston
|
||||
2. Sent to the debug webhook with error details
|
||||
3. Presented to users with friendly messages (when applicable)
|
||||
|
||||
Example error flow (src/modules/checkAirtableRecords.ts):
|
||||
```typescript
|
||||
try {
|
||||
// API call
|
||||
} catch (error) {
|
||||
logHandler.error("Error message", error);
|
||||
debugHook.send({ content: "Error details" });
|
||||
}
|
||||
```
|
||||
|
||||
### 2.14 Performance Considerations
|
||||
|
||||
- **Message Caching**: Fetches messages in batches of 100 to reduce API calls
|
||||
- **Duplicate Prevention**: Tracks latest Airtable record ID and news article ID
|
||||
- **Rate Limiting**:
|
||||
- Airtable: 60-minute polling interval
|
||||
- News API: 10-minute polling interval
|
||||
- **Concurrent Limits**: Artists/distributors limited to 2 active tasks each
|
||||
|
||||
### 2.15 Security Considerations
|
||||
|
||||
- **Environment Variables**: Sensitive tokens stored in `.env` (not committed)
|
||||
- **Role Verification**: Commands require support role for execution (src/events/onMessageCreate.ts:1)
|
||||
- **Webhook Validation**: Checks webhook existence before use (src/utils/isValidWebhook.ts:1)
|
||||
- **Privileged Intents**: Requires approval from Discord for `MessageContent` intent
|
||||
|
||||
### 2.16 Troubleshooting
|
||||
|
||||
**Bot doesn't start:**
|
||||
- Verify `TOKEN` is valid in `.env`
|
||||
- Check Node.js version is 22
|
||||
- Ensure all dependencies are installed: `pnpm install`
|
||||
|
||||
**Webhooks not working:**
|
||||
- Verify webhook URLs are valid and accessible
|
||||
- Check webhook permissions in Discord channel settings
|
||||
- Use `isValidWebhook` utility for validation
|
||||
|
||||
**Airtable integration failing:**
|
||||
- Verify `AIRTABLE_KEY`, `AIRTABLE_BASE_ID`, and `AIRTABLE_TABLE_ID`
|
||||
- Check Airtable API permissions
|
||||
- Review Airtable API rate limits
|
||||
|
||||
**Scheduled tasks not running:**
|
||||
- Check server timezone matches expected cron schedule
|
||||
- Review `onReady.ts` for cron expression syntax
|
||||
- Check debug webhook for error messages
|
||||
|
||||
**Ticket logs not saving:**
|
||||
- Verify write permissions for `logs/` directory
|
||||
- Check disk space availability
|
||||
- Review console for Winston logging errors
|
||||
|
||||
---
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
### 3.1 Terms of Service
|
||||
|
||||
The Application is subject to our global Terms of Service, which can be found at:
|
||||
|
||||
https://docs.nhcarrigan.com/#/terms
|
||||
|
||||
### 3.2 Privacy Policy
|
||||
|
||||
The Application's privacy practices are governed by our global Privacy Policy, which can be found at:
|
||||
|
||||
https://docs.nhcarrigan.com/#/privacy
|
||||
|
||||
#### 3.2.1 Data Collection
|
||||
|
||||
The Application collects and temporarily stores the following data:
|
||||
|
||||
**Discord Data:**
|
||||
- User IDs (for role assignment, moderation, and ticket management)
|
||||
- Message content in ticket threads (logged to text files)
|
||||
- Reaction events (for tracking commission/distribution claims)
|
||||
- Member join events (for auto-role assignment)
|
||||
|
||||
**Airtable Data:**
|
||||
- Form submission data (name, contact method, handle, art request details)
|
||||
- Reference images (URLs only)
|
||||
- Submission timestamps and record IDs
|
||||
|
||||
**Temporary Storage:**
|
||||
- Ticket conversation logs (stored as text files, deleted after archival)
|
||||
- In-memory cache for article IDs and ticket log mappings
|
||||
|
||||
**Data Retention:**
|
||||
- Ticket logs: Deleted immediately after being sent to the archive channel
|
||||
- Cached data: Cleared on bot restart
|
||||
- Airtable record IDs: Stored in memory to prevent duplicate processing
|
||||
|
||||
**Third-Party Services:**
|
||||
The Application integrates with:
|
||||
- Discord (message delivery and bot functionality)
|
||||
- Airtable (form submission retrieval)
|
||||
- Al Jazeera (public news feed)
|
||||
- Trello (configuration only, no active integration)
|
||||
|
||||
Users should review the privacy policies of these services for their data handling practices.
|
||||
|
||||
### 3.3 License
|
||||
|
||||
This software is licensed under our global software license:
|
||||
|
||||
https://docs.nhcarrigan.com/#/license
|
||||
|
||||
**Copyright:** Held by Naomi Carrigan
|
||||
|
||||
**License Type:** Proprietary (see link above for full terms)
|
||||
|
||||
### 3.4 Code of Conduct
|
||||
|
||||
All contributors and users must adhere to our Code of Conduct:
|
||||
|
||||
See: `CODE_OF_CONDUCT.md` in the repository root
|
||||
|
||||
### 3.5 Security Policy
|
||||
|
||||
Security vulnerabilities should be reported according to our Security Policy:
|
||||
|
||||
See: `SECURITY.md` in the repository root
|
||||
|
||||
For security concerns, please contact us through:
|
||||
- Chat Server: http://chat.nhcarrigan.com
|
||||
- Email: contact@nhcarrigan.com
|
||||
|
||||
### 3.6 Disclaimer
|
||||
|
||||
The Application is provided for the specific purpose of facilitating the Art for Palestine charity event. While we strive for reliability and accuracy, the Application is provided "as-is" without warranties of any kind.
|
||||
|
||||
**Moderation Actions:** The Application includes moderation features (mute/unmute). Server administrators and support team members are responsible for using these features in accordance with Discord's Terms of Service and Community Guidelines.
|
||||
|
||||
**External Content:** The Application fetches and displays news content from Al Jazeera. We do not control or endorse this content and are not responsible for its accuracy or appropriateness.
|
||||
|
||||
**Charity Event:** This Application is specifically designed for the Art for Palestine charity event. For questions about the event itself, please visit https://art4palestine.org or contact the event organizers.
|
||||
|
||||
---
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
### 4.1 Contributing Guidelines
|
||||
|
||||
Our complete contributing guidelines can be found at:
|
||||
|
||||
https://docs.nhcarrigan.com/#/contributing
|
||||
|
||||
### 4.2 Getting Started with Development
|
||||
|
||||
1. **Fork the Repository**
|
||||
```bash
|
||||
# Visit GitHub and fork the repository to your account
|
||||
```
|
||||
|
||||
2. **Clone Your Fork**
|
||||
```bash
|
||||
git clone https://github.com/YOUR_USERNAME/nodejs-typescript-template.git
|
||||
cd nodejs-typescript-template
|
||||
```
|
||||
|
||||
3. **Install Dependencies**
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
4. **Set Up Environment**
|
||||
- Create a `.env` file (see section 2.3)
|
||||
- Create a test Discord server and bot
|
||||
- Configure test webhooks
|
||||
|
||||
5. **Create a Branch**
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
### 4.3 Code Style and Standards
|
||||
|
||||
The project enforces code style through automated tooling:
|
||||
|
||||
**ESLint Configuration:**
|
||||
- Extends `@nhcarrigan/eslint-config`
|
||||
- Maximum warnings allowed: 0 (all warnings treated as errors)
|
||||
- Checks both `src/` and `test/` directories
|
||||
|
||||
**Prettier Configuration:**
|
||||
- Extends `@nhcarrigan/prettier-config`
|
||||
- Enforces consistent formatting
|
||||
|
||||
**TypeScript Configuration:**
|
||||
- Extends `@nhcarrigan/typescript-config`
|
||||
- Strict type checking enabled
|
||||
- Root directory: `./src`
|
||||
- Output directory: `./prod`
|
||||
|
||||
**Running Linters:**
|
||||
```bash
|
||||
pnpm lint
|
||||
```
|
||||
|
||||
**Auto-Fixing Issues:**
|
||||
```bash
|
||||
# Fix ESLint issues
|
||||
npx eslint src test --fix
|
||||
|
||||
# Fix Prettier issues
|
||||
npx prettier src test --write
|
||||
```
|
||||
|
||||
### 4.4 Writing Tests
|
||||
|
||||
The project uses Mocha and Chai for testing:
|
||||
|
||||
**Test Structure:**
|
||||
- Test files: `test/**/*.spec.ts`
|
||||
- Test style: TDD (Test-Driven Development)
|
||||
- Timeout: 10 seconds per test
|
||||
- Type: TypeScript (via ts-mocha)
|
||||
|
||||
**Running Tests:**
|
||||
```bash
|
||||
pnpm test
|
||||
```
|
||||
|
||||
**Writing a Test:**
|
||||
```typescript
|
||||
import { expect } from "chai";
|
||||
import { suite, test } from "mocha";
|
||||
|
||||
suite("Feature Name", () => {
|
||||
test("should do something", () => {
|
||||
// Arrange
|
||||
const input = "test";
|
||||
|
||||
// Act
|
||||
const result = myFunction(input);
|
||||
|
||||
// Assert
|
||||
expect(result).to.equal("expected");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 4.5 Documentation Standards
|
||||
|
||||
**JSDoc Comments:**
|
||||
All functions, classes, and complex logic should include JSDoc comments:
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Brief description of the function.
|
||||
*
|
||||
* @param {Type} paramName - Parameter description
|
||||
* @returns {Type} Return value description
|
||||
*/
|
||||
function myFunction(paramName: Type): Type {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
**Inline Comments:**
|
||||
Use inline comments for complex logic:
|
||||
```typescript
|
||||
// Explanation of why this approach is used
|
||||
const result = complexOperation();
|
||||
```
|
||||
|
||||
**Commit Messages:**
|
||||
Follow conventional commit format:
|
||||
- `feat: Add new feature`
|
||||
- `fix: Resolve bug in ticket system`
|
||||
- `docs: Update README`
|
||||
- `chore: Update dependencies`
|
||||
- `refactor: Restructure event handlers`
|
||||
- `test: Add tests for webhook validation`
|
||||
|
||||
### 4.6 Pull Request Process
|
||||
|
||||
1. **Ensure All Checks Pass:**
|
||||
- Run `pnpm lint` (must pass with 0 warnings)
|
||||
- Run `pnpm test` (all tests must pass)
|
||||
- Run `pnpm build` (must compile without errors)
|
||||
|
||||
2. **Create Pull Request:**
|
||||
- Use a descriptive title
|
||||
- Provide detailed description of changes
|
||||
- Reference any related issues
|
||||
- Include screenshots/videos for UI changes
|
||||
|
||||
3. **Code Review:**
|
||||
- Address reviewer feedback
|
||||
- Make requested changes
|
||||
- Re-request review after updates
|
||||
|
||||
4. **Merge:**
|
||||
- Maintainers will merge approved PRs
|
||||
- Squash and merge is preferred for clean history
|
||||
|
||||
### 4.7 Areas for Contribution
|
||||
|
||||
The project welcomes contributions in these areas:
|
||||
|
||||
**Feature Enhancements:**
|
||||
- Trello integration completion (see TODO in `src/server/serve.ts`)
|
||||
- Database integration using Prisma (currently installed but unused)
|
||||
- Additional moderation commands
|
||||
- Enhanced reporting and analytics
|
||||
|
||||
**Bug Fixes:**
|
||||
- Report bugs via GitHub Issues
|
||||
- Include reproduction steps and environment details
|
||||
- PRs to fix bugs are highly appreciated
|
||||
|
||||
**Documentation:**
|
||||
- Improve code comments
|
||||
- Expand user guides
|
||||
- Add troubleshooting sections
|
||||
- Create video tutorials
|
||||
|
||||
**Testing:**
|
||||
- Increase test coverage
|
||||
- Add integration tests
|
||||
- Create test utilities
|
||||
|
||||
**Performance:**
|
||||
- Optimize message caching
|
||||
- Reduce webhook API calls
|
||||
- Improve scheduled task efficiency
|
||||
|
||||
### 4.8 Development Environment Setup
|
||||
|
||||
**Recommended Tools:**
|
||||
- **Editor:** VS Code (or any TypeScript-compatible editor)
|
||||
- **Extensions:**
|
||||
- ESLint
|
||||
- Prettier
|
||||
- TypeScript and JavaScript Language Features
|
||||
- **Node Version Manager:** nvm (for managing Node.js versions)
|
||||
- **Package Manager:** pnpm 10
|
||||
|
||||
**Discord Developer Portal Setup:**
|
||||
1. Create a new application at https://discord.com/developers/applications
|
||||
2. Create a bot user
|
||||
3. Enable required privileged intents: `Message Content`, `Server Members`
|
||||
4. Generate and save bot token
|
||||
5. Invite bot to test server with required permissions
|
||||
|
||||
**Webhook Setup:**
|
||||
1. Create test channels in your Discord server
|
||||
2. Go to channel settings → Integrations → Webhooks
|
||||
3. Create webhooks for: debug, comm, dist, news, ticket
|
||||
4. Copy webhook URLs to `.env`
|
||||
|
||||
### 4.9 Debugging
|
||||
|
||||
**Console Logging:**
|
||||
The project uses Winston for logging. To add debug logs:
|
||||
|
||||
```typescript
|
||||
import { logHandler } from "./utils/logHandler.js";
|
||||
|
||||
logHandler.info("Informational message");
|
||||
logHandler.error("Error message", error);
|
||||
```
|
||||
|
||||
**Discord Debug Webhook:**
|
||||
Error details are automatically sent to the debug webhook. Check this channel for runtime errors.
|
||||
|
||||
**VS Code Launch Configuration:**
|
||||
Create `.vscode/launch.json`:
|
||||
```json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"type": "node",
|
||||
"request": "launch",
|
||||
"name": "Debug Bot",
|
||||
"runtimeArgs": ["-r", "dotenv/config"],
|
||||
"program": "${workspaceFolder}/prod/index.js",
|
||||
"preLaunchTask": "npm: build",
|
||||
"outFiles": ["${workspaceFolder}/prod/**/*.js"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 4.10 Common Development Tasks
|
||||
|
||||
**Adding a New Command:**
|
||||
1. Add handler logic to `src/events/onMessageCreate.ts`
|
||||
2. Implement command functionality in `src/modules/`
|
||||
3. Update user documentation (section 1)
|
||||
4. Add tests in `test/`
|
||||
|
||||
**Adding a New Button:**
|
||||
1. Create button handler in `src/modules/buttons/`
|
||||
2. Export handler in button module
|
||||
3. Register handler in `src/events/onInteractionCreate.ts`
|
||||
4. Update user documentation
|
||||
|
||||
**Adding a New Event Listener:**
|
||||
1. Create event handler in `src/events/`
|
||||
2. Register listener in `src/index.ts`
|
||||
3. Add error handling
|
||||
4. Update technical documentation
|
||||
|
||||
**Modifying Configuration:**
|
||||
1. Update relevant file in `src/config/`
|
||||
2. Document changes in section 2.4
|
||||
3. Update environment variable documentation if needed
|
||||
|
||||
### 4.11 Release Process
|
||||
|
||||
(For maintainers)
|
||||
|
||||
1. **Version Bump:**
|
||||
- Update version in `package.json`
|
||||
- Follow semantic versioning (MAJOR.MINOR.PATCH)
|
||||
|
||||
2. **Changelog:**
|
||||
- Document all changes since last release
|
||||
- Include breaking changes, features, and bug fixes
|
||||
|
||||
3. **Testing:**
|
||||
- Run full test suite
|
||||
- Test in staging environment
|
||||
- Verify all integrations work
|
||||
|
||||
4. **Deployment:**
|
||||
- Build production bundle: `pnpm build`
|
||||
- Deploy to production server
|
||||
- Monitor logs for issues
|
||||
|
||||
5. **Tag Release:**
|
||||
```bash
|
||||
git tag -a v2.0.0 -m "Release version 2.0.0"
|
||||
git push origin v2.0.0
|
||||
```
|
||||
|
||||
### 4.12 Contact for Contributors
|
||||
|
||||
If you have questions about contributing:
|
||||
|
||||
- **GitHub Issues:** https://github.com/naomi-lgbt/nodejs-typescript-template/issues
|
||||
- **Chat Server:** http://chat.nhcarrigan.com
|
||||
- **Email:** contact@nhcarrigan.com
|
||||
|
||||
We review pull requests as soon as possible and appreciate all contributions to the project.
|
||||
|
||||
---
|
||||
|
||||
**Document Version:** 1.0.0
|
||||
**Last Updated:** 2025-10-29
|
||||
**Maintained By:** Naomi Carrigan
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Aeris
|
||||
---
|
||||
|
||||
Aeris (hereinafter the "Application") is an authentication service featuring magic links and support for multiple social media platforms
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Alouette
|
||||
---
|
||||
|
||||
Alouette (hereinafter the "Application") is a web server that allows you to set up arbitrary webhooks and format them to post on Discord.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,441 @@
|
||||
---
|
||||
title: Amari
|
||||
---
|
||||
|
||||
Amari (hereinafter the "Application") is Naomi's Virtual Personal Assistant on Discord, designed to automate community management, content aggregation, mentorship program coordination, and integration with external services such as GitHub, RetroAchievements, and Baserow.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
### 1.1 Interacting with Amari
|
||||
|
||||
#### 1.1.1 Direct Messages
|
||||
|
||||
When you send a Direct Message to Amari, the bot will automatically forward your message to Naomi and respond with an acknowledgment. This provides a direct communication channel to reach Naomi through the bot.
|
||||
|
||||
Implementation: `src/modules/respondToDm.ts:19`
|
||||
|
||||
#### 1.1.2 Mentions
|
||||
|
||||
Amari monitors messages in the Discord server for mentions of "Naomi" or "@NHCarrigan" (user or role). When detected, the bot forwards the message to Naomi for review, helping ensure important messages are not missed. To prevent spam, Amari will not forward mentions from channels that have been active in the last 10 minutes.
|
||||
|
||||
Implementation: `src/modules/respondToMention.ts:20`
|
||||
|
||||
### 1.2 Mentorship Program
|
||||
|
||||
#### 1.2.1 Joining the Program
|
||||
|
||||
When you receive the Mentorship role, Amari will automatically send a welcome message in the mentee chat channel with onboarding instructions, including:
|
||||
- Accepting the GitHub repository invitation
|
||||
- Reading the mentorship wiki
|
||||
- Creating your initial goal post
|
||||
|
||||
Implementation: `src/modules/processMentorshipRole.ts:20`
|
||||
|
||||
#### 1.2.2 Forum Thread Management
|
||||
|
||||
Amari automatically manages thread tags in mentorship forums (Goals, Projects, Resume Reviews, and Discussions) to track whose turn it is to respond:
|
||||
- When Naomi responds to your thread, the tag changes to "Waiting on Member"
|
||||
- When you respond, the tag changes to "Waiting on Naomi"
|
||||
|
||||
Implementation: `src/modules/updateMentorshipThread.ts:43`
|
||||
|
||||
#### 1.2.3 Progress Reminders
|
||||
|
||||
Every weekday (Monday-Friday) at 9:00 AM, Amari posts progress reminders in configured channels. These reminders prompt you to share:
|
||||
1. What you accomplished yesterday
|
||||
2. What you're working on today
|
||||
3. Any blockers or issues you need help with
|
||||
|
||||
Implementation: `src/modules/postProgressReminders.ts:16`
|
||||
|
||||
### 1.3 Content and News
|
||||
|
||||
#### 1.3.1 Tech News Feed
|
||||
|
||||
Amari automatically posts new articles from two sources every hour:
|
||||
- **FreeCodeCamp News**: Articles are filtered for inappropriate content before posting
|
||||
- **Hacker News**: Latest posts with comment links
|
||||
|
||||
Implementation: `src/modules/postNews.ts:40` and `src/modules/postNews.ts:95`
|
||||
|
||||
#### 1.3.2 RetroAchievements
|
||||
|
||||
If Naomi unlocks any RetroAchievements, Amari posts them to the gaming channel every 10 minutes. These posts include:
|
||||
- Achievement title and description
|
||||
- Game title and console
|
||||
- Point value
|
||||
- Badge images
|
||||
|
||||
Implementation: `src/modules/checkAchievements.ts:87`
|
||||
|
||||
### 1.4 Form Submissions
|
||||
|
||||
When you submit a form through the Baserow system, Amari posts a notification to the form submissions channel. Supported forms include:
|
||||
- Sanction Appeals
|
||||
- Commission Requests
|
||||
- Contact Requests
|
||||
- Event Requests
|
||||
- Meeting Requests
|
||||
- Mentorship Requests
|
||||
- Staff Applications
|
||||
- Testimonials
|
||||
- ASCII Submissions
|
||||
- Contributor Applications
|
||||
- Guild Wars Officer/Leader Applications
|
||||
- Product and Community Feedback
|
||||
- Community Nominations
|
||||
|
||||
Implementation: `src/modules/processFormSubmission.ts:22` and `src/config/forms.ts:9`
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
### 2.1 Prerequisites
|
||||
|
||||
- Node.js (compatible with the version specified in package.json)
|
||||
- pnpm 10.15.0 or higher
|
||||
- A Discord Bot Token
|
||||
- GitHub App credentials (Client ID and Private Key)
|
||||
- RetroAchievements API Key (optional, for achievements feature)
|
||||
- Baserow webhook secret (optional, for form submissions)
|
||||
|
||||
### 2.2 Environment Variables
|
||||
|
||||
The following environment variables must be configured:
|
||||
|
||||
| Variable | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `BOT_TOKEN` | Yes | Discord bot token |
|
||||
| `GH_CLIENT_ID` | Yes | GitHub App client ID |
|
||||
| `GH_PRIVATE_KEY` | Yes | GitHub App private key (with newlines as `\\n`) |
|
||||
| `GH_WEBHOOK_SECRET` | No | Secret for validating GitHub webhook payloads |
|
||||
| `RA_KEY` | No | RetroAchievements API key |
|
||||
| `BASEROW_SECRET` | No | Secret for validating Baserow webhook payloads |
|
||||
|
||||
### 2.3 Installation
|
||||
|
||||
1. Clone the repository
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
3. Build the TypeScript code:
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
4. Configure environment variables (see section 2.2)
|
||||
|
||||
5. Start the application:
|
||||
```bash
|
||||
pnpm start
|
||||
```
|
||||
|
||||
Implementation: `src/index.ts:1`
|
||||
|
||||
### 2.4 Configuration
|
||||
|
||||
#### 2.4.1 Discord IDs
|
||||
|
||||
All Discord-specific IDs (channels, roles, users, guilds, tags) are configured in `src/config/ids.ts`. You will need to update these IDs to match your Discord server setup:
|
||||
|
||||
- **Channels**: Form submissions, gaming, general, mentee chat, forums, news
|
||||
- **Roles**: Mentorship, nhcarrigan, representing
|
||||
- **Users**: Amari (bot), Naomi, nhcarrigan
|
||||
- **Tags**: Forum tags for tracking thread status
|
||||
|
||||
Implementation: `src/config/ids.ts:7`
|
||||
|
||||
#### 2.4.2 Form IDs
|
||||
|
||||
Form submission notifications are configured in `src/config/forms.ts`. Map Baserow table IDs to human-readable form names.
|
||||
|
||||
Implementation: `src/config/forms.ts:9`
|
||||
|
||||
#### 2.4.3 Progress Reminders
|
||||
|
||||
Progress reminder channels are configured in `src/config/progressReminders.ts`. Configure which channels should receive reminders, associated role IDs, and whether to create threads.
|
||||
|
||||
Implementation: `src/config/progressReminders.ts:1`
|
||||
|
||||
#### 2.4.4 DM Response
|
||||
|
||||
The automatic response sent when users DM the bot is configured in `src/config/responses.ts`.
|
||||
|
||||
Implementation: `src/config/responses.ts:1`
|
||||
|
||||
### 2.5 Architecture
|
||||
|
||||
#### 2.5.1 Core Components
|
||||
|
||||
The Application consists of several key components:
|
||||
|
||||
1. **Discord Bot** (`discord.js`): Handles all Discord interactions
|
||||
2. **GitHub Integration** (`octokit`): Manages GitHub webhooks and API interactions
|
||||
3. **Web Server** (`fastify`): Receives webhooks and serves health monitoring page
|
||||
4. **Scheduled Jobs** (`node-schedule`): Executes periodic tasks (news, reminders, etc.)
|
||||
5. **Analytics** (`@nhcarrigan/discord-analytics`): Tracks bot usage metrics
|
||||
|
||||
Main entry point: `src/index.ts:1`
|
||||
|
||||
#### 2.5.2 Event Handlers
|
||||
|
||||
The bot responds to the following Discord events:
|
||||
|
||||
- `ClientReady`: Initialize scheduled jobs and cache data (src/index.ts:65)
|
||||
- `MessageCreate`: Handle guild messages and DMs (src/index.ts:89)
|
||||
- `InteractionCreate`: Handle button interactions (src/index.ts:97)
|
||||
- `UserUpdate`: Process guild tag changes (src/index.ts:117)
|
||||
- `GuildMemberUpdate`: Process mentorship role assignments (src/index.ts:121)
|
||||
- `GuildMemberAdd`: Log when mentees join (src/index.ts:125)
|
||||
- `GuildMemberRemove`: Log when mentees leave (src/index.ts:129)
|
||||
|
||||
#### 2.5.3 Scheduled Tasks
|
||||
|
||||
The following tasks run on a schedule:
|
||||
|
||||
- **Hourly** (0 * * * *): Post news from FreeCodeCamp and Hacker News
|
||||
- **Daily at Midnight** (0 0 * * *): Audit and cache guild tags
|
||||
- **Weekdays at 9 AM** (0 9 * * 1-5): Post progress reminders
|
||||
- **Every 10 minutes** (interval): Check RetroAchievements and clear recently active channels
|
||||
|
||||
Implementation: `src/index.ts:70-86`
|
||||
|
||||
#### 2.5.4 Web Server Endpoints
|
||||
|
||||
The Fastify web server provides the following endpoints:
|
||||
|
||||
- `GET /`: Health monitoring page with bot information
|
||||
- `POST /github`: Webhook endpoint for GitHub events (issues, pull requests)
|
||||
- `POST /form`: Webhook endpoint for Baserow form submissions
|
||||
|
||||
The server listens on port 7044.
|
||||
|
||||
Implementation: `src/server/serve.ts:61`
|
||||
|
||||
### 2.6 Content Filtering
|
||||
|
||||
FreeCodeCamp News posts are filtered for inappropriate content using a comprehensive regular expression that detects violations of the Code of Conduct. The regex is defined in `src/modules/postNews.ts:23` and checks for:
|
||||
|
||||
- Harassment, bullying, and discrimination
|
||||
- Hate speech and slurs
|
||||
- Explicit, violent, or illegal content
|
||||
- Spam, scams, and fraud
|
||||
- Drug-related content
|
||||
- Violence and illegal activities
|
||||
|
||||
Posts matching these patterns are automatically rejected and not posted to Discord.
|
||||
|
||||
### 2.7 GitHub Integration
|
||||
|
||||
When GitHub webhooks are received:
|
||||
|
||||
1. **New Issues** (`opened` action): Amari automatically assigns Naomi to the issue
|
||||
2. **New Pull Requests** (`opened` action): Amari automatically requests Naomi as a reviewer
|
||||
|
||||
Implementation: `src/modules/processGitHubEvent.ts:31`
|
||||
|
||||
### 2.8 Development
|
||||
|
||||
#### 2.8.1 Available Scripts
|
||||
|
||||
- `pnpm run build`: Compile TypeScript to JavaScript
|
||||
- `pnpm start`: Start the production server (uses 1Password for environment variables)
|
||||
- `pnpm run lint`: Run ESLint with zero warnings policy
|
||||
- `pnpm test`: Run tests (currently placeholder)
|
||||
|
||||
#### 2.8.2 Code Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── config/ # Configuration files (IDs, forms, responses, reminders)
|
||||
├── events/ # Discord event handlers
|
||||
├── interfaces/ # TypeScript interfaces
|
||||
├── modules/ # Core functionality modules
|
||||
├── server/ # Fastify web server
|
||||
├── utils/ # Utility functions
|
||||
└── index.ts # Application entry point
|
||||
```
|
||||
|
||||
#### 2.8.3 Dependencies
|
||||
|
||||
Key dependencies:
|
||||
- `discord.js` v14.22.0: Discord API wrapper
|
||||
- `fastify` v5.5.0: Web server framework
|
||||
- `octokit` v5.0.3: GitHub API client
|
||||
- `node-schedule` v2.1.1: Cron job scheduler
|
||||
- `rss-parser` v3.13.0: RSS feed parser
|
||||
- `@retroachievements/api` v2.6.0: RetroAchievements API client
|
||||
- `@nhcarrigan/discord-analytics` v0.0.6: Analytics tracking
|
||||
- `@nhcarrigan/logger` v1.1.1: Logging utility
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
### 3.1 License
|
||||
|
||||
This software is licensed under Naomi's Public License. The full license text is available in the `LICENSE.md` file in the repository root.
|
||||
|
||||
Copyright held by Naomi Carrigan.
|
||||
|
||||
### 3.2 Code of Conduct
|
||||
|
||||
All users interacting with the Application, whether through Discord or by contributing to the codebase, must adhere to the Code of Conduct defined in `CODE_OF_CONDUCT.md`.
|
||||
|
||||
### 3.3 Content Filtering
|
||||
|
||||
The Application implements automated content filtering for RSS feeds to ensure posted content complies with the community's Code of Conduct. While this filtering attempts to catch policy violations, it may not be perfect. Users should report any inappropriate content that bypasses the filters.
|
||||
|
||||
### 3.4 Data Collection
|
||||
|
||||
The Application collects the following data for operational purposes:
|
||||
|
||||
- Discord user IDs and message content (forwarded to Naomi for mentions/DMs)
|
||||
- GitHub usernames (for webhook processing)
|
||||
- Form submission data (row IDs and table identifiers)
|
||||
- Analytics metrics (event counts and associated metadata)
|
||||
|
||||
All data is processed in accordance with Naomi's privacy policies.
|
||||
|
||||
### 3.5 Third-Party Services
|
||||
|
||||
The Application integrates with several third-party services:
|
||||
|
||||
- **Discord**: Communication platform (Terms of Service apply)
|
||||
- **GitHub**: Code hosting and webhook integration (Terms of Service apply)
|
||||
- **RetroAchievements**: Gaming achievement tracking (Terms of Service apply)
|
||||
- **Baserow**: Form submission processing (Terms of Service apply)
|
||||
|
||||
Users of the Application are subject to the terms of service of these platforms.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
### 4.1 Getting Started
|
||||
|
||||
Before contributing, please:
|
||||
|
||||
1. Read the `CONTRIBUTING.md` file for contribution guidelines
|
||||
2. Review the `CODE_OF_CONDUCT.md` to understand community standards
|
||||
3. Familiarize yourself with the codebase structure (see section 2.8.2)
|
||||
|
||||
### 4.2 Development Setup
|
||||
|
||||
1. Fork the repository
|
||||
2. Clone your fork locally
|
||||
3. Install dependencies: `pnpm install`
|
||||
4. Create a feature branch: `git checkout -b feature/your-feature-name`
|
||||
5. Make your changes
|
||||
6. Run linting: `pnpm run lint`
|
||||
7. Build the project: `pnpm run build`
|
||||
8. Test your changes with a local instance
|
||||
|
||||
### 4.3 Code Standards
|
||||
|
||||
The project enforces the following standards:
|
||||
|
||||
- **TypeScript**: All code must be written in TypeScript
|
||||
- **ESLint**: Code must pass linting with zero warnings (`@nhcarrigan/eslint-config`)
|
||||
- **TypeScript Config**: Uses `@nhcarrigan/typescript-config`
|
||||
- **File Headers**: All files must include copyright header with license and author information
|
||||
|
||||
Example header:
|
||||
```typescript
|
||||
/**
|
||||
* @copyright NHCarrigan
|
||||
* @license Naomi's Public License
|
||||
* @author Naomi Carrigan
|
||||
*/
|
||||
```
|
||||
|
||||
### 4.4 Module Guidelines
|
||||
|
||||
When creating or modifying modules:
|
||||
|
||||
1. **Single Responsibility**: Each module should handle one specific feature
|
||||
2. **Error Handling**: Use try-catch blocks and log errors with the logger utility
|
||||
3. **Type Safety**: Define interfaces for all data structures
|
||||
4. **Documentation**: Include JSDoc comments for all exported functions
|
||||
5. **Testing**: Consider how your changes can be tested (when tests are implemented)
|
||||
|
||||
### 4.5 Adding New Features
|
||||
|
||||
When adding new features:
|
||||
|
||||
1. **Configuration**: Add any new IDs or configuration to appropriate config files
|
||||
2. **Interfaces**: Define TypeScript interfaces in the `src/interfaces/` directory
|
||||
3. **Modules**: Create new modules in `src/modules/` for self-contained functionality
|
||||
4. **Events**: Add event handlers in `src/events/` if needed
|
||||
5. **Server Routes**: Add new endpoints in `src/server/serve.ts` if needed
|
||||
6. **Documentation**: Update this documentation file to reflect new features
|
||||
|
||||
### 4.6 Submitting Changes
|
||||
|
||||
1. Commit your changes with descriptive commit messages
|
||||
2. Push to your fork
|
||||
3. Create a Pull Request to the main repository
|
||||
4. Amari will automatically request Naomi as a reviewer
|
||||
5. Address any review feedback
|
||||
6. Once approved, your changes will be merged
|
||||
|
||||
### 4.7 Key Files for Contributors
|
||||
|
||||
- `src/index.ts`: Main application entry point
|
||||
- `src/config/ids.ts`: Discord server IDs configuration
|
||||
- `src/interfaces/amari.ts`: Core application state interface
|
||||
- `src/server/serve.ts`: Web server and webhook handlers
|
||||
- `src/modules/`: Individual feature implementations
|
||||
- `package.json`: Dependencies and scripts
|
||||
|
||||
### 4.8 Common Tasks
|
||||
|
||||
#### Adding a New Form Type
|
||||
|
||||
1. Add the table ID and name to `src/config/forms.ts`
|
||||
2. The form notification will automatically work via `src/modules/processFormSubmission.ts`
|
||||
|
||||
#### Adding a New Scheduled Task
|
||||
|
||||
1. Add the schedule in `src/index.ts` within the `ClientReady` event handler
|
||||
2. Use `node-schedule` cron syntax
|
||||
3. Create a new module in `src/modules/` for the task logic
|
||||
|
||||
#### Adding a New Discord Event Handler
|
||||
|
||||
1. Create a handler module in `src/modules/` or `src/events/`
|
||||
2. Register the event listener in `src/index.ts`
|
||||
3. Use the `Amari` interface for accessing bot state
|
||||
|
||||
#### Modifying Webhook Endpoints
|
||||
|
||||
1. Update the route handler in `src/server/serve.ts`
|
||||
2. Define interfaces for payloads in `src/interfaces/`
|
||||
3. Ensure proper authentication checking with secrets
|
||||
|
||||
### 4.9 Support and Questions
|
||||
|
||||
If you have questions about contributing:
|
||||
|
||||
- Open a GitHub issue for bugs or feature requests
|
||||
- Join the Discord server at https://chat.nhcarrigan.com for discussions
|
||||
- Email contact@nhcarrigan.com for private inquiries
|
||||
|
||||
### 4.10 Analytics and Logging
|
||||
|
||||
The Application uses custom logging and analytics:
|
||||
|
||||
- **Logger**: Use `logger.log()`, `logger.error()`, `logger.metric()` from `src/utils/logger.ts`
|
||||
- **Metrics**: Log user actions with `logger.metric()` for analytics tracking
|
||||
- **Error Handling**: Always catch and log errors to help with debugging
|
||||
|
||||
Example:
|
||||
```typescript
|
||||
await logger.metric("processed_event", 1, { user: userId });
|
||||
await logger.error("module name", error);
|
||||
```
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Amirei
|
||||
---
|
||||
|
||||
Amirei (hereinafter the "Application") is a quick social link aggregator for 'link in bio' pages.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Aurelia
|
||||
---
|
||||
|
||||
Aurelia (hereinafter the "Application") is a blogging platform with markdown editor
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Aureline
|
||||
---
|
||||
|
||||
Aureline (hereinafter the "Application") is a web app that allows you to create/upload digital badges and certifications and grant them to users
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
---
|
||||
title: Beccalia: Origins
|
||||
---
|
||||
|
||||
Beccalia: Origins (hereinafter the "Game") is originally planned as the story of Becca and Rosalia growing up, this game was only released as a demo.
|
||||
|
||||
## 1. Player Documentation
|
||||
|
||||
This section is for players who are exploring or playing the Game.
|
||||
|
||||
### Controls
|
||||
|
||||
- **Keyboard / Gamepad:**
|
||||
- Arrow keys / D-Pad: Move character
|
||||
- Z / Enter / A: Confirm / Interact
|
||||
- X / Esc / B: Cancel / Menu
|
||||
- C / Space / Y: Open menu (if applicable)
|
||||
- Shift / L / R: Dash (if enabled)
|
||||
|
||||
- **Touch UI (Mobile / Tablet):**
|
||||
- Tap to move or interact
|
||||
- On-screen buttons for menu and actions
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
- Ensure your device meets RPG Maker MZ requirements.
|
||||
- If the game crashes, try restarting the app or clearing temporary files.
|
||||
- Ask us on discord if persistent issues occur.
|
||||
|
||||
---
|
||||
|
||||
## 2. Developer Documentation
|
||||
|
||||
This section is for those interested in running, modifying, or extending the Game.
|
||||
|
||||
### Engine & Dependencies
|
||||
|
||||
- **Engine:** RPG Maker MZ
|
||||
- **Plugins Used:** none
|
||||
- **Assets:** All original
|
||||
|
||||
### Setup Instructions
|
||||
|
||||
1. Open RPG Maker MZ.
|
||||
2. Load the project folder `beccalia-origins`.
|
||||
3. Use the "Playtest" button to run the Game locally.
|
||||
4. To export, use the "Deployment" feature for target platforms.
|
||||
|
||||
### Directory Structure
|
||||
|
||||
- `data/` — database files (maps, events, actors, items, skills, etc.)
|
||||
- `img/` — graphics (characters, tilesets, animations, pictures, etc.)
|
||||
- `audio/` — music and sound effects
|
||||
- `js/` — plugins and core scripts
|
||||
- `www/` — exported HTML5 build (if deployed for web)
|
||||
|
||||
---
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
This section expands on legal or licensing information specific to the Game.
|
||||
|
||||
### Licensing
|
||||
|
||||
This Game is created using RPG Maker MZ. The game code and original content are the property of NHCarrigan. RPG Maker MZ runtime assets are licensed under the terms provided by KADOKAWA Corporation. All original graphics, music, and story content belong to NHCarrigan and are protected by copyright.
|
||||
|
||||
### Third-Party Notices
|
||||
|
||||
- Any third-party assets, music, or plugins included are credited in game.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
This section is for contributors or collaborators on the Game.
|
||||
|
||||
### How to Contribute
|
||||
|
||||
- Fork or copy the project folder.
|
||||
- Submit patches or mods via Git.
|
||||
|
||||
- Include a changelog and clear notes on modifications.
|
||||
|
||||
### Coding Standards
|
||||
|
||||
- Plugins in `js/plugins/` should follow standard JS conventions.
|
||||
- Comment custom scripts clearly for readability.
|
||||
|
||||
### Art & Audio Guidelines
|
||||
|
||||
- Maintain original resolutions where possible (48x48 tiles, etc.).
|
||||
- Use consistent naming for files in `img/` and `audio/`.
|
||||
|
||||
### Contact
|
||||
|
||||
- For collaboration or questions, ask us on discord.
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
---
|
||||
title: Beccalia: Prologue
|
||||
---
|
||||
|
||||
Beccalia: Prologue (hereinafter the "Game") is an introductory story that sets the stage for the Beccalia universe, featuring Becca and Rosalia.
|
||||
|
||||
## 1. Player Documentation
|
||||
|
||||
This section is for players who are exploring or playing the Game.
|
||||
|
||||
### Controls
|
||||
|
||||
- **Keyboard / Gamepad:**
|
||||
- Arrow keys / D-Pad: Move character
|
||||
- Z / Enter / A: Confirm / Interact
|
||||
- X / Esc / B: Cancel / Menu
|
||||
- C / Space / Y: Open menu (if applicable)
|
||||
- Shift / L / R: Dash (if enabled)
|
||||
|
||||
- **Touch UI (Mobile / Tablet):**
|
||||
- Tap to move or interact
|
||||
- On-screen buttons for menu and actions
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
- Ensure your device meets RPG Maker MZ requirements.
|
||||
- If the game crashes, try restarting the app or clearing temporary files.
|
||||
- Ask us on discord if persistent issues occur.
|
||||
|
||||
---
|
||||
|
||||
## 2. Developer Documentation
|
||||
|
||||
This section is for those interested in running, modifying, or extending the Game.
|
||||
|
||||
### Engine & Dependencies
|
||||
|
||||
- **Engine:** RPG Maker MZ
|
||||
- **Plugins Used:** none
|
||||
- **Assets:** All original
|
||||
|
||||
### Setup Instructions
|
||||
|
||||
1. Open RPG Maker MZ.
|
||||
2. Load the project folder `beccalia-prologue`.
|
||||
3. Use the "Playtest" button to run the Game locally.
|
||||
4. To export, use the "Deployment" feature for target platforms.
|
||||
|
||||
### Directory Structure
|
||||
|
||||
- `data/` — database files (maps, events, actors, items, skills, etc.)
|
||||
- `img/` — graphics (characters, tilesets, animations, pictures, etc.)
|
||||
- `audio/` — music and sound effects
|
||||
- `js/` — plugins and core scripts
|
||||
- `www/` — exported HTML5 build (if deployed for web)
|
||||
|
||||
---
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
This section expands on legal or licensing information specific to the Game.
|
||||
|
||||
### Licensing
|
||||
|
||||
This Game is created using RPG Maker MZ. The game code and original content are the property of NHCarrigan. RPG Maker MZ runtime assets are licensed under the terms provided by KADOKAWA Corporation. All original graphics, music, and story content belong to NHCarrigan and are protected by copyright.
|
||||
|
||||
### Third-Party Notices
|
||||
|
||||
- Any third-party assets, music, or plugins included are credited in game.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
This section is for contributors or collaborators on the Game.
|
||||
|
||||
### How to Contribute
|
||||
|
||||
- Fork or copy the project folder.
|
||||
- Submit patches or mods via Git.
|
||||
|
||||
- Include a changelog and clear notes on modifications.
|
||||
|
||||
### Coding Standards
|
||||
|
||||
- Plugins in `js/plugins/` should follow standard JS conventions.
|
||||
- Comment custom scripts clearly for readability.
|
||||
|
||||
### Art & Audio Guidelines
|
||||
|
||||
- Maintain original resolutions where possible (48x48 tiles, etc.).
|
||||
- Use consistent naming for files in `img/` and `audio/`.
|
||||
|
||||
### Contact
|
||||
|
||||
- For collaboration or questions, ask us on discord.
|
||||
|
||||
@@ -0,0 +1,293 @@
|
||||
---
|
||||
title: Discord Boost Monitor
|
||||
---
|
||||
|
||||
Discord Boost Monitor (hereinafter the "Application") is a Discord bot that automatically manages special roles for server boosters. The Application monitors server members and removes booster-exclusive roles (such as custom color roles) when a member stops boosting the server.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
### Overview
|
||||
|
||||
The Discord Boost Monitor operates automatically in the background of your Discord server. It requires no direct user interaction once configured by server administrators.
|
||||
|
||||
### How It Works
|
||||
|
||||
1. **Automatic Monitoring**: The bot monitors all member updates in the Discord server
|
||||
2. **Boost Detection**: When a member's boost status changes, the bot checks if they still have the server booster role
|
||||
3. **Role Management**: If a member no longer has the booster role, the bot automatically removes any configured booster-exclusive roles (such as custom color roles)
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Automated Role Removal**: No manual intervention needed when members stop boosting
|
||||
- **Configurable Roles**: Server-specific booster and color role IDs can be configured
|
||||
- **Status Monitoring**: Health check endpoint available at the bot's web interface
|
||||
- **Debug Webhooks**: Sends status updates and error reports to configured Discord webhooks
|
||||
|
||||
### Accessing the Bot
|
||||
|
||||
The bot runs as a background service and does not have traditional user-facing commands. Server administrators can monitor its status through:
|
||||
|
||||
- **Web Interface**: HTTPS endpoint showing bot status and information
|
||||
- **Debug Webhook**: Real-time updates sent to configured Discord webhook
|
||||
- **Server Logs**: Winston-based logging for troubleshooting
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Node.js**: Version 22 or higher
|
||||
- **pnpm**: Version 9 or higher
|
||||
- **Discord Bot Token**: From the Discord Developer Portal
|
||||
- **SSL Certificates**: For HTTPS server (Let's Encrypt or similar)
|
||||
- **Sentry Account** (optional): For error tracking
|
||||
|
||||
### Installation
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/nhcarrigan/oogie-woogie-boostie-woostie.git
|
||||
cd oogie-woogie-boostie-woostie
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
3. Configure environment variables by creating a `.env` file:
|
||||
```bash
|
||||
cp sample.env .env
|
||||
```
|
||||
|
||||
4. Edit `.env` with your configuration:
|
||||
```env
|
||||
DISCORD_TOKEN="your-discord-bot-token"
|
||||
SENTRY_DSN="your-sentry-dsn"
|
||||
DEBUG_HOOK="your-discord-webhook-url"
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
#### Role Configuration
|
||||
|
||||
Edit `src/config/roles.ts` to configure your server-specific role IDs:
|
||||
|
||||
- **colourRoles**: Array of role IDs that should be removed when a member stops boosting (src/config/roles.ts:1-10)
|
||||
- **boosterRole**: The ID of your server's booster role (src/config/roles.ts:12)
|
||||
|
||||
Example:
|
||||
```typescript
|
||||
export const colourRoles = [
|
||||
"883281643098484736", // Red role
|
||||
"883283836887261204", // Blue role
|
||||
// Add your color role IDs here
|
||||
];
|
||||
|
||||
export const boosterRole = "712431541531181177"; // Your booster role ID
|
||||
```
|
||||
|
||||
#### SSL Certificates
|
||||
|
||||
The bot expects SSL certificates at the following locations:
|
||||
- Certificate: `/etc/letsencrypt/live/oogie.nhcarrigan.com/cert.pem`
|
||||
- Private Key: `/etc/letsencrypt/live/oogie.nhcarrigan.com/privkey.pem`
|
||||
|
||||
Update the paths in `src/server/serve.ts:18-22` if your certificates are located elsewhere.
|
||||
|
||||
### Building and Running
|
||||
|
||||
1. Build the TypeScript code:
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
|
||||
2. Start the bot:
|
||||
```bash
|
||||
pnpm start
|
||||
```
|
||||
|
||||
3. For development with linting:
|
||||
```bash
|
||||
pnpm lint
|
||||
```
|
||||
|
||||
### Architecture
|
||||
|
||||
#### Core Components
|
||||
|
||||
- **Main Entry Point** (`src/index.ts`): Initializes the Discord client, sets up event listeners, and starts the web server
|
||||
- **Role Manager** (`src/modules/manageRoles.ts`): Core logic for detecting boost status and removing roles
|
||||
- **Web Server** (`src/server/serve.ts`): Fastify-based HTTPS server for health monitoring
|
||||
- **Error Handler** (`src/utils/errorHandler.ts`): Centralized error handling with Sentry integration and Discord webhook notifications
|
||||
- **Log Handler** (`src/utils/logHandler.ts`): Winston-based logging with timestamps and color coding
|
||||
|
||||
#### Bot Intents
|
||||
|
||||
The bot requires the following Discord gateway intents (src/index.ts:22):
|
||||
- `Guilds`: Access to guild information
|
||||
- `GuildMembers`: Access to member updates (privileged intent)
|
||||
|
||||
Note: The `GuildMembers` intent must be enabled in your bot's Discord Developer Portal settings.
|
||||
|
||||
#### Event Flow
|
||||
|
||||
1. Bot connects to Discord and fetches guild members (src/index.ts:25-39)
|
||||
2. Bot listens for `guildMemberUpdate` events (src/index.ts:42-44)
|
||||
3. On member update, `manageRoles` function checks boost status (src/modules/manageRoles.ts:13-26)
|
||||
4. If member is not boosting, configured color roles are removed
|
||||
5. Errors are logged and sent to Sentry and debug webhook
|
||||
|
||||
#### Web Server
|
||||
|
||||
The Fastify server runs on port 3443 with HTTPS and provides:
|
||||
- Health check endpoint at `/` (src/server/serve.ts:27-66)
|
||||
- Simple HTML page with bot information and links
|
||||
- Status notifications sent to debug webhook on startup
|
||||
|
||||
### Monitoring and Debugging
|
||||
|
||||
#### Sentry Integration
|
||||
|
||||
All errors are automatically captured and sent to Sentry (src/index.ts:9-17), providing:
|
||||
- Stack trace rewriting for better debugging
|
||||
- Full error context and stack traces
|
||||
- 100% transaction sampling rate
|
||||
|
||||
#### Discord Webhooks
|
||||
|
||||
Debug webhooks are used for:
|
||||
- Bot startup confirmation (src/index.ts:26-31)
|
||||
- Member count logging (src/index.ts:35-39)
|
||||
- Server startup notification (src/server/serve.ts:73-80)
|
||||
- Error notifications with embeds (src/utils/errorHandler.ts:22-38)
|
||||
|
||||
#### Logging
|
||||
|
||||
Winston logger provides console output with:
|
||||
- Timestamps in `YYYY-MM-DD HH:mm:ss` format
|
||||
- Color-coded log levels
|
||||
- NPM-style log levels (silly, verbose, info, warn, error)
|
||||
|
||||
### Deployment Considerations
|
||||
|
||||
1. **Privileged Intents**: Ensure `GuildMembers` intent is enabled in Discord Developer Portal
|
||||
2. **SSL Certificates**: Keep certificates up-to-date (consider using certbot for Let's Encrypt)
|
||||
3. **Environment Variables**: Secure your `.env` file and never commit it to version control
|
||||
4. **Port Access**: Ensure port 3443 is accessible for health monitoring
|
||||
5. **Process Management**: Consider using PM2 or systemd for process management
|
||||
6. **Single Guild**: Bot is designed for single-guild operation (src/index.ts:33)
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
### Software License
|
||||
|
||||
This Application is licensed under the global software license maintained by Naomi Carrigan. Full license details can be found at: https://docs.nhcarrigan.com/#/license
|
||||
|
||||
Copyright is held by Naomi Carrigan.
|
||||
|
||||
### Privacy Considerations
|
||||
|
||||
The Application processes the following Discord data:
|
||||
- **Guild member information**: Required for detecting boost status changes
|
||||
- **Role information**: Required for managing booster-exclusive roles
|
||||
- **Member update events**: Monitored to detect boost status changes
|
||||
|
||||
This data is processed in real-time and is not permanently stored by the Application outside of:
|
||||
- Error logs sent to Sentry
|
||||
- Debug messages sent to Discord webhooks
|
||||
- Console logs from Winston logger
|
||||
|
||||
For full privacy policy details, see: PRIVACY.md
|
||||
|
||||
### Terms of Service
|
||||
|
||||
The Application operates as an automated moderation tool for Discord servers. Server administrators are responsible for:
|
||||
- Configuring appropriate role IDs
|
||||
- Informing server members about automated role management
|
||||
- Ensuring compliance with Discord's Terms of Service
|
||||
|
||||
For full terms of service, see: TERMS.md
|
||||
|
||||
### Security Policy
|
||||
|
||||
Security vulnerabilities should be reported according to the guidelines in: SECURITY.md
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
### Getting Started
|
||||
|
||||
Full contributing guidelines are available at: https://docs.nhcarrigan.com/#/contributing
|
||||
|
||||
### Development Setup
|
||||
|
||||
1. Fork and clone the repository
|
||||
2. Install dependencies with `pnpm install`
|
||||
3. Create a `.env` file from `sample.env`
|
||||
4. Make your changes in a feature branch
|
||||
5. Run linting with `pnpm lint` before committing
|
||||
6. Build the project with `pnpm build` to ensure TypeScript compiles
|
||||
|
||||
### Code Style
|
||||
|
||||
The project uses:
|
||||
- **ESLint**: `@nhcarrigan/eslint-config` (max 0 warnings)
|
||||
- **Prettier**: `@nhcarrigan/prettier-config`
|
||||
- **TypeScript**: `@nhcarrigan/typescript-config`
|
||||
|
||||
Run `pnpm lint` to check code style before submitting PRs.
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts # Main entry point
|
||||
├── config/
|
||||
│ └── roles.ts # Role ID configuration
|
||||
├── modules/
|
||||
│ └── manageRoles.ts # Core role management logic
|
||||
├── server/
|
||||
│ └── serve.ts # Fastify web server
|
||||
└── utils/
|
||||
├── errorHandler.ts # Centralized error handling
|
||||
└── logHandler.ts # Winston logging configuration
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
Currently, the project does not have automated tests (package.json:11). When contributing new features, consider:
|
||||
- Manual testing with a test Discord server
|
||||
- Verifying role removal works correctly
|
||||
- Testing error handling paths
|
||||
- Checking webhook notifications
|
||||
|
||||
### Submitting Changes
|
||||
|
||||
1. Ensure code passes linting: `pnpm lint`
|
||||
2. Build successfully: `pnpm build`
|
||||
3. Review the Code of Conduct: CODE_OF_CONDUCT.md
|
||||
4. Submit a Pull Request with:
|
||||
- Clear description of changes
|
||||
- Rationale for the changes
|
||||
- Any testing performed
|
||||
|
||||
### Code of Conduct
|
||||
|
||||
All contributors must adhere to the Code of Conduct outlined in: CODE_OF_CONDUCT.md
|
||||
|
||||
### Reporting Issues
|
||||
|
||||
Bug reports and feature requests can be submitted at: https://github.com/nhcarrigan/oogie-woogie-boostie-woostie/issues
|
||||
|
||||
### Contact
|
||||
|
||||
For questions or support:
|
||||
- **Chat Server**: http://chat.nhcarrigan.com
|
||||
- **Email**: contact@nhcarrigan.com
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Calenelle
|
||||
---
|
||||
|
||||
Calenelle (hereinafter the "Application") is a group coordination app with event scheduling and such.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Clarion
|
||||
---
|
||||
|
||||
Clarion (hereinafter the "Application") is a Discord bot with dashboard that allows server mangers to post and edit announcements, rules, and similar.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,662 @@
|
||||
---
|
||||
title: Data API
|
||||
---
|
||||
|
||||
Data API (hereinafter the "Application") is a lightweight web API server designed to host and serve personal and professional data for the NHCarrigan ecosystem. The Application acts as a centralized headless CMS, providing structured data in both YAML and JSON formats to power multiple websites, applications, and Discord bots.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
### 1.1 API Overview
|
||||
|
||||
The Data Server provides a RESTful API that serves various categories of data through simple HTTP GET requests. All endpoints support both YAML and JSON formats.
|
||||
|
||||
**Base URL**: The server runs on `https://data.nhcarrigan.com'.
|
||||
|
||||
**Root Endpoint**:
|
||||
- `GET /` - Returns a welcome message: "Welcome to the NHCarrigan Data API!"
|
||||
|
||||
### 1.2 Available Endpoints
|
||||
|
||||
All data endpoints are available in two formats by changing the file extension:
|
||||
|
||||
#### Projects Data
|
||||
- `GET /projects.json` - Returns project portfolio data in JSON format
|
||||
- `GET /projects.yml` - Returns project portfolio data in YAML format
|
||||
|
||||
Contains information about development projects including:
|
||||
- Project names and descriptions
|
||||
- Project URLs and repository links
|
||||
- Project categories (websites, community tools, Discord bots, etc.)
|
||||
- Avatar images
|
||||
- Status indicators (premium, work-in-progress)
|
||||
|
||||
#### Resume Data
|
||||
- `GET /resume.json` - Returns resume data in JSON format
|
||||
- `GET /resume.yml` - Returns resume data in YAML format
|
||||
|
||||
Contains comprehensive professional information:
|
||||
- Employment history (current and prior positions)
|
||||
- Volunteer experience
|
||||
- Education credentials
|
||||
- Professional certifications
|
||||
- Notable projects
|
||||
- Publications and articles
|
||||
|
||||
#### Testimonials
|
||||
- `GET /testimonials.json` - Returns testimonials in JSON format
|
||||
- `GET /testimonials.yml` - Returns testimonials in YAML format
|
||||
|
||||
Contains professional testimonials and recommendations with:
|
||||
- Testimonial author names
|
||||
- Testimonial content
|
||||
- Date information
|
||||
|
||||
#### Donation Information
|
||||
- `GET /donate.json` - Returns donation platform data in JSON format
|
||||
- `GET /donate.yml` - Returns donation platform data in YAML format
|
||||
|
||||
Contains details about donation platforms:
|
||||
- Platform names and URLs
|
||||
- Icon references
|
||||
- Color schemes
|
||||
- Platform descriptions
|
||||
|
||||
#### Funding Information
|
||||
- `GET /funding.json` - Returns comprehensive funding data in JSON format
|
||||
- `GET /funding.yml` - Returns comprehensive funding data in YAML format
|
||||
|
||||
Contains detailed funding information:
|
||||
- Entity details
|
||||
- Project listings with unique identifiers
|
||||
- Funding channel information
|
||||
- Subscription plan details
|
||||
- Financial history and records
|
||||
|
||||
### 1.3 CORS Support
|
||||
|
||||
The Application has CORS enabled for all origins, allowing consumption from any domain without cross-origin restrictions.
|
||||
|
||||
### 1.4 Content Types
|
||||
|
||||
The Application automatically sets appropriate Content-Type headers:
|
||||
- JSON endpoints: `application/json`
|
||||
- YAML endpoints: `text/yaml` or `application/x-yaml`
|
||||
|
||||
### 1.5 Rate Limiting
|
||||
|
||||
Currently, the Application does not implement rate limiting. Users should be respectful of the server resources and avoid excessive requests.
|
||||
|
||||
### 1.6 Data Freshness
|
||||
|
||||
Data is compiled from YAML source files during the build process. To receive updated data, the server must be rebuilt and restarted when source data changes.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
### 2.1 Prerequisites
|
||||
|
||||
Before running the Application, ensure you have the following installed:
|
||||
|
||||
- **Node.js**: Latest LTS version recommended
|
||||
- **pnpm**: Version 10.17.0 (specified in package.json as packageManager)
|
||||
- **1Password CLI** (optional): For secure environment variable management in production
|
||||
|
||||
### 2.2 Technology Stack
|
||||
|
||||
- **Runtime**: Node.js with ES modules
|
||||
- **Language**: TypeScript 5.9.2
|
||||
- **Web Framework**: Fastify 5.6.1
|
||||
- **Data Format**: YAML (source) → JSON (runtime)
|
||||
- **Testing**: Vitest 3.2.4
|
||||
- **Linting**: ESLint 9.36.0
|
||||
- **Package Manager**: pnpm 10.17.0
|
||||
|
||||
### 2.3 Installation
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd data
|
||||
```
|
||||
|
||||
2. Install dependencies using pnpm:
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 2.4 Project Structure
|
||||
|
||||
```
|
||||
/data/
|
||||
├── src/ # TypeScript source code
|
||||
│ ├── index.ts # Main entry point - Fastify server
|
||||
│ ├── modules/
|
||||
│ │ └── buildRoutes.ts # Dynamic route builder
|
||||
│ ├── interfaces/ # TypeScript type definitions
|
||||
│ │ ├── projects.ts
|
||||
│ │ ├── resume.ts
|
||||
│ │ ├── testimonials.ts
|
||||
│ │ ├── donate.ts
|
||||
│ │ └── funding.ts
|
||||
│ └── utils/
|
||||
│ └── logger.ts # Logger configuration
|
||||
├── data/ # Data directory (YAML sources and JSON builds)
|
||||
│ ├── projects.yml / .json
|
||||
│ ├── resume.yml / .json
|
||||
│ ├── testimonials.yml / .json
|
||||
│ ├── donate.yml / .json
|
||||
│ └── funding.yml / .json
|
||||
├── test/
|
||||
│ └── yaml.spec.ts # Comprehensive validation tests
|
||||
├── prod/ # Compiled JavaScript output
|
||||
├── build.js # YAML to JSON build script
|
||||
├── tsconfig.json # TypeScript configuration
|
||||
└── package.json # Project metadata and scripts
|
||||
```
|
||||
|
||||
### 2.5 Configuration
|
||||
|
||||
The Application uses the following configuration points:
|
||||
|
||||
#### Server Port
|
||||
- Default: Port 9999
|
||||
- Location: `src/index.ts:34`
|
||||
- Can be modified by editing the port number in the source code
|
||||
|
||||
#### Data Directory
|
||||
- Location: `./data`
|
||||
- Contains both source YAML files and built JSON files
|
||||
- Referenced in: `src/modules/buildRoutes.ts`
|
||||
|
||||
#### CORS Settings
|
||||
- Currently configured to allow all origins
|
||||
- Location: `src/index.ts:30`
|
||||
- Can be restricted by modifying the Fastify CORS configuration
|
||||
|
||||
### 2.6 Data Management
|
||||
|
||||
#### Adding New Data Endpoints
|
||||
|
||||
1. Create a new YAML file in the `/data` directory:
|
||||
```bash
|
||||
touch data/newdata.yml
|
||||
```
|
||||
|
||||
2. Create a corresponding TypeScript interface in `src/interfaces/`:
|
||||
```typescript
|
||||
// src/interfaces/newdata.ts
|
||||
export interface NewData {
|
||||
// Define your data structure
|
||||
}
|
||||
```
|
||||
|
||||
3. The Application will automatically:
|
||||
- Generate routes for `/newdata.yml` and `/newdata.json`
|
||||
- Serve the content when the server restarts
|
||||
|
||||
#### Editing Existing Data
|
||||
|
||||
1. Edit the YAML files in the `/data` directory
|
||||
2. Run the build command to convert YAML to JSON
|
||||
3. Restart the server to serve updated data
|
||||
|
||||
The YAML files are the source of truth. Always edit YAML files, not JSON files, as JSON files are auto-generated.
|
||||
|
||||
### 2.7 Build Process
|
||||
|
||||
The build process consists of two steps:
|
||||
|
||||
1. **YAML to JSON Conversion**: `node build.js`
|
||||
- Reads all YAML files from the data directory
|
||||
- Generates corresponding JSON files
|
||||
- Preserves the human-readable YAML as the source of truth
|
||||
|
||||
2. **TypeScript Compilation**: `tsc`
|
||||
- Compiles TypeScript source code to JavaScript
|
||||
- Outputs to the `/prod` directory
|
||||
- Uses configuration from `tsconfig.json` (extends @nhcarrigan/typescript-config)
|
||||
|
||||
To run the complete build:
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
### 2.8 Available Scripts
|
||||
|
||||
```bash
|
||||
# Build (YAML → JSON + TypeScript compilation)
|
||||
pnpm run build
|
||||
|
||||
# Start production server (with 1Password environment variables)
|
||||
pnpm run start
|
||||
|
||||
# Run test suite
|
||||
pnpm test
|
||||
|
||||
# Linting
|
||||
pnpm run lint # Run all linters
|
||||
pnpm run lint:ts # ESLint only
|
||||
pnpm run lint:spelling # Spell check YAML files
|
||||
pnpm run lint:yaml # YAML validation
|
||||
```
|
||||
|
||||
### 2.9 Testing
|
||||
|
||||
The Application includes comprehensive test coverage using Vitest.
|
||||
|
||||
**Test File**: `test/yaml.spec.ts`
|
||||
|
||||
**What is tested**:
|
||||
- Data structure validation against TypeScript interfaces
|
||||
- URL reachability for all external links (with retry logic)
|
||||
- Date format validation
|
||||
- Required field presence
|
||||
- Data type correctness
|
||||
|
||||
**Running tests**:
|
||||
```bash
|
||||
pnpm test
|
||||
```
|
||||
|
||||
Tests have a 120-second timeout to accommodate URL validation checks, which may be rate-limited.
|
||||
|
||||
### 2.10 Development Workflow
|
||||
|
||||
1. **Make changes to data**:
|
||||
- Edit YAML files in `/data` directory
|
||||
- Use your preferred text editor
|
||||
|
||||
2. **Validate your changes**:
|
||||
```bash
|
||||
pnpm run lint:yaml # Validate YAML syntax
|
||||
pnpm run lint:spelling # Check spelling
|
||||
pnpm test # Run full test suite
|
||||
```
|
||||
|
||||
3. **Build the application**:
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
4. **Start the server locally**:
|
||||
```bash
|
||||
node ./prod/index.js
|
||||
```
|
||||
|
||||
Or with 1Password environment variables:
|
||||
```bash
|
||||
pnpm run start
|
||||
```
|
||||
|
||||
5. **Test endpoints**:
|
||||
```bash
|
||||
curl http://localhost:9999/projects.json
|
||||
```
|
||||
|
||||
### 2.11 Deployment
|
||||
|
||||
#### Environment Variables
|
||||
|
||||
The production start script uses 1Password CLI for secure environment variable management:
|
||||
```bash
|
||||
op run --env-file ./prod.env -- node ./prod/index.js
|
||||
```
|
||||
|
||||
Create a `prod.env` file with 1Password references for any required environment variables.
|
||||
|
||||
#### Production Considerations
|
||||
|
||||
1. **Reverse Proxy**: Consider running the Application behind a reverse proxy (nginx, Apache) for:
|
||||
- SSL/TLS termination
|
||||
- Rate limiting
|
||||
- Caching
|
||||
- Load balancing
|
||||
|
||||
2. **Process Management**: Use a process manager to ensure uptime:
|
||||
- PM2
|
||||
- systemd
|
||||
- Docker with restart policies
|
||||
|
||||
3. **Monitoring**: Implement monitoring for:
|
||||
- Server health
|
||||
- Response times
|
||||
- Error rates
|
||||
|
||||
4. **Backups**: Regularly backup the `/data` directory, as it contains the source YAML files.
|
||||
|
||||
### 2.12 Troubleshooting
|
||||
|
||||
#### Server won't start
|
||||
- Verify port 9999 is not in use
|
||||
- Check that dependencies are installed (`pnpm install`)
|
||||
- Ensure the build completed successfully (`pnpm run build`)
|
||||
|
||||
#### Data not updating
|
||||
- Verify you edited the YAML files, not JSON files
|
||||
- Run `pnpm run build` to regenerate JSON
|
||||
- Restart the server
|
||||
|
||||
#### Test failures
|
||||
- **URL validation failures**: May be due to rate limiting; tests include retry logic
|
||||
- **Data structure failures**: Ensure YAML structure matches TypeScript interfaces
|
||||
- **Spelling failures**: Add custom words to cspell configuration if needed
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
### 3.1 Data Usage and Privacy
|
||||
|
||||
#### Data Served by the Application
|
||||
|
||||
The Application serves public, non-sensitive data intended for public consumption. The data categories include:
|
||||
|
||||
- **Projects**: Public information about open-source projects and portfolio work
|
||||
- **Resume**: Professional experience, education, and certifications
|
||||
- **Testimonials**: Public testimonials and recommendations
|
||||
- **Donation Information**: Public donation platform links
|
||||
- **Funding Information**: Public funding channel and subscription information
|
||||
|
||||
#### No Personal User Data Collection
|
||||
|
||||
The Application itself does not collect, store, or process any personal data from users accessing the API. The server:
|
||||
- Does not require authentication
|
||||
- Does not track user requests
|
||||
- Does not use cookies or similar tracking technologies
|
||||
- Does not log IP addresses or personally identifiable information
|
||||
|
||||
#### CORS and Third-Party Access
|
||||
|
||||
By enabling CORS for all origins, the Application explicitly permits third-party websites and applications to access the served data. This is intentional and by design, as the data is meant for public consumption.
|
||||
|
||||
### 3.2 Data Accuracy and Updates
|
||||
|
||||
The data served by the Application is maintained on a best-effort basis. While efforts are made to ensure accuracy:
|
||||
|
||||
- Data may become outdated between updates
|
||||
- URLs and external links may become invalid over time
|
||||
- No guarantee of real-time data freshness is provided
|
||||
|
||||
Users consuming this data should:
|
||||
- Implement appropriate error handling for unavailable resources
|
||||
- Cache responses responsibly
|
||||
- Not rely on the Application for time-sensitive or critical decisions
|
||||
|
||||
### 3.3 Service Availability
|
||||
|
||||
The Application is provided "as-is" without guarantees of:
|
||||
- Continuous availability
|
||||
- Specific uptime percentages
|
||||
- Response time performance
|
||||
- Data freshness
|
||||
|
||||
Users should not build critical systems that depend on the Application's availability without implementing appropriate fallbacks and error handling.
|
||||
|
||||
### 3.4 Intellectual Property
|
||||
|
||||
#### Data Content
|
||||
|
||||
The data served by the Application contains information about projects, professional experience, and other content that may be subject to intellectual property rights:
|
||||
|
||||
- Project names, descriptions, and logos may be trademarks
|
||||
- Code and software referenced may be under various open-source licenses
|
||||
- Testimonial content remains the intellectual property of the original authors
|
||||
|
||||
Users consuming this data should:
|
||||
- Respect intellectual property rights
|
||||
- Provide proper attribution when displaying data
|
||||
- Review specific licenses for any referenced projects or software
|
||||
|
||||
#### Application Code
|
||||
|
||||
The Application's source code is licensed under the terms specified in the LICENSE.md file. Copyright is held by Naomi Carrigan.
|
||||
|
||||
### 3.5 Terms of Service
|
||||
|
||||
The general Terms of Service can be found at: https://docs.nhcarrigan.com/#/terms
|
||||
|
||||
#### Application-Specific Terms
|
||||
|
||||
Users of the Application agree to:
|
||||
- Use the API in good faith and not for malicious purposes
|
||||
- Not attempt to overwhelm the server with excessive requests
|
||||
- Not attempt to exploit vulnerabilities or security weaknesses
|
||||
- Respect the intended public use of the data
|
||||
|
||||
### 3.6 Privacy Policy
|
||||
|
||||
The general Privacy Policy can be found at: https://docs.nhcarrigan.com/#/privacy
|
||||
|
||||
#### Application-Specific Privacy Notes
|
||||
|
||||
As noted in section 3.1, the Application does not collect user data. The privacy policy primarily applies to:
|
||||
- Contributors to the codebase (governed by GitHub's privacy policy)
|
||||
- Data maintainers with access to the data repository
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
### 4.1 General Contributing Guidelines
|
||||
|
||||
General contributing guidelines can be found at: https://docs.nhcarrigan.com/#/contributing
|
||||
|
||||
Please review these guidelines before contributing to the Application.
|
||||
|
||||
### 4.2 Code of Conduct
|
||||
|
||||
Before interacting with the project or community, please read the [Code of Conduct](CODE_OF_CONDUCT.md).
|
||||
|
||||
### 4.3 Ways to Contribute
|
||||
|
||||
#### 4.3.1 Data Contributions
|
||||
|
||||
If you have corrections or updates to the data served by the Application:
|
||||
|
||||
1. **Data corrections**: If you notice incorrect information, please open an issue
|
||||
2. **Testimonials**: If you'd like to add a testimonial, please contact through the official channels
|
||||
3. **Project updates**: For updates to project information, verify you have permission to modify the data
|
||||
|
||||
#### 4.3.2 Code Contributions
|
||||
|
||||
Contributors can help improve the Application in several ways:
|
||||
|
||||
**Features**:
|
||||
- Enhanced API endpoints
|
||||
- New data validation rules
|
||||
- Performance optimizations
|
||||
- Additional data format support
|
||||
- API documentation improvements
|
||||
|
||||
**Bug Fixes**:
|
||||
- Server stability issues
|
||||
- Route handling bugs
|
||||
- Build process errors
|
||||
- Test failures
|
||||
|
||||
**Quality Improvements**:
|
||||
- Code refactoring
|
||||
- Test coverage expansion
|
||||
- Documentation enhancements
|
||||
- Type safety improvements
|
||||
|
||||
### 4.4 Development Setup
|
||||
|
||||
1. **Fork and clone** the repository
|
||||
2. **Install dependencies**: `pnpm install`
|
||||
3. **Create a branch** for your changes: `git checkout -b feature/your-feature-name`
|
||||
4. **Make your changes** following the guidelines below
|
||||
5. **Test your changes**: `pnpm test`
|
||||
6. **Lint your code**: `pnpm run lint`
|
||||
7. **Build the project**: `pnpm run build`
|
||||
8. **Commit and push** your changes
|
||||
9. **Open a Pull Request**
|
||||
|
||||
### 4.5 Code Style Guidelines
|
||||
|
||||
#### TypeScript
|
||||
|
||||
- Follow the ESLint configuration (`@nhcarrigan/eslint-config`)
|
||||
- Use explicit type annotations for function parameters and return values
|
||||
- Prefer interfaces over type aliases for object shapes
|
||||
- Use ES modules (`import`/`export`) syntax
|
||||
- Maintain strict type safety (no `any` types unless absolutely necessary)
|
||||
|
||||
**Example**:
|
||||
```typescript
|
||||
// Good
|
||||
export const processData = (input: string): ProcessedData => {
|
||||
// implementation
|
||||
};
|
||||
|
||||
// Avoid
|
||||
export const processData = (input) => {
|
||||
// implementation
|
||||
};
|
||||
```
|
||||
|
||||
#### File Organization
|
||||
|
||||
- Place interfaces in `src/interfaces/`
|
||||
- Place utility functions in `src/utils/`
|
||||
- Place core logic in `src/modules/`
|
||||
- Keep the main entry point (`src/index.ts`) minimal
|
||||
|
||||
#### Error Handling
|
||||
|
||||
- Use the custom logger from `@nhcarrigan/logger`
|
||||
- Provide meaningful error messages
|
||||
- Handle errors gracefully without crashing the server
|
||||
|
||||
### 4.6 Testing Guidelines
|
||||
|
||||
All contributions should maintain or improve test coverage.
|
||||
|
||||
#### Writing Tests
|
||||
|
||||
- Use Vitest test framework
|
||||
- Place tests in the `/test` directory
|
||||
- Use descriptive test names
|
||||
|
||||
**Example test structure**:
|
||||
```typescript
|
||||
describe("Feature Name", () => {
|
||||
it("should do something specific", () => {
|
||||
// Arrange
|
||||
const input = setupTestData();
|
||||
|
||||
// Act
|
||||
const result = performAction(input);
|
||||
|
||||
// Assert
|
||||
expect(result).toBe(expectedValue);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
#### Running Tests
|
||||
|
||||
Before submitting a PR:
|
||||
```bash
|
||||
pnpm test # Run all tests
|
||||
```
|
||||
|
||||
### 4.7 Documentation Guidelines
|
||||
|
||||
When contributing documentation:
|
||||
|
||||
- Use clear, concise language
|
||||
- Include code examples where helpful
|
||||
- Update relevant sections when changing functionality
|
||||
- Check spelling with `pnpm run lint:spelling`
|
||||
|
||||
### 4.8 Pull Request Process
|
||||
|
||||
1. **Ensure all checks pass**:
|
||||
- All tests pass (`pnpm test`)
|
||||
- Code lints without warnings (`pnpm run lint`)
|
||||
- Build succeeds (`pnpm run build`)
|
||||
|
||||
2. **Write a clear PR description**:
|
||||
- Describe what changes were made
|
||||
- Explain why the changes were necessary
|
||||
- Reference any related issues
|
||||
|
||||
3. **Respond to feedback**:
|
||||
- Address review comments promptly
|
||||
- Be open to suggestions and improvements
|
||||
- Update the PR as requested
|
||||
|
||||
4. **Squash commits** if requested to maintain a clean git history
|
||||
|
||||
### 4.9 Adding New Data Categories
|
||||
|
||||
To add a new data category to the Application:
|
||||
|
||||
1. **Create the TypeScript interface**:
|
||||
```typescript
|
||||
// src/interfaces/newcategory.ts
|
||||
export interface NewCategory {
|
||||
id: string;
|
||||
name: string;
|
||||
// other fields
|
||||
}
|
||||
```
|
||||
|
||||
2. **Create the YAML data file**:
|
||||
```yaml
|
||||
# data/newcategory.yml
|
||||
- id: example
|
||||
name: Example Item
|
||||
```
|
||||
|
||||
3. **Add tests**:
|
||||
```typescript
|
||||
// test/yaml.spec.ts
|
||||
describe("New Category Data", () => {
|
||||
it("should have valid structure", () => {
|
||||
// validation tests
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
4. **Update documentation**:
|
||||
- Add endpoint documentation to section 1.2
|
||||
- Update project structure in section 2.4
|
||||
|
||||
5. **Test the changes**:
|
||||
```bash
|
||||
pnpm run build
|
||||
node ./prod/index.js
|
||||
curl http://localhost:9999/newcategory.json
|
||||
```
|
||||
|
||||
### 4.10 Security Considerations
|
||||
|
||||
When contributing, keep security in mind:
|
||||
|
||||
- Never commit sensitive data (API keys, passwords, personal information)
|
||||
- Validate all input data in tests
|
||||
- Follow secure coding practices
|
||||
- Report security vulnerabilities privately before opening public issues
|
||||
|
||||
### 4.11 Getting Help
|
||||
|
||||
If you need help contributing:
|
||||
|
||||
- Open a GitHub issue with your question
|
||||
- Join the [Chat Server](http://chat.nhcarrigan.com)
|
||||
- Email: `contact@nhcarrigan.com`
|
||||
|
||||
### 4.12 Recognition
|
||||
|
||||
All contributors will be recognized for their contributions. Significant contributions may be highlighted in release notes and project documentation.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-10-29
|
||||
**Application Version**: 1.0.0
|
||||
**Maintained by**: NHCarrigan
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Eirene
|
||||
---
|
||||
|
||||
Eirene (hereinafter the "Application") is a website and Discord activity that allows you to participate in code challenges competitively or collaboratively
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Elaria
|
||||
---
|
||||
|
||||
Elaria (hereinafter the "Application") is a meeting schedule coordination tool.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Elowyn
|
||||
---
|
||||
|
||||
Elowyn (hereinafter the "Application") is a quick website that helps you format text.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Elunara
|
||||
---
|
||||
|
||||
Elunara (hereinafter the "Application") is a Discord bot that allows users to proxy messages so they correctly appear as composed by an alter.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Elysium
|
||||
---
|
||||
|
||||
Elysium (hereinafter the "Application") is an idle RPG in the browser.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Evangeline
|
||||
---
|
||||
|
||||
Evangeline (hereinafter the "Application") is a Discord bot that allows you to configure canned replies, retrieve them anywhere on discord, and easily copy + paste them into chat.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Hacksmiths
|
||||
---
|
||||
|
||||
Hacksmiths (hereinafter the "Application") is an online programming-themed party game.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Isolda
|
||||
---
|
||||
|
||||
Isolda (hereinafter the "Application") is a modern, sleek email client for the web or desktop
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
---
|
||||
title: Life of a Naomi
|
||||
---
|
||||
|
||||
Life of a Naomi (hereinafter the "Game") is a quick game that introduces who Naomi is, and provides a glimpse into her life.
|
||||
|
||||
## 1. Player Documentation
|
||||
|
||||
This section is for players who are exploring or playing the Game.
|
||||
|
||||
### Controls
|
||||
|
||||
- **Keyboard / Gamepad:**
|
||||
- Arrow keys / D-Pad: Move character
|
||||
- Z / Enter / A: Confirm / Interact
|
||||
- X / Esc / B: Cancel / Menu
|
||||
- C / Space / Y: Open menu (if applicable)
|
||||
- Shift / L / R: Dash (if enabled)
|
||||
|
||||
- **Touch UI (Mobile / Tablet):**
|
||||
- Tap to move or interact
|
||||
- On-screen buttons for menu and actions
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
- Ensure your device meets RPG Maker MZ requirements.
|
||||
- If the game crashes, try restarting the app or clearing temporary files.
|
||||
- Ask us on discord if persistent issues occur.
|
||||
|
||||
---
|
||||
|
||||
## 2. Developer Documentation
|
||||
|
||||
This section is for those interested in running, modifying, or extending the Game.
|
||||
|
||||
### Engine & Dependencies
|
||||
|
||||
- **Engine:** RPG Maker MZ
|
||||
- **Plugins Used:** none
|
||||
- **Assets:** All original
|
||||
|
||||
### Setup Instructions
|
||||
|
||||
1. Open RPG Maker MZ.
|
||||
2. Load the project folder `life-of-a-naomi`.
|
||||
3. Use the "Playtest" button to run the Game locally.
|
||||
4. To export, use the "Deployment" feature for target platforms.
|
||||
|
||||
### Directory Structure
|
||||
|
||||
- `data/` — database files (maps, events, actors, items, skills, etc.)
|
||||
- `img/` — graphics (characters, tilesets, animations, pictures, etc.)
|
||||
- `audio/` — music and sound effects
|
||||
- `js/` — plugins and core scripts
|
||||
- `www/` — exported HTML5 build (if deployed for web)
|
||||
|
||||
---
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
This section expands on legal or licensing information specific to the Game.
|
||||
|
||||
### Licensing
|
||||
|
||||
This Game is created using RPG Maker MZ. The game code and original content are the property of NHCarrigan. RPG Maker MZ runtime assets are licensed under the terms provided by KADOKAWA Corporation. All original graphics, music, and story content belong to NHCarrigan and are protected by copyright.
|
||||
|
||||
### Third-Party Notices
|
||||
|
||||
- Any third-party assets, music, or plugins included are credited in game.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
This section is for contributors or collaborators on the Game.
|
||||
|
||||
### How to Contribute
|
||||
|
||||
- Fork or copy the project folder.
|
||||
- Submit patches or mods via Git.
|
||||
|
||||
- Include a changelog and clear notes on modifications.
|
||||
|
||||
### Coding Standards
|
||||
|
||||
- Plugins in `js/plugins/` should follow standard JS conventions.
|
||||
- Comment custom scripts clearly for readability.
|
||||
|
||||
### Art & Audio Guidelines
|
||||
|
||||
- Maintain original resolutions where possible (48x48 tiles, etc.).
|
||||
- Use consistent naming for files in `img/` and `audio/`.
|
||||
|
||||
### Contact
|
||||
|
||||
- For collaboration or questions, ask us on discord.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Lucinda
|
||||
---
|
||||
|
||||
Lucinda (hereinafter the "Application") is a kanban-style task management site.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Lyra
|
||||
---
|
||||
|
||||
Lyra (hereinafter the "Application") is a web-based API mocking tool, allowing you to create temporary endpoints for a front-end to hit, test webhook payloads, and more!
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Maribelle
|
||||
---
|
||||
|
||||
Maribelle (hereinafter the "Application") is a Discord bot that allows you to configure daily progress huddle reminders for your server members.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Meliora
|
||||
---
|
||||
|
||||
Meliora (hereinafter the "Application") is an embeddable chat widget, comment section, and full support flow utility.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Meridia
|
||||
---
|
||||
|
||||
Meridia (hereinafter the "Application") is our custom metrics and analytics server.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Naomi's Adventure I: An Isekai Story
|
||||
---
|
||||
|
||||
Naomi's Adventure I: An Isekai Story (hereinafter the "Application") is an Isekai story, and our first paid game.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Nymira
|
||||
---
|
||||
|
||||
Nymira (hereinafter the "Application") is a service that allows you to claim a custom <username>.naomi.party username for Bluesky.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Octavia
|
||||
---
|
||||
|
||||
Octavia (hereinafter the "Application") is a Linux-native music player application with a focus on handling large libraries with minimal memory.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Oriana
|
||||
---
|
||||
|
||||
Oriana (hereinafter the "Application") is an uptime monitoring tool with status pages
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Rowena
|
||||
---
|
||||
|
||||
Rowena (hereinafter the "Application") is a web app that allows you to create and share forms, and track responses in a user friendly table.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
---
|
||||
title: Ruu's Goblin Quest
|
||||
---
|
||||
|
||||
Ruu's Goblin Quest (hereinafter the "Game") is a game developed for our friend Ruu's game jam.
|
||||
|
||||
## 1. Player Documentation
|
||||
|
||||
This section is for players who are exploring or playing the Game.
|
||||
|
||||
### Controls
|
||||
|
||||
- **Keyboard / Gamepad:**
|
||||
- Arrow keys / D-Pad: Move character
|
||||
- Z / Enter / A: Confirm / Interact
|
||||
- X / Esc / B: Cancel / Menu
|
||||
- C / Space / Y: Open menu (if applicable)
|
||||
- Shift / L / R: Dash (if enabled)
|
||||
|
||||
- **Touch UI (Mobile / Tablet):**
|
||||
- Tap to move or interact
|
||||
- On-screen buttons for menu and actions
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
- Ensure your device meets RPG Maker MZ requirements.
|
||||
- If the game crashes, try restarting the app or clearing temporary files.
|
||||
- Ask us on discord if persistent issues occur.
|
||||
|
||||
---
|
||||
|
||||
## 2. Developer Documentation
|
||||
|
||||
This section is for those interested in running, modifying, or extending the Game.
|
||||
|
||||
### Engine & Dependencies
|
||||
|
||||
- **Engine:** RPG Maker MZ
|
||||
- **Plugins Used:** none
|
||||
- **Assets:** All original
|
||||
|
||||
### Setup Instructions
|
||||
|
||||
1. Open RPG Maker MZ.
|
||||
2. Load the project folder `ruus-goblin-quest`.
|
||||
3. Use the "Playtest" button to run the Game locally.
|
||||
4. To export, use the "Deployment" feature for target platforms.
|
||||
|
||||
### Directory Structure
|
||||
|
||||
- `data/` — database files (maps, events, actors, items, skills, etc.)
|
||||
- `img/` — graphics (characters, tilesets, animations, pictures, etc.)
|
||||
- `audio/` — music and sound effects
|
||||
- `js/` — plugins and core scripts
|
||||
- `www/` — exported HTML5 build (if deployed for web)
|
||||
|
||||
---
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
This section expands on legal or licensing information specific to the Game.
|
||||
|
||||
### Licensing
|
||||
|
||||
This Game is created using RPG Maker MZ. The game code and original content are the property of NHCarrigan. RPG Maker MZ runtime assets are licensed under the terms provided by KADOKAWA Corporation. All original graphics, music, and story content belong to NHCarrigan and are protected by copyright.
|
||||
|
||||
### Third-Party Notices
|
||||
|
||||
- Any third-party assets, music, or plugins included are credited in game.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
This section is for contributors or collaborators on the Game.
|
||||
|
||||
### How to Contribute
|
||||
|
||||
- Fork or copy the project folder.
|
||||
- Submit patches or mods via Git.
|
||||
|
||||
- Include a changelog and clear notes on modifications.
|
||||
|
||||
### Coding Standards
|
||||
|
||||
- Plugins in `js/plugins/` should follow standard JS conventions.
|
||||
- Comment custom scripts clearly for readability.
|
||||
|
||||
### Art & Audio Guidelines
|
||||
|
||||
- Maintain original resolutions where possible (48x48 tiles, etc.).
|
||||
- Use consistent naming for files in `img/` and `audio/`.
|
||||
|
||||
### Contact
|
||||
|
||||
- For collaboration or questions, ask us on discord.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Selene
|
||||
---
|
||||
|
||||
Selene (hereinafter the "Application") is a local-only privacy-focused REST API client.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -2,254 +2,655 @@
|
||||
title: Static Pages
|
||||
---
|
||||
|
||||
Static Pages (hereinafter the "Application") is a collection of static HTML pages and related data/scripts for various small web utilities and content sections. The application provides interactive explorers for books and music libraries, product directories, games, chat services, testimonials, and other utility pages. It is designed to be easily synchronized to a production server using shell scripts and requires no backend or dynamic server-side logic.
|
||||
Static Pages (hereinafter the "Application") is a collection of static HTML pages that serve as the foundation for various web-based services and informational resources offered by Naomi Carrigan. The Application provides a lightweight, accessible platform for showcasing personal content, accepting donations, displaying testimonials, cataloguing personal collections, and managing product information.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
The Application provides several interactive web utilities:
|
||||
|
||||
### Book Library
|
||||
|
||||
Visit at https://books.nhcarrigan.com
|
||||
|
||||
An interactive explorer for Naomi's book collection. Users can browse and search through the library of books with filtering capabilities by author. The interface displays book titles and authors extracted from digital book files.
|
||||
|
||||
### Music Library
|
||||
|
||||
Visit at https://music.nhcarrigan.com
|
||||
|
||||
An interactive explorer for Naomi's music collection. Similar to the book library, users can browse and search through songs with filtering by artist. The interface displays song titles and artists extracted from audio file metadata.
|
||||
|
||||
### Games
|
||||
|
||||
Visit at https://games.nhcarrigan.com
|
||||
|
||||
A landing page showcasing various games developed by NHCarrigan, including links to the Beccalia Series and other game projects.
|
||||
|
||||
### BlueSky Handle Generator
|
||||
|
||||
Visit at https://naomi.party
|
||||
|
||||
A service page for provisioning custom Bluesky handles under the naomi.party domain. Currently requires manual processing through the Discord support server.
|
||||
|
||||
### Testimonials
|
||||
|
||||
Visit at https://testimonials.nhcarrigan.com
|
||||
|
||||
A showcase page displaying testimonials from past clients about NHCarrigan's work and services.
|
||||
|
||||
### Link Redirector
|
||||
|
||||
Visit at https://nhcarrigan.link
|
||||
|
||||
A utility page that serves as a fallback for improperly configured subdomain redirects, providing users with support contact information.
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
### User Manual
|
||||
### 1.1 Available Pages
|
||||
|
||||
Visit at https://manual.nhcarrigan.com
|
||||
The Application consists of several distinct pages, each serving a specific purpose:
|
||||
|
||||
A brief description of what it is like to work with Naomi, and how to cultivate an environment where she can thrive.
|
||||
#### 1.1.1 Donation Page (`/donate`)
|
||||
|
||||
The donation page provides multiple avenues for supporting Naomi Carrigan's work, including:
|
||||
|
||||
- **OpenCollective**: Main financial ledger tracking all income and expenses
|
||||
- **Patreon**: Monthly membership support
|
||||
- **Ko-Fi**: Coffee donations and one-time contributions
|
||||
- **PayPal**: Direct donation processing
|
||||
- **CashApp**: Direct monetary transfers
|
||||
- **GitHub Sponsors**: Platform-integrated sponsorship
|
||||
- **Stripe**: Monthly recurring donations
|
||||
- **Twitch**: Stream subscriptions
|
||||
- **Throne**: Gift suggestion and purchase platform
|
||||
- **Discord**: Community hub access
|
||||
|
||||
#### 1.1.2 Book Library (`/books`)
|
||||
|
||||
An interactive explorer displaying books that Naomi has read. Features include:
|
||||
|
||||
- Searchable database by author and title
|
||||
- Filterable results with dynamic count display
|
||||
- Alphabetically sorted table view
|
||||
- JSON-backed data storage (`books.json`)
|
||||
- Currently displays over 1,000 books
|
||||
|
||||
#### 1.1.3 Music Library (`/music`)
|
||||
|
||||
An interactive explorer for music that Naomi listens to. Features include:
|
||||
|
||||
- Search functionality for artists and titles
|
||||
- Dynamic filtering with live count updates
|
||||
- Tabular display with alternating row colors
|
||||
- JSON-backed data storage (`songs.json`)
|
||||
|
||||
#### 1.1.4 Testimonials (`/testimonials`)
|
||||
|
||||
A comprehensive showcase of professional feedback and recommendations from:
|
||||
|
||||
- Past clients
|
||||
- Colleagues
|
||||
- Community members
|
||||
- Internal team feedback (anonymized for privacy)
|
||||
|
||||
Features include:
|
||||
|
||||
- Print-optimized styling
|
||||
- Chronologically organized testimonials
|
||||
- Web form integration for new submissions
|
||||
- Over 50 professional testimonials spanning multiple years (2023-2025)
|
||||
|
||||
#### 1.1.5 Link Redirector (`/link-redirector`)
|
||||
|
||||
A fallback page for improperly configured subdomain redirects, providing users with support contact information.
|
||||
|
||||
#### 1.1.6 Additional Pages
|
||||
|
||||
- **Chat** (`/chat`): Community communication hub
|
||||
- **Mail** (`/mail`): Email-related services
|
||||
- **Games** (`/games`): Gaming-related content
|
||||
- **Manual** (`/manual`): User manuals and guides
|
||||
- **Sitemap** (`/sitemap`): Site navigation structure
|
||||
- **Bluesky** (`/bsky`): Bluesky social platform integration
|
||||
|
||||
### 1.2 Common Features
|
||||
|
||||
All pages share common functionality through a global header system:
|
||||
|
||||
- Consistent styling via CSS custom properties (variables)
|
||||
- Responsive design for mobile and desktop
|
||||
- Global navigation (loaded from `cdn.nhcarrigan.com/headers/index.js`)
|
||||
- Consistent theming with foreground/background color variables
|
||||
- Custom cursor styles
|
||||
|
||||
### 1.3 Accessibility
|
||||
|
||||
The Application is designed with accessibility in mind:
|
||||
|
||||
- Semantic HTML5 structure
|
||||
- Proper heading hierarchy
|
||||
- Descriptive page titles and meta descriptions
|
||||
- Responsive viewport scaling
|
||||
- UTF-8 character encoding
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
### System Requirements
|
||||
- Unix-like operating system (Linux/macOS)
|
||||
- Bash shell
|
||||
- `rsync` for deployment
|
||||
- `exiftool` for extracting book metadata
|
||||
- `mid3v2` for extracting music metadata
|
||||
- `jq` for JSON processing
|
||||
- Access to Gitea API (for products functionality)
|
||||
- Web server capable of serving static files
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
├── books/ # Book library interface
|
||||
│ ├── index.html # Main book explorer page
|
||||
│ └── books.json # Generated book data
|
||||
├── music/ # Music library interface
|
||||
│ ├── index.html # Main music explorer page
|
||||
│ └── songs.json # Generated music data
|
||||
├── products/ # Product directory
|
||||
│ ├── index.html # Product listing page
|
||||
│ └── data.json # Generated product data
|
||||
├── games/ # Games showcase
|
||||
├── bsky/ # BlueSky handle service
|
||||
├── testimonials/ # Client testimonials
|
||||
├── link-redirector/ # Redirect fallback
|
||||
├── mail/ # Mail service (manual sync)
|
||||
├── manual/ # Manual/documentation
|
||||
├── sitemap/ # Site navigation
|
||||
├── books.sh # Book data generator script
|
||||
├── songs.sh # Music data generator script
|
||||
├── products.sh # Product data generator script
|
||||
└── sync.sh # Deployment script
|
||||
```
|
||||
|
||||
### Data Generation Scripts
|
||||
|
||||
**Book Library (`books.sh`)**
|
||||
- Scans `/home/naomi/cloud/Books` directory for book files
|
||||
- Extracts title and author metadata using `exiftool`
|
||||
- Generates `books/books.json` with book data
|
||||
- Handles files without metadata by using filenames
|
||||
|
||||
**Music Library (`songs.sh`)**
|
||||
- Scans `/home/naomi/music` directory for audio files
|
||||
- Extracts title and artist metadata using `mid3v2`
|
||||
- Generates `music/songs.json` with song data
|
||||
- Falls back to filename parsing for missing metadata
|
||||
|
||||
**Product Directory (`products.sh`)**
|
||||
- Fetches repository data from Gitea API
|
||||
- Organizes projects by category (public, games, private, archived)
|
||||
- Generates `products/data.json` with project information
|
||||
- Requires `GITEA_TOKEN` environment variable
|
||||
|
||||
### Deployment
|
||||
|
||||
The deployment process uses `sync.sh` which:
|
||||
1. Syncs all directories to production server using `rsync`
|
||||
2. Targets `prod:/home/nhcarrigan` for most content
|
||||
3. Requires manual sync for `mail/index.html` to `mail:/home/user-data/www/default`
|
||||
|
||||
**Deployment Command:**
|
||||
```bash
|
||||
./sync.sh
|
||||
```
|
||||
|
||||
### Running Your Own Instance
|
||||
|
||||
1. **Clone the repository**
|
||||
2. **Install dependencies:**
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt install exiftool python3-mutagen jq rsync
|
||||
|
||||
# macOS
|
||||
brew install exiftool jq rsync
|
||||
pip3 install mutagen
|
||||
```
|
||||
|
||||
3. **Configure data sources:**
|
||||
- Update paths in `books.sh` for your book collection
|
||||
- Update paths in `songs.sh` for your music collection
|
||||
- Set `GITEA_TOKEN` environment variable for products functionality
|
||||
- Modify `products.sh` with your Gitea instance URL and organizations
|
||||
|
||||
4. **Generate data:**
|
||||
```bash
|
||||
./books.sh # Generate book library data
|
||||
./songs.sh # Generate music library data
|
||||
./products.sh # Generate product directory data
|
||||
```
|
||||
|
||||
5. **Serve static files:**
|
||||
```bash
|
||||
# Simple Python server for testing
|
||||
python3 -m http.server 8000
|
||||
```
|
||||
|
||||
6. **Deploy to production:**
|
||||
- Modify `sync.sh` with your server details
|
||||
- Ensure SSH key authentication is configured
|
||||
- Run `./sync.sh`
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
### 2.1 Architecture
|
||||
|
||||
The Application is a pure static website with no backend dependencies:
|
||||
|
||||
- **Technology Stack**: HTML5, CSS3, Vanilla JavaScript
|
||||
- **Data Storage**: JSON files for dynamic content
|
||||
- **Styling**: Custom CSS with CSS custom properties
|
||||
- **Scripts**: Vanilla JavaScript (no frameworks)
|
||||
- **CDN Dependencies**: Global header/navigation system from `cdn.nhcarrigan.com`
|
||||
|
||||
### 2.2 File Structure
|
||||
|
||||
```
|
||||
static-pages/
|
||||
├── books/
|
||||
│ ├── index.html
|
||||
│ └── books.json
|
||||
├── music/
|
||||
│ ├── index.html
|
||||
│ └── songs.json
|
||||
├── testimonials/
|
||||
│ └── index.html
|
||||
├── donate/
|
||||
│ └── index.html
|
||||
├── products/
|
||||
│ ├── index.html
|
||||
│ └── data.json
|
||||
├── link-redirector/
|
||||
│ └── index.html
|
||||
├── bsky/
|
||||
├── chat/
|
||||
├── games/
|
||||
├── mail/
|
||||
├── manual/
|
||||
├── sitemap/
|
||||
├── README.md
|
||||
├── CONTRIBUTING.md
|
||||
├── LICENSE.md
|
||||
├── PRIVACY.md
|
||||
├── TERMS.md
|
||||
├── SECURITY.md
|
||||
└── CODE_OF_CONDUCT.md
|
||||
```
|
||||
|
||||
### 2.3 Dependencies
|
||||
|
||||
#### 2.3.1 External Dependencies
|
||||
|
||||
- **Global Header System**: `https://cdn.nhcarrigan.com/headers/index.js`
|
||||
- Provides consistent navigation and styling across all pages
|
||||
- Loaded asynchronously with defer attribute
|
||||
- **Font Awesome**: Icon library (loaded via global header)
|
||||
- **Custom Cursors**: `https://cdn.nhcarrigan.com/cursors/pointer.cur`
|
||||
|
||||
#### 2.3.2 Internal Dependencies
|
||||
|
||||
- JSON data files for dynamic content (books.json, songs.json, data.json)
|
||||
|
||||
### 2.4 Deployment
|
||||
|
||||
The Application can be deployed to any static web host:
|
||||
|
||||
#### 2.4.1 Prerequisites
|
||||
|
||||
- Web server capable of serving static files (Nginx, Apache, etc.)
|
||||
- No server-side processing required
|
||||
- No database required
|
||||
|
||||
#### 2.4.2 Installation Steps
|
||||
|
||||
1. Clone the repository:
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd static-pages
|
||||
```
|
||||
|
||||
2. Configure your web server to serve the directory:
|
||||
|
||||
- Set document root to the static-pages directory
|
||||
- Configure directory indexing if needed
|
||||
- Ensure proper MIME types are set for .html, .json, .css files
|
||||
|
||||
3. (Optional) Update the global header CDN URL if hosting independently:
|
||||
- Replace `cdn.nhcarrigan.com/headers/index.js` with your own header script
|
||||
- Update custom cursor URLs if needed
|
||||
|
||||
#### 2.4.3 Web Server Configuration
|
||||
|
||||
**Nginx Example:**
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name your-domain.com;
|
||||
root /path/to/static-pages;
|
||||
index index.html;
|
||||
|
||||
location / {
|
||||
try_files $uri $uri/ =404;
|
||||
}
|
||||
|
||||
location ~* \.(json)$ {
|
||||
add_header Content-Type application/json;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Apache Example (.htaccess):**
|
||||
|
||||
```apache
|
||||
DirectoryIndex index.html
|
||||
Options -Indexes
|
||||
<Files ~ "\\.json$">
|
||||
Header set Content-Type "application/json"
|
||||
</Files>
|
||||
```
|
||||
|
||||
### 2.5 Data Management
|
||||
|
||||
#### 2.5.1 Books Library
|
||||
|
||||
Run `./books.sh` to update the book data. You may need to change the filepath the script reads from.
|
||||
|
||||
#### 2.5.2 Music Library
|
||||
|
||||
Run `./songs.sh` to update the music data. You may need to change the filepath the script reads from.
|
||||
|
||||
#### 2.5.3 Testimonials List
|
||||
|
||||
Run `./testimonials.sh` to update the testimonial data from our API.
|
||||
|
||||
### 2.6 Customization
|
||||
|
||||
#### 2.6.1 Styling
|
||||
|
||||
Each page uses CSS custom properties that can be overridden:
|
||||
|
||||
- `--foreground`: Primary foreground color
|
||||
- `--background`: Primary background color
|
||||
|
||||
Global styles are loaded from the CDN header system. To customize:
|
||||
|
||||
1. Fork and host your own version of the header script
|
||||
2. Update the script src in each HTML file
|
||||
3. Modify CSS custom properties in your hosted version
|
||||
|
||||
#### 2.6.2 Adding New Pages
|
||||
|
||||
1. Create a new directory in the root
|
||||
2. Add an `index.html` file
|
||||
3. Include the global header script:
|
||||
```html
|
||||
<script
|
||||
src="https://cdn.nhcarrigan.com/headers/index.js"
|
||||
async
|
||||
defer
|
||||
></script>
|
||||
```
|
||||
4. Follow the existing HTML structure for consistency
|
||||
|
||||
### 2.7 System Requirements
|
||||
|
||||
**Client-Side:**
|
||||
|
||||
- Modern web browser with JavaScript enabled
|
||||
- Support for ES6+ JavaScript features
|
||||
- Support for CSS custom properties
|
||||
|
||||
**Server-Side:**
|
||||
|
||||
- Any static file web server (Nginx, Apache, Caddy, etc.)
|
||||
- No specific server-side language requirements
|
||||
- No database requirements
|
||||
|
||||
### 2.8 Version Control
|
||||
|
||||
The Application is managed using Git:
|
||||
|
||||
- Repository hosted on Gitea (https://git.nhcarrigan.com)
|
||||
- GitHub integration available
|
||||
- Standard Git workflows supported
|
||||
|
||||
### 2.9 Continuous Integration
|
||||
|
||||
CI/CD configuration files are located in `.gitea/workflows/`:
|
||||
|
||||
- `sonar.yml`: SonarQube code quality analysis
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
The Application operates under NHCarrigan's standard legal framework:
|
||||
|
||||
### License
|
||||
This software is licensed under the [global software license](https://docs.nhcarrigan.com/#/license). Copyright is held by Naomi Carrigan.
|
||||
|
||||
### Privacy Policy
|
||||
Privacy considerations for the Application are covered under the [global privacy policy](PRIVACY.md).
|
||||
|
||||
### Terms of Service
|
||||
Terms of service for the Application are outlined in [TERMS.md](TERMS.md).
|
||||
|
||||
### Code of Conduct
|
||||
All interactions with the Application's community and codebase are governed by the [Code of Conduct](https://docs.nhcarrigan.com/#/coc), referenced in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
|
||||
|
||||
### Security Policy
|
||||
Security reporting and handling procedures are documented in [SECURITY.md](SECURITY.md).
|
||||
|
||||
### Data Handling
|
||||
- **Book Library**: Processes local book file metadata only
|
||||
- **Music Library**: Processes local music file metadata only
|
||||
- **Product Directory**: Fetches public repository information from Gitea API
|
||||
- **BlueSky Service**: Collects handle requests through Discord (manual process)
|
||||
- **No personal data**: The Application does not collect or store personal user data directly
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
### 3.1 License
|
||||
|
||||
The Application is licensed under the global software license maintained by Naomi Carrigan. Full license details are available at:
|
||||
|
||||
- **URL**: https://docs.nhcarrigan.com/#/license
|
||||
- **Copyright**: All rights reserved by Naomi Carrigan
|
||||
- **Reference**: See `LICENSE.md` in the repository root
|
||||
|
||||
### 3.2 Privacy Policy
|
||||
|
||||
User privacy is governed by the global privacy policy:
|
||||
|
||||
- **URL**: https://docs.nhcarrigan.com/#/privacy
|
||||
- **Reference**: See `PRIVACY.md` in the repository root
|
||||
- **Data Collection**: The Application itself does not collect user data; however, external links may have their own privacy policies
|
||||
|
||||
### 3.3 Terms of Service
|
||||
|
||||
Usage of the Application is subject to the global terms of service:
|
||||
|
||||
- **URL**: https://docs.nhcarrigan.com/#/terms
|
||||
- **Reference**: See `TERMS.md` in the repository root
|
||||
|
||||
### 3.4 Security Policy
|
||||
|
||||
Security-related information and vulnerability reporting:
|
||||
|
||||
- **Reference**: See `SECURITY.md` in the repository root
|
||||
- **Contact**: For security concerns, contact via the official channels listed in the security policy
|
||||
|
||||
### 3.5 Third-Party Services
|
||||
|
||||
The Application integrates with several third-party services:
|
||||
|
||||
#### 3.5.1 Donation Platforms
|
||||
|
||||
- OpenCollective
|
||||
- Patreon
|
||||
- Ko-Fi
|
||||
- PayPal
|
||||
- CashApp
|
||||
- GitHub Sponsors
|
||||
- Stripe
|
||||
- Twitch
|
||||
- Throne
|
||||
- Discord
|
||||
|
||||
Each platform has its own terms of service and privacy policy that users should review before proceeding with transactions.
|
||||
|
||||
#### 3.5.2 Content Delivery Network (CDN)
|
||||
|
||||
- **Service**: cdn.nhcarrigan.com
|
||||
- **Purpose**: Global header, navigation, and styling
|
||||
- **Data Handling**: Standard CDN caching and delivery
|
||||
|
||||
### 3.6 User Responsibilities
|
||||
|
||||
Users of the Application agree to:
|
||||
|
||||
- Use the Application for lawful purposes only
|
||||
- Respect intellectual property rights
|
||||
- Not attempt to exploit, hack, or compromise the Application's security
|
||||
- Follow the Code of Conduct when interacting with the community
|
||||
|
||||
### 3.7 Data Portability
|
||||
|
||||
All user-facing data in the Application is stored in JSON format and can be easily exported or migrated:
|
||||
|
||||
- Books data: `books/books.json`
|
||||
- Music data: `music/songs.json`
|
||||
- Products data: `products/data.json`
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
### Getting Started
|
||||
Contributors should review the [global contributing guidelines](https://docs.nhcarrigan.com/#/contributing) referenced in [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
### Development Workflow
|
||||
### 4.1 Getting Started
|
||||
|
||||
To contribute to the Application:
|
||||
|
||||
1. **Read the Contributing Guidelines**:
|
||||
|
||||
- Full guidelines: https://docs.nhcarrigan.com/#/contributing
|
||||
- Repository reference: See `CONTRIBUTING.md`
|
||||
|
||||
2. **Review the Code of Conduct**:
|
||||
|
||||
- See `CODE_OF_CONDUCT.md` in the repository root
|
||||
- Violations can be reported through official channels
|
||||
|
||||
3. **Set Up Development Environment**:
|
||||
|
||||
1. **Fork and Clone**
|
||||
```bash
|
||||
git clone https://github.com/your-username/Static Pages.git
|
||||
cd Static Pages
|
||||
# Clone the repository
|
||||
git clone <repository-url>
|
||||
cd static-pages
|
||||
|
||||
# No build tools required - edit HTML files directly
|
||||
# Use any text editor or IDE
|
||||
```
|
||||
|
||||
2. **Set Up Development Environment**
|
||||
- Install required dependencies (see Technical Documentation)
|
||||
- Configure data source paths for testing
|
||||
- Set up environment variables if working with products functionality
|
||||
### 4.2 Contribution Workflow
|
||||
|
||||
3. **Making Changes**
|
||||
- **HTML Pages**: Edit individual `index.html` files in respective directories
|
||||
- **Data Scripts**: Modify `*.sh` scripts for data generation logic
|
||||
- **Deployment**: Update `sync.sh` for deployment configuration changes
|
||||
1. **Fork the Repository**:
|
||||
|
||||
- Fork on Gitea or GitHub
|
||||
- Clone your fork locally
|
||||
|
||||
2. **Create a Feature Branch**:
|
||||
|
||||
4. **Testing Changes**
|
||||
```bash
|
||||
# Test data generation
|
||||
./books.sh
|
||||
./songs.sh
|
||||
./products.sh
|
||||
|
||||
# Test locally
|
||||
python3 -m http.server 8000
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
5. **Submitting Changes**
|
||||
- Create feature branch: `git checkout -b feature/your-feature`
|
||||
- Commit changes with descriptive messages
|
||||
- Push to your fork and create a Pull Request
|
||||
- Ensure all data generation scripts work correctly
|
||||
3. **Make Your Changes**:
|
||||
|
||||
### Code Style Guidelines
|
||||
- **HTML**: Use semantic HTML5 elements, include proper meta tags
|
||||
- **Shell Scripts**: Follow bash best practices, include error handling
|
||||
- **JSON Data**: Ensure proper formatting and validation
|
||||
- **Documentation**: Update relevant documentation for new features
|
||||
- Edit HTML, CSS, or JSON files as needed
|
||||
- Test locally by opening HTML files in a browser
|
||||
- Ensure consistent styling and structure
|
||||
|
||||
### Areas for Contribution
|
||||
- **UI/UX Improvements**: Enhance styling and user experience of static pages
|
||||
- **Data Processing**: Improve metadata extraction and data generation scripts
|
||||
- **New Features**: Add new utility pages or improve existing functionality
|
||||
- **Documentation**: Expand user guides and technical documentation
|
||||
- **Testing**: Add validation and testing for data generation processes
|
||||
- **Accessibility**: Improve accessibility compliance across all pages
|
||||
4. **Commit Your Changes**:
|
||||
|
||||
### Communication
|
||||
- **Issues**: Report bugs and request features through GitHub Issues
|
||||
- **Support**: Join the [chat server](https://chat.nhcarrigan.com) for discussion
|
||||
- **Contact**: Reach out via email at `contact@nhcarrigan.com`
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: description of your changes"
|
||||
```
|
||||
|
||||
### Review Process
|
||||
All Pull Requests are reviewed for:
|
||||
- Code quality and adherence to project standards
|
||||
- Functionality and testing
|
||||
5. **Push to Your Fork**:
|
||||
|
||||
```bash
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
|
||||
6. **Open a Pull Request**:
|
||||
- Navigate to the original repository
|
||||
- Click "New Pull Request"
|
||||
- Fill out the pull request template in `.gitea/pull_request_template.yml`
|
||||
|
||||
### 4.3 Coding Standards
|
||||
|
||||
#### 4.3.1 HTML Standards
|
||||
|
||||
- Use HTML5 semantic elements
|
||||
- Include proper DOCTYPE declaration
|
||||
- Set UTF-8 charset
|
||||
- Include viewport meta tag for responsive design
|
||||
- Use descriptive page titles and meta descriptions
|
||||
|
||||
#### 4.3.2 CSS Standards
|
||||
|
||||
- Use CSS custom properties for theming
|
||||
- Maintain responsive design principles
|
||||
- Use consistent class naming conventions
|
||||
- Include print styles where appropriate
|
||||
- Test cross-browser compatibility
|
||||
|
||||
#### 4.3.3 JavaScript Standards
|
||||
|
||||
- Use vanilla JavaScript (no frameworks)
|
||||
- Follow ES6+ standards
|
||||
- Use const/let instead of var
|
||||
- Include error handling where appropriate
|
||||
- Keep functions small and focused
|
||||
- Comment complex logic
|
||||
|
||||
#### 4.3.4 JSON Data Standards
|
||||
|
||||
- Maintain consistent schema within each data file
|
||||
- Use proper JSON formatting (validated)
|
||||
- Include all required fields
|
||||
- Use descriptive keys
|
||||
|
||||
### 4.4 Testing
|
||||
|
||||
Before submitting a pull request:
|
||||
|
||||
1. **Manual Testing**:
|
||||
|
||||
- Open each modified HTML file in multiple browsers
|
||||
- Test on both desktop and mobile viewports
|
||||
- Verify all links work correctly
|
||||
- Ensure JSON data loads properly
|
||||
|
||||
2. **Validation**:
|
||||
|
||||
- Validate HTML using W3C validator
|
||||
- Validate JSON syntax using a JSON validator
|
||||
- Check CSS for syntax errors
|
||||
|
||||
3. **Cross-Browser Testing**:
|
||||
- Test in Chrome/Chromium
|
||||
- Test in Firefox
|
||||
- Test in Safari (if available)
|
||||
- Test in Edge
|
||||
|
||||
### 4.5 Issue Reporting
|
||||
|
||||
Use the issue templates in `.gitea/issue_template/`:
|
||||
|
||||
#### 4.5.1 Bug Reports
|
||||
|
||||
- Template: `bug_report.yaml`
|
||||
- Include reproduction steps
|
||||
- Provide browser and OS information
|
||||
- Include screenshots if applicable
|
||||
|
||||
#### 4.5.2 Feature Proposals
|
||||
|
||||
- Template: `feature_proposal.yml`
|
||||
- Describe the feature clearly
|
||||
- Explain the use case
|
||||
- Consider implementation impact
|
||||
|
||||
#### 4.5.3 Other Issues
|
||||
|
||||
- Template: `other.yml`
|
||||
- For general inquiries or discussions
|
||||
|
||||
### 4.6 Pull Request Guidelines
|
||||
|
||||
- Fill out the pull request template completely
|
||||
- Reference related issues using `#issue-number`
|
||||
- Keep changes focused on a single feature or fix
|
||||
- Update documentation if needed
|
||||
- Respond to review feedback promptly
|
||||
- Ensure CI checks pass (if applicable)
|
||||
|
||||
### 4.7 Communication Channels
|
||||
|
||||
- **GitHub Issues**: For bug reports and feature requests
|
||||
- **Chat Server**: http://chat.nhcarrigan.com
|
||||
- **Email**: contact@nhcarrigan.com
|
||||
- **Pull Request Discussions**: For code-specific conversations
|
||||
|
||||
### 4.8 Areas for Contribution
|
||||
|
||||
#### 4.8.1 High Priority
|
||||
|
||||
- Accessibility improvements
|
||||
- Cross-browser compatibility fixes
|
||||
- Performance optimizations
|
||||
- Documentation updates
|
||||
- Security considerations
|
||||
- Compatibility with existing deployment process
|
||||
|
||||
#### 4.8.2 Medium Priority
|
||||
|
||||
- New page additions
|
||||
- Enhanced filtering/search features
|
||||
- Visual design improvements
|
||||
- Mobile experience enhancements
|
||||
|
||||
#### 4.8.3 Low Priority
|
||||
|
||||
- Additional data entries (books, music, etc.)
|
||||
- Minor styling tweaks
|
||||
- Code refactoring
|
||||
|
||||
### 4.9 Recognition
|
||||
|
||||
Contributors are recognized through:
|
||||
|
||||
- Git commit history
|
||||
- Pull request acknowledgments
|
||||
- Potential testimonial features for significant contributions
|
||||
|
||||
### 4.10 Development Tools
|
||||
|
||||
Recommended tools for contributing:
|
||||
|
||||
- **Editors**: VS Code, Sublime Text, Atom, or any text editor
|
||||
- **Browser DevTools**: Chrome DevTools, Firefox Developer Tools
|
||||
- **Validators**: W3C HTML Validator, JSONLint
|
||||
- **Version Control**: Git (command line or GUI)
|
||||
|
||||
### 4.11 Local Development
|
||||
|
||||
To run locally:
|
||||
|
||||
1. **Simple HTTP Server (Python)**:
|
||||
|
||||
```bash
|
||||
python -m http.server 8000
|
||||
# Visit http://localhost:8000
|
||||
```
|
||||
|
||||
2. **Simple HTTP Server (Node.js)**:
|
||||
|
||||
```bash
|
||||
npx http-server -p 8000
|
||||
# Visit http://localhost:8000
|
||||
```
|
||||
|
||||
3. **VS Code Live Server Extension**:
|
||||
- Install Live Server extension
|
||||
- Right-click HTML file → "Open with Live Server"
|
||||
|
||||
### 4.12 Commit Message Guidelines
|
||||
|
||||
Follow conventional commit format:
|
||||
|
||||
- `feat:` New features
|
||||
- `fix:` Bug fixes
|
||||
- `docs:` Documentation changes
|
||||
- `style:` Code formatting (no logic changes)
|
||||
- `refactor:` Code refactoring
|
||||
- `test:` Test additions or updates
|
||||
- `chore:` Build process or tooling changes
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
feat: add search functionality to testimonials page
|
||||
|
||||
- Implement client-side search filtering
|
||||
- Add search input with clear button
|
||||
- Update styling for search controls
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Appendix A: Page-Specific Technical Details
|
||||
|
||||
### Books Page
|
||||
|
||||
- **Data Source**: `books/books.json`
|
||||
- **JavaScript Functions**:
|
||||
- `loadBooks(books)`: Initializes the book list
|
||||
- `filterBooks(author, title)`: Filters books by author and/or title
|
||||
- `updateTable(books)`: Renders the book table
|
||||
- **Current Count**: 1,210 books
|
||||
|
||||
### Music Page
|
||||
|
||||
- **Data Source**: `music/songs.json`
|
||||
- **JavaScript Functions**:
|
||||
- `loadSongs(songs)`: Initializes the song list
|
||||
- `filterSongs(artist, title)`: Filters songs by artist and/or title
|
||||
- `updateTable(songs)`: Renders the song table
|
||||
|
||||
### Products Page
|
||||
|
||||
- **Data Source**: `products/data.json`
|
||||
- **JavaScript Functions**:
|
||||
- `loadProducts(products)`: Processes and displays products by category
|
||||
- `titleCase(name)`: Converts kebab-case to Title Case
|
||||
- **Categories**: public, private, games, archived
|
||||
- **Current Count**: ~50 products
|
||||
|
||||
### Testimonials Page
|
||||
|
||||
- **Data Format**: Static HTML cards generated from source
|
||||
- **Styling Features**:
|
||||
- Screen-optimized and print-optimized views
|
||||
- Responsive card layout
|
||||
- Chronological ordering
|
||||
- **Submission**: Via web form at `https://forms.nhcarrigan.com/form/M_GrmqASymmO744axMOmu2LaMAaT5F0LmdVcU2c8-gQ`
|
||||
|
||||
---
|
||||
|
||||
**Document Version**: 1.0
|
||||
**Last Updated**: 2025-10-29
|
||||
**Maintained By**: Naomi Carrigan
|
||||
**Contact**: contact@nhcarrigan.com
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Sybil
|
||||
---
|
||||
|
||||
Sybil (hereinafter the "Application") is a Discord bot that syndicates forum threads to an indexable website and generates help articles based on resolved conversations.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Tessara
|
||||
---
|
||||
|
||||
Tessara (hereinafter the "Application") is a Discord bot that allows you to collect and use trading cards that are actually conversation starters.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Thalassa
|
||||
---
|
||||
|
||||
Thalassa (hereinafter the "Application") is a rich presence application for Linux.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Theodora
|
||||
---
|
||||
|
||||
Theodora (hereinafter the "Application") is a Discord bot that generates 100 days of code reminders.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Thessalia
|
||||
---
|
||||
|
||||
Thessalia (hereinafter the "Application") is an RPG game on Discord
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,313 @@
|
||||
---
|
||||
title: TypeScript Configuration Package
|
||||
---
|
||||
|
||||
TypeScript Configuration Package (hereinafter the "Application") is a shareable TypeScript compiler configuration package designed to enforce strict type checking and consistent coding standards across multiple TypeScript projects. The Application provides a pre-configured `tsconfig.json` that can be extended by other projects to maintain code quality and catch potential errors during development.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
### 1.1 Overview
|
||||
|
||||
The Application is a published npm package (`@nhcarrigan/typescript-config`) that provides a standardized TypeScript configuration. It enforces strict typing rules and modern ECMAScript standards to improve code quality and maintainability.
|
||||
|
||||
### 1.2 Installation
|
||||
|
||||
To install the Application in your project, use the following command:
|
||||
|
||||
```bash
|
||||
npm i @nhcarrigan/typescript-config typescript
|
||||
```
|
||||
|
||||
Or with pnpm:
|
||||
|
||||
```bash
|
||||
pnpm add @nhcarrigan/typescript-config typescript
|
||||
```
|
||||
|
||||
### 1.3 Usage
|
||||
|
||||
After installation, extend the Application's configuration in your project's `tsconfig.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"extends": "@nhcarrigan/typescript-config",
|
||||
"compilerOptions": {
|
||||
"rootDir": "./src",
|
||||
"outDir": "./prod"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Important Notes:**
|
||||
- You must specify `rootDir` and `outDir` in your project's `tsconfig.json` as these are not set by default in version 4.0.0 and above
|
||||
- Set these directories to match your project's structure
|
||||
- The Application is compatible with TypeScript 5 and above
|
||||
|
||||
### 1.4 Configuration Features
|
||||
|
||||
The Application provides the following compiler options:
|
||||
|
||||
#### Target and Module System
|
||||
- **Target**: ES2022 - Compiles code to ECMAScript 2022 standard
|
||||
- **Module**: ES2022 - Uses ES2022 module system
|
||||
- **Module Resolution**: Node - Uses Node.js module resolution strategy
|
||||
|
||||
#### Type Safety
|
||||
- **Strict Mode**: Enabled - Enforces all strict type-checking options
|
||||
- **Exact Optional Property Types**: Enabled - Distinguishes between `undefined` and absent properties
|
||||
- **No Unchecked Indexed Access**: Enabled - Adds `undefined` to index signature results
|
||||
- **No Implicit Returns**: Enabled - Ensures functions return values consistently
|
||||
|
||||
#### Code Quality
|
||||
- **No Unreachable Code**: Disallowed - Prevents dead code
|
||||
- **No Unused Labels**: Disallowed - Prevents unused labels
|
||||
- **No Fallthrough Cases in Switch**: Enabled - Requires explicit fallthrough in switch statements
|
||||
- **No Implicit Override**: Enabled - Requires explicit `override` keyword
|
||||
- **No Unused Locals**: Enabled - Reports unused local variables
|
||||
- **No Unused Parameters**: Enabled - Reports unused function parameters
|
||||
|
||||
#### Interoperability
|
||||
- **ES Module Interop**: Enabled - Improves compatibility with CommonJS modules
|
||||
- **Skip Lib Check**: Enabled - Skips type checking of declaration files
|
||||
- **Force Consistent Casing in Filenames**: Enabled - Ensures case-sensitive file imports
|
||||
|
||||
### 1.5 Package Information
|
||||
|
||||
- **Version**: 4.0.0
|
||||
- **NPM Package**: [@nhcarrigan/typescript-config](https://www.npmjs.com/package/@nhcarrigan/typescript-config)
|
||||
- **Author**: Naomi Carrigan
|
||||
- **License**: [Global Software License](https://docs.nhcarrigan.com/#/license)
|
||||
|
||||
### 1.6 Support and Feedback
|
||||
|
||||
- **Issues**: Report bugs at [Codeberg Issues](https://codeberg.org/naomi-lgbt/typescript-config/issues)
|
||||
- **Contact**: Available via [Chat Server](http://chat.nhcarrigan.com) or email at `contact@nhcarrigan.com`
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
### 2.1 Project Structure
|
||||
|
||||
The Application has a minimal structure focused on distributing a TypeScript configuration:
|
||||
|
||||
```
|
||||
typescript-config/
|
||||
├── src/
|
||||
│ └── index.ts # Test file for validating configuration
|
||||
├── tsconfig.json # The main configuration file
|
||||
├── package.json # Package metadata and dependencies
|
||||
└── [documentation files] # README, LICENSE, CONTRIBUTING, etc.
|
||||
```
|
||||
|
||||
### 2.2 Source Code
|
||||
|
||||
#### Configuration File (tsconfig.json:1)
|
||||
|
||||
The main configuration file exports the following compiler options:
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "ES2022",
|
||||
"moduleResolution": "Node",
|
||||
"allowUnreachableCode": false,
|
||||
"allowUnusedLabels": false,
|
||||
"exactOptionalPropertyTypes": true,
|
||||
"noFallthroughCasesInSwitch": true,
|
||||
"noImplicitOverride": true,
|
||||
"noImplicitReturns": true,
|
||||
"noUncheckedIndexedAccess": true,
|
||||
"noUnusedLocals": true,
|
||||
"noUnusedParameters": true,
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"forceConsistentCasingInFileNames": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Test File (src/index.ts:1)
|
||||
|
||||
The source directory contains a minimal test file used to validate that the configuration compiles correctly:
|
||||
|
||||
```typescript
|
||||
(async () => {
|
||||
console.log("just testing!");
|
||||
})();
|
||||
```
|
||||
|
||||
This file serves as a smoke test to ensure the TypeScript configuration is valid.
|
||||
|
||||
### 2.3 Development Setup
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
- Node.js version 20
|
||||
- pnpm version 9
|
||||
- TypeScript >= 5.5.2 (peer dependency)
|
||||
|
||||
#### Local Development
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone git@codeberg.org:naomi-lgbt/typescript-config.git
|
||||
cd typescript-config
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
3. Run tests:
|
||||
```bash
|
||||
pnpm test
|
||||
```
|
||||
|
||||
The test script runs the TypeScript compiler with specific `rootDir` and `outDir` settings to validate the configuration.
|
||||
|
||||
### 2.4 Build and Test Process
|
||||
|
||||
The Application uses a simple test script defined in package.json:6:
|
||||
|
||||
```bash
|
||||
tsc --rootDir './src' --outDir './prod' && echo 'build appears valid!'
|
||||
```
|
||||
|
||||
This command:
|
||||
1. Compiles TypeScript files from the `src` directory
|
||||
2. Outputs compiled JavaScript to the `prod` directory
|
||||
3. Confirms successful compilation with a success message
|
||||
|
||||
### 2.5 Publishing
|
||||
|
||||
The Application is published to npm under the package name `@nhcarrigan/typescript-config`. The main entry point is the `tsconfig.json` file itself (as specified in package.json:5).
|
||||
|
||||
### 2.6 Version History
|
||||
|
||||
The current version is 4.0.0, which introduced breaking changes:
|
||||
- Removed default `rootDir` and `outDir` settings
|
||||
- Users must now explicitly set these in their project's `tsconfig.json`
|
||||
- This change resolves incompatibilities with certain package managers
|
||||
|
||||
### 2.7 Design Decisions
|
||||
|
||||
The configuration emphasizes:
|
||||
1. **Strict Type Checking**: All strict options are enabled to catch potential errors at compile time
|
||||
2. **Modern JavaScript**: Targets ES2022 for modern language features
|
||||
3. **Code Quality**: Enforces best practices like no unused variables, no unreachable code
|
||||
4. **Flexibility**: Allows projects to specify their own directory structure (rootDir/outDir)
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
### 3.1 License
|
||||
|
||||
The Application is licensed under the [Global Software License](https://docs.nhcarrigan.com/#/license). Copyright is held by Naomi Carrigan.
|
||||
|
||||
See LICENSE.md for full license details.
|
||||
|
||||
### 3.2 Terms of Service
|
||||
|
||||
Users of the Application are subject to the global Terms of Service available at [https://docs.nhcarrigan.com/#/terms](https://docs.nhcarrigan.com/#/terms).
|
||||
|
||||
See TERMS.md for reference.
|
||||
|
||||
### 3.3 Privacy Policy
|
||||
|
||||
The Application does not collect or transmit any user data. For general privacy policies, refer to [https://docs.nhcarrigan.com/#/privacy](https://docs.nhcarrigan.com/#/privacy).
|
||||
|
||||
See PRIVACY.md for reference.
|
||||
|
||||
### 3.4 Security Policy
|
||||
|
||||
Security vulnerabilities should be reported according to the guidelines at [https://docs.nhcarrigan.com/#/security](https://docs.nhcarrigan.com/#/security).
|
||||
|
||||
See SECURITY.md for reference.
|
||||
|
||||
### 3.5 Intellectual Property
|
||||
|
||||
The Application's configuration is an original work created by Naomi Carrigan. The specific combination of TypeScript compiler options represents curated decisions for code quality and safety.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
### 4.1 Contributing Guidelines
|
||||
|
||||
Comprehensive contributing guidelines are available at [https://docs.nhcarrigan.com/#/contributing](https://docs.nhcarrigan.com/#/contributing).
|
||||
|
||||
See CONTRIBUTING.md for reference.
|
||||
|
||||
### 4.2 Code of Conduct
|
||||
|
||||
Before interacting with the community, please review the Code of Conduct available in CODE_OF_CONDUCT.md.
|
||||
|
||||
### 4.3 How to Contribute
|
||||
|
||||
#### Reporting Issues
|
||||
|
||||
If you encounter bugs or have feature requests:
|
||||
1. Check existing issues at [Codeberg Issues](https://codeberg.org/naomi-lgbt/typescript-config/issues)
|
||||
2. Create a new issue with a clear description
|
||||
3. Include TypeScript version and package manager information
|
||||
|
||||
#### Submitting Changes
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes to the configuration
|
||||
4. Test that the configuration compiles correctly (`pnpm test`)
|
||||
5. Submit a Pull Request with a clear description of changes
|
||||
6. Await review from maintainers
|
||||
|
||||
#### Configuration Changes
|
||||
|
||||
When proposing changes to the TypeScript configuration:
|
||||
- Explain the rationale for the change
|
||||
- Document any breaking changes
|
||||
- Consider backward compatibility
|
||||
- Test with various TypeScript projects to ensure compatibility
|
||||
|
||||
### 4.4 Development Workflow
|
||||
|
||||
1. Clone the repository
|
||||
2. Create a branch for your changes
|
||||
3. Modify `tsconfig.json` as needed
|
||||
4. Run `pnpm test` to validate changes
|
||||
5. Update documentation if necessary
|
||||
6. Commit with clear, descriptive messages
|
||||
7. Submit a Pull Request
|
||||
|
||||
### 4.5 Testing Changes
|
||||
|
||||
To test configuration changes:
|
||||
1. Make modifications to `tsconfig.json`
|
||||
2. Run the test script: `pnpm test`
|
||||
3. Test in a real project by linking locally:
|
||||
```bash
|
||||
# In this package directory
|
||||
pnpm link
|
||||
|
||||
# In your test project
|
||||
pnpm link @nhcarrigan/typescript-config
|
||||
```
|
||||
4. Verify the configuration works as expected
|
||||
|
||||
### 4.6 Repository Information
|
||||
|
||||
- **Repository**: [https://codeberg.org/naomi-lgbt/typescript-config](https://codeberg.org/naomi-lgbt/typescript-config)
|
||||
- **Issue Tracker**: [https://codeberg.org/naomi-lgbt/typescript-config/issues](https://codeberg.org/naomi-lgbt/typescript-config/issues)
|
||||
- **Git URL**: `git@codeberg.org:naomi-lgbt/typescript-config.git`
|
||||
|
||||
### 4.7 Contact
|
||||
|
||||
For questions about contributing:
|
||||
- Join the [Chat Server](http://chat.nhcarrigan.com)
|
||||
- Email: `contact@nhcarrigan.com`
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Verena
|
||||
---
|
||||
|
||||
Verena (hereinafter the "Application") is a Discord bot that allows identity and age verification.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Vitalia
|
||||
---
|
||||
|
||||
Vitalia (hereinafter the "Application") is a full-featured nutrition tracker with community-driven nutrient data.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Vivienne
|
||||
---
|
||||
|
||||
Vivienne (hereinafter the "Application") is an RSS feed reader/management site.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
@@ -0,0 +1,330 @@
|
||||
---
|
||||
title: Naomi's Themes
|
||||
---
|
||||
|
||||
Naomi's Themes (hereinafter the "Application") is a Visual Studio Code extension that provides a curated collection of custom color themes designed to enhance the coding experience with aesthetically pleasing color schemes. The Application currently offers four distinct themes: Ocean Breeze, Sakura Dreams, Sakura Dreams (Dark), and Trans Pride.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
### 1.1 Overview
|
||||
|
||||
Naomi's Themes is a VSCode extension that provides custom color themes for your code editor. Each theme has been carefully crafted with specific color palettes to create visually appealing and comfortable coding environments.
|
||||
|
||||
### 1.2 Available Themes
|
||||
|
||||
The Application includes the following themes:
|
||||
|
||||
- **Ocean Breeze**: A dark theme featuring soothing teal and cyan colors reminiscent of ocean waves, designed for extended coding sessions with reduced eye strain
|
||||
- **Sakura Dreams**: A light theme inspired by cherry blossoms with soft, pastel colors
|
||||
- **Sakura Dreams (Dark)**: A dark variant of the Sakura Dreams theme, maintaining the cherry blossom aesthetic while providing a darker background
|
||||
- **Trans Pride**: A light theme celebrating trans pride with a carefully selected color palette
|
||||
|
||||
### 1.3 Installation
|
||||
|
||||
1. Open Visual Studio Code
|
||||
2. Navigate to the Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
|
||||
3. Search for "Naomi's Themes" by nhcarrigan
|
||||
4. Click "Install"
|
||||
|
||||
### 1.4 Activating a Theme
|
||||
|
||||
After installation:
|
||||
|
||||
1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
|
||||
2. Type "Preferences: Color Theme"
|
||||
3. Select your desired theme from the list:
|
||||
- Ocean Breeze
|
||||
- Sakura Dreams
|
||||
- Sakura Dreams (Dark)
|
||||
- Trans Pride
|
||||
|
||||
### 1.5 Requirements
|
||||
|
||||
- Visual Studio Code version 1.96.4 or higher
|
||||
|
||||
### 1.6 Support and Feedback
|
||||
|
||||
If you encounter any issues or have feedback:
|
||||
|
||||
- Open an issue at: https://git.nhcarrigan.com/nhcarrigan/vscode-themes/issues
|
||||
- Contact via Chat Server: http://chat.nhcarrigan.com
|
||||
- Email: contact@nhcarrigan.com
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
### 2.1 Architecture
|
||||
|
||||
The Application is structured as a standard VSCode extension with the following components:
|
||||
|
||||
- **Theme Definitions**: JSON files located in the `themes/` directory, each defining color schemes for UI elements and syntax highlighting
|
||||
- **Extension Manifest**: `package.json` containing metadata and theme contributions
|
||||
- **Assets**: `icon.png` for the extension icon
|
||||
|
||||
### 2.2 Project Structure
|
||||
|
||||
```
|
||||
vscode-themes/
|
||||
├── themes/
|
||||
│ ├── ocean-breeze.json
|
||||
│ ├── sakura-dreams.json
|
||||
│ ├── sakura-dreams-dark.json
|
||||
│ └── trans-pride.json
|
||||
├── package.json
|
||||
├── icon.png
|
||||
├── README.md
|
||||
├── LICENSE.md
|
||||
├── CONTRIBUTING.md
|
||||
├── CODE_OF_CONDUCT.md
|
||||
├── PRIVACY.md
|
||||
├── TERMS.md
|
||||
└── SECURITY.md
|
||||
```
|
||||
|
||||
### 2.3 Local Development Setup
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
- Node.js and npm installed
|
||||
- Visual Studio Code installed
|
||||
- vsce (Visual Studio Code Extension Manager) installed globally
|
||||
|
||||
#### Setup Steps
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone https://git.nhcarrigan.com/nhcarrigan/vscode-themes.git
|
||||
cd vscode-themes
|
||||
```
|
||||
|
||||
2. Install vsce if not already installed:
|
||||
```bash
|
||||
npm install -g @vscode/vsce
|
||||
```
|
||||
|
||||
3. Package the extension:
|
||||
```bash
|
||||
npm run package
|
||||
```
|
||||
|
||||
4. Install the packaged extension in VSCode:
|
||||
- Open VSCode
|
||||
- Go to Extensions view
|
||||
- Click the "..." menu
|
||||
- Select "Install from VSIX..."
|
||||
- Choose the generated `.vsix` file
|
||||
|
||||
### 2.4 Creating a Theme
|
||||
|
||||
Each theme is defined in a JSON file with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Theme Name",
|
||||
"type": "dark" or "light",
|
||||
"colors": {
|
||||
// UI element colors
|
||||
},
|
||||
"tokenColors": [
|
||||
// Syntax highlighting rules
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Key sections:
|
||||
|
||||
- **colors**: Defines colors for editor UI elements (background, foreground, sidebar, statusbar, etc.)
|
||||
- **tokenColors**: Array of rules defining syntax highlighting colors based on TextMate scopes
|
||||
|
||||
For example, see `themes/ocean-breeze.json` at lines 1-373.
|
||||
|
||||
### 2.5 Building and Packaging
|
||||
|
||||
The package script is configured in `package.json` at lines 38-39:
|
||||
|
||||
```bash
|
||||
npm run package
|
||||
```
|
||||
|
||||
This command:
|
||||
- Packages the extension into a `.vsix` file
|
||||
- Sets the base content and images URLs to the repository
|
||||
|
||||
### 2.6 Publishing
|
||||
|
||||
The extension is published by nhcarrigan to the VSCode Marketplace. The publisher configuration is defined in `package.json` at line 10.
|
||||
|
||||
### 2.7 Version Management
|
||||
|
||||
Current version: 2.2.0 (as defined in `package.json` at line 5)
|
||||
|
||||
Version history (from git commits):
|
||||
- 2.2.0: Current release
|
||||
- 2.1.0: Added dark mode and updated source links
|
||||
- 2.0.0: Major version update
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
### 3.1 License
|
||||
|
||||
The Application is licensed under Naomi Carrigan's global software license, available at: https://docs.nhcarrigan.com/#/license
|
||||
|
||||
Copyright is held by Naomi Carrigan.
|
||||
|
||||
Reference: `LICENSE.md` at lines 1-5
|
||||
|
||||
### 3.2 Privacy Policy
|
||||
|
||||
The Application adheres to the privacy policy documented at: https://docs.nhcarrigan.com/#/privacy
|
||||
|
||||
As a VSCode theme extension, the Application:
|
||||
- Does not collect any user data
|
||||
- Does not transmit any information externally
|
||||
- Operates entirely locally within VSCode
|
||||
|
||||
Reference: `PRIVACY.md` at lines 1-3
|
||||
|
||||
### 3.3 Terms of Service
|
||||
|
||||
The Application is governed by the Terms of Service available at: https://docs.nhcarrigan.com/#/terms
|
||||
|
||||
Reference: `TERMS.md` at lines 1-3
|
||||
|
||||
### 3.4 Security Policy
|
||||
|
||||
Security policies and vulnerability reporting procedures are documented in `SECURITY.md`.
|
||||
|
||||
### 3.5 Intellectual Property
|
||||
|
||||
All themes, color schemes, and design elements are copyright of Naomi Carrigan. The theme names "Ocean Breeze," "Sakura Dreams," and "Trans Pride" are part of this intellectual property.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
### 4.1 Contributing Guidelines
|
||||
|
||||
Complete contributing guidelines are available at: https://docs.nhcarrigan.com/#/contributing
|
||||
|
||||
Reference: `CONTRIBUTING.md` at lines 1-3
|
||||
|
||||
### 4.2 Code of Conduct
|
||||
|
||||
Before participating in the project, please review the Code of Conduct at: https://git.nhcarrigan.com/nhcarrigan/vscode-themes/src/branch/main/CODE_OF_CONDUCT.md
|
||||
|
||||
The project maintains a welcoming and inclusive environment for all contributors.
|
||||
|
||||
Reference: `README.md` at lines 13-15
|
||||
|
||||
### 4.3 How to Contribute
|
||||
|
||||
#### Reporting Issues
|
||||
|
||||
1. Check existing issues at: https://git.nhcarrigan.com/nhcarrigan/vscode-themes/issues
|
||||
2. Create a new issue with:
|
||||
- Clear description of the problem or suggestion
|
||||
- Steps to reproduce (for bugs)
|
||||
- Expected vs. actual behavior
|
||||
- VSCode version and operating system
|
||||
|
||||
#### Submitting Pull Requests
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch from `main`
|
||||
3. Make your changes:
|
||||
- For new themes: Add a new JSON file in `themes/` directory
|
||||
- For theme modifications: Edit the respective JSON file
|
||||
- Update `package.json` if adding a new theme
|
||||
4. Test your changes locally by packaging and installing the extension
|
||||
5. Commit your changes with clear, descriptive commit messages
|
||||
6. Submit a pull request to the `main` branch
|
||||
7. Await review from the maintainers
|
||||
|
||||
#### Theme Contribution Guidelines
|
||||
|
||||
When contributing a new theme:
|
||||
|
||||
1. Ensure the theme has a unique name and aesthetic
|
||||
2. Define both `colors` and `tokenColors` sections comprehensively
|
||||
3. Test the theme with multiple programming languages
|
||||
4. Ensure sufficient contrast for accessibility
|
||||
5. Add the theme entry to `package.json` under `contributes.themes`
|
||||
6. Specify the correct `uiTheme` base ("vs" for light, "vs-dark" for dark)
|
||||
|
||||
Example theme entry in `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "Your Theme Name",
|
||||
"uiTheme": "vs-dark",
|
||||
"path": "./themes/your-theme-name.json"
|
||||
}
|
||||
```
|
||||
|
||||
Reference: `package.json` at lines 14-36
|
||||
|
||||
### 4.4 Development Standards
|
||||
|
||||
#### File Naming Conventions
|
||||
|
||||
- Theme files: Use kebab-case (e.g., `ocean-breeze.json`, `sakura-dreams-dark.json`)
|
||||
- Theme files should be placed in the `themes/` directory
|
||||
|
||||
#### JSON Formatting
|
||||
|
||||
- Use 2-space indentation
|
||||
- Ensure valid JSON syntax
|
||||
- Include all required theme properties
|
||||
|
||||
#### Color Guidelines
|
||||
|
||||
- Use hex color codes (e.g., `#012a22`)
|
||||
- Consider accessibility and contrast ratios
|
||||
- Test colors in both day and night lighting conditions
|
||||
- Document color inspiration or theme concept if applicable
|
||||
|
||||
### 4.5 Testing
|
||||
|
||||
Before submitting:
|
||||
|
||||
1. Package the extension locally using `npm run package`
|
||||
2. Install the VSIX file in a clean VSCode instance
|
||||
3. Test the theme with multiple file types:
|
||||
- JavaScript/TypeScript
|
||||
- Python
|
||||
- Rust
|
||||
- HTML/CSS
|
||||
- Markdown
|
||||
4. Verify UI elements (sidebar, statusbar, tabs, etc.) are properly styled
|
||||
5. Check for color contrast issues
|
||||
|
||||
### 4.6 Release Process
|
||||
|
||||
Releases are managed by the project maintainer (Naomi Carrigan). The typical release process:
|
||||
|
||||
1. Update version in `package.json`
|
||||
2. Commit version changes
|
||||
3. Create a git tag for the version
|
||||
4. Run `npm run package` to generate the VSIX file
|
||||
5. Publish to VSCode Marketplace (maintainer only)
|
||||
|
||||
Recent release pattern (from git history):
|
||||
- Version bumps follow semantic versioning
|
||||
- Releases are tagged in git
|
||||
- Each release includes descriptive commit messages
|
||||
|
||||
### 4.7 Community and Communication
|
||||
|
||||
- Issues and discussions: https://git.nhcarrigan.com/nhcarrigan/vscode-themes/issues
|
||||
- Chat Server: http://chat.nhcarrigan.com
|
||||
- Email: contact@nhcarrigan.com
|
||||
- Homepage: https://nhcarrigan.com
|
||||
|
||||
### 4.8 Recognition
|
||||
|
||||
Contributors are valued members of the project. Significant contributions may be recognized in release notes or project documentation.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Zephra
|
||||
---
|
||||
|
||||
Zephra (hereinafter the "Application") is a micro-blogging social media platform.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
:::note
|
||||
This section is coming soon!
|
||||
:::
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
Reference in New Issue
Block a user