Skip to content

Commit 7230c88

Browse files
psjamesppsjamesp
authored
Merge pull request #1 from PowerShellOrg/discord-mirror
Add Discord mirror exporter, config, and docs
2 parents 5d14c0e + 619e603 commit 7230c88

9 files changed

Lines changed: 898 additions & 0 deletions

‎DISCORD_MIRROR_DEPLOYMENT.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Discord Mirror Deployment Guide for PowerShell.org
2+
3+
This repository contains a PowerShell-based Discord mirror that publishes selected Discord channel content into the Hugo site under `/discord/`.
4+
5+
## What this does
6+
7+
- Pulls messages from **specific allowlisted channels** in the PowerShell.org Discord server.
8+
- Applies **moderation controls** before any content is published.
9+
- Generates Hugo content pages in `content/discord/`.
10+
- Generates search assets in `static/discord/`.
11+
- Leaves all attachments and images hosted by Discord and links back to them.
12+
13+
## Required GitHub secret
14+
15+
Add this repository secret:
16+
17+
- `DISCORD_BOT_TOKEN`
18+
19+
## Required config updates
20+
21+
Edit `config/discord-mirror.json`:
22+
23+
- Replace `discord.guildId`
24+
- Replace each placeholder channel ID
25+
- Tune moderation mode per channel
26+
- Tune `minMessageAgeMinutes` per channel
27+
- Optionally adjust regex filters
28+
29+
## Recommended moderation modes
30+
31+
### `all`
32+
Publish everything in that channel after the minimum age filter.
33+
34+
Use for:
35+
- announcements
36+
- release channels
37+
- moderator-curated channels only
38+
39+
### `reaction`
40+
Only publish messages that have the approval reaction, such as ✅.
41+
42+
Use for:
43+
- help channels
44+
- showcase channels
45+
- Q&A highlights
46+
47+
### `prefix`
48+
Only publish messages whose content starts with a configured prefix, such as `[publish]`.
49+
50+
Use for:
51+
- moderator repost channels
52+
- copy-edited summaries
53+
54+
### `author-role`
55+
Only publish messages authored by users with one of the configured role names.
56+
57+
Use for:
58+
- staff summaries
59+
- trusted publisher channels
60+
61+
### `any`
62+
Publish a message if any of the enabled approval mechanisms match.
63+
64+
Use for:
65+
- flexible moderation workflows
66+
67+
## Workflow behavior
68+
69+
- On `main` branch pushes, the workflow runs the Discord exporter if `DISCORD_BOT_TOKEN` is present.
70+
- On pull requests or when the secret is missing, the Hugo build still runs but the Discord export step is skipped.
71+
72+
## Validation checklist
73+
74+
1. Confirm the bot can read the selected channels.
75+
2. Confirm the bot can read message history.
76+
3. Confirm `https://powershell.org/discord/` renders.
77+
4. Confirm `https://powershell.org/discord/search/` loads search results.
78+
5. Confirm no private or unapproved messages appear.
79+
6. Confirm attachment links point to Discord URLs.
80+
81+
## Operational advice
82+
83+
Do not point this at high-noise general chat and hope for the best. That is how you build a searchable landfill.

‎DISCORD_MIRROR_MODERATION_GUIDE.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Discord Mirror Moderation Guide (v5)
2+
3+
This version adds practical publication controls so PowerShell.org can expose selected Discord content on the public web without blindly dumping channel history.
4+
5+
## Controls available
6+
7+
### 1. Channel allowlist
8+
Only channels listed in `config/discord-mirror.json` are processed.
9+
10+
### 2. Per-channel moderation mode
11+
Each channel can choose one of these modes:
12+
13+
- `all`
14+
- `reaction`
15+
- `prefix`
16+
- `author-role`
17+
- `any`
18+
19+
### 3. Minimum message age
20+
`minMessageAgeMinutes` delays publication so moderators have time to correct or remove content.
21+
22+
Examples:
23+
- `60` for announcements
24+
- `1440` for support highlights
25+
- `10080` for weekly editorial review
26+
27+
### 4. Regex filters
28+
Use `excludeRegex` to suppress command spam, bot command invocations, or unwanted patterns.
29+
Use `includeRegex` to only publish messages that match a known format.
30+
31+
### 5. Optional thread capture
32+
`includeThreads` can be enabled per channel, but it is off by default because the current target is mostly normal text channels.
33+
34+
## Suggested policies for PowerShell.org
35+
36+
### Announcements
37+
- moderation: `all`
38+
- age: `60`
39+
- threads: `false`
40+
41+
### Help highlights
42+
- moderation: `reaction`
43+
- reaction: `✅`
44+
- age: `1440`
45+
- threads: `false`
46+
47+
### Moderator summaries
48+
- moderation: `prefix`
49+
- prefix: `[publish]`
50+
- age: `60`
51+
- threads: `false`
52+
53+
### Staff-only publisher channel
54+
- moderation: `author-role`
55+
- roles: `Moderator`, `Admin`, `Discord Team`
56+
- age: `60`
57+
- threads: `false`
58+
59+
## Recommended rollout
60+
61+
Start with one low-risk channel such as announcements, verify output, then add one curated help channel using `reaction` mode.
62+
63+
That gives you a public knowledge layer instead of a public transcript of everyone's stream of consciousness.

‎DISCORD_MIRROR_SITE_OWNER_QUICKSTART.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Discord Mirror Quick Start
2+
3+
1. Add the `DISCORD_BOT_TOKEN` secret to the GitHub repository.
4+
2. Update `config/discord-mirror.json` with the real guild ID and channel IDs.
5+
3. Give the Discord bot **View Channel** and **Read Message History** in the selected channels.
6+
4. Push the changes to `main`.
7+
5. Verify the GitHub Actions workflow succeeds.
8+
6. Open `/discord/` and `/discord/search/` on the site.
9+
7. Verify moderation controls are working before announcing the feature publicly.

‎config/discord-mirror.json‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
{
2+
"site": {
3+
"title": "PowerShell.org Discord Archive",
4+
"baseUrl": "https://powershell.org/discord",
5+
"sectionPath": "discord",
6+
"footerText": "Selected Discord content is published to the public web for search and discovery. Attachments and images remain hosted by Discord.",
7+
"searchDescription": "Search approved Discord archive content mirrored from selected PowerShell.org Discord channels."
8+
},
9+
"discord": {
10+
"guildId": "1488875093873397832",
11+
"apiBaseUrl": "https://discord.com/api/v10",
12+
"userAgent": "PowerShellOrgDiscordMirror/5.0"
13+
},
14+
"export": {
15+
"outputContentDir": "content/discord",
16+
"outputStaticDir": "static/discord",
17+
"searchIndexFileName": "search-index.json",
18+
"includeBotMessages": false,
19+
"sanitizeMentions": true,
20+
"maxMessagesPerChannel": 1500,
21+
"defaultMinMessageAgeMinutes": 1440,
22+
"defaultModerationMode": "reaction",
23+
"defaultApprovalReaction": "\u2705",
24+
"defaultApprovalPrefix": "[publish]",
25+
"defaultAuthorRoleNames": [
26+
"Moderator",
27+
"Admin",
28+
"Discord Team"
29+
],
30+
"defaultExcludeRegex": [
31+
"^/",
32+
"^!",
33+
"^\\\\?help"
34+
],
35+
"generatedBy": "tools/discord-mirror/Export-DiscordMirror.ps1"
36+
},
37+
"channels": [
38+
{
39+
"id": "1488875094938746884",
40+
"slug": "announcements",
41+
"title": "Announcements",
42+
"description": "Approved announcement messages mirrored from Discord.",
43+
"enabled": true,
44+
"includeThreads": false,
45+
"maxMessages": 500,
46+
"minMessageAgeMinutes": 60,
47+
"moderationMode": "all",
48+
"approvalReaction": "\u2705",
49+
"approvalPrefix": "[publish]",
50+
"authorRoleNames": [
51+
"Moderator",
52+
"Admin"
53+
],
54+
"excludeRegex": []
55+
},
56+
{
57+
"id": "1489393262191185981",
58+
"slug": "TechTalk-PowerShell",
59+
"title": "TechTalk-PowerShell",
60+
"description": "Curated PowerShell message highlights approved for public publishing.",
61+
"enabled": true,
62+
"includeThreads": false,
63+
"maxMessages": 2000,
64+
"minMessageAgeMinutes": 1440,
65+
"moderationMode": "all",
66+
"approvalReaction": "\u2705",
67+
"approvalPrefix": "[publish]",
68+
"authorRoleNames": [
69+
"Moderator",
70+
"Admin"
71+
],
72+
"excludeRegex": [
73+
"^/",
74+
"^!"
75+
],
76+
"includeRegex": []
77+
}
78+
]
79+
}

‎hugo.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,9 @@ menu:
6060
- name: "Forums"
6161
url: "https://forums.powershell.org"
6262
weight: 60
63+
- name: "Discord Archive"
64+
url: "/discord/"
65+
weight: 62
6366

6467
# Site parameters
6568
params:

‎static/discord/search-index.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
[]

‎static/discord/search.js‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎static/discord/styles.css‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/* Generated by tools/discord-mirror/Export-DiscordMirror.ps1 */

0 commit comments

Comments
 (0)