Skip to content

Commit b015329

Browse files
TimeraaDarkVillagerBas950
authored
feat(docs): add VitePress documentation (#9463)
* feat(docs): add VitePress documentation * feat(docs): switch to npm and add GitHub Pages deployment * fix: add semicolons to method signatures in API docs * fix: add eslint-skip comments to code blocks in documentation * fix: properly format JSON code blocks in documentation * feat(docs): add PR preview deployment for documentation * fix: resolve dead links in documentation * Refactor documentation for consistency and clarity - Updated JSON examples in localization, metadata, multilanguage, and settings guides to ensure consistent formatting and clarity. - Improved TypeScript code snippets across various guides, including presence, slideshow, and structure, for better readability and adherence to coding standards. - Removed unnecessary comments and adjusted spacing for improved visual structure. - Enhanced explanations and examples in the presence class and slideshow sections to provide clearer guidance on usage. * fix: update base path in VitePress config for correct routing * feat: update PR preview comment logic to update existing comments * fix: standardize quotes in deploy-docs.yml for consistency * Update docs/api/utility-functions.md Co-authored-by: Dark_Ville <[email protected]> Signed-off-by: Florian Metz <[email protected]> * Update docs/v1/guide/slideshows.md Co-authored-by: Dark_Ville <[email protected]> Signed-off-by: Florian Metz <[email protected]> * Update docs/v1/guide/settings.md Co-authored-by: Dark_Ville <[email protected]> Signed-off-by: Florian Metz <[email protected]> * Update docs/v1/guide/slideshows.md Co-authored-by: Dark_Ville <[email protected]> Signed-off-by: Florian Metz <[email protected]> * Update docs/v1/guide/settings.md Co-authored-by: Dark_Ville <[email protected]> Signed-off-by: Florian Metz <[email protected]> * Update docs/v1/guide/presence-class.md Co-authored-by: Dark_Ville <[email protected]> Signed-off-by: Florian Metz <[email protected]> * docs: update imageKey documentation to recommend direct URLs * docs: standardize property tables in presence documentation * docs: update all imageKey examples to use direct URLs * docs: update all imageKey examples to use direct URLs * docs: update largeImageKey in setActivity example to use a direct URL * feat: activity forwarding * feat: add forwarding image * docs: improve documentation clarity and usability - Update commenting best practices to be more balanced - Add CLI help command documentation - Add information about using og:description meta tags - Simplify DevTools access instructions - Generalize page source viewing instructions - Update example code to use direct image URLs * docs: remove outdated multilanguage.md file and update references - Removed the outdated multilanguage.md file as it's been replaced by localization.md - Updated references in iframes.md, slideshows.md, and settings.md to point to localization.md instead * chore: remove old multilang * docs: implement Bas950's review comments - Add documentation for browsingTimestamp constant, ActivityType and Assets enums - Update examples to use [presenceData.startTimestamp, presenceData.endTimestamp] = getTimestamps(FromMedia) - Update examples to use imgur links for hardcoded image URLs - Add information about validating activities with --validate flag - Update examples to use destructured data like const { pathname, href } = document.location * docs: update documentation with best practices and correct examples - Update utility-functions.md with proper destructuring examples - Update best-practices.md with improved timestamp handling and document.location destructuring - Update iframes.md and media.md examples to use best practices - Remove mentions of PreMiD application (only extension now) - Update localization.md to use getStrings method correctly - Fix various code examples to follow best practices * docs: remove redundant metadata.md file - Remove docs/v1/api/metadata.md as it's redundant with docs/v1/api/metadata-json.md - metadata-json.md is more comprehensive and user-friendly - This avoids confusion by having only one file documenting the metadata.json structure * docs: update metadata link in API index - Update link from /v1/api/metadata to /v1/api/metadata-json - Fix dead link after removing the redundant metadata.md file * docs: add guidelines page - Add comprehensive guidelines for PreMiD activities - Include rules for websites, metadata, code requirements, and more - Update sidebar to include the new guidelines page * docs: add references to guidelines throughout documentation - Add link to guidelines in first-activity.md for new developers - Add reference to metadata guidelines in metadata.md - Add code guidelines section in presence-class.md - Add warning about button guidelines in presence-class.md * chore: fix eslint * chore: review comments * docs: fix getPageVariable example and update utility functions to use Assets enum * docs: improve getPageVariable example with proper destructuring and type annotations * chore: add forwarding to sidebar * chore: lint * chore: enable search and add special episode formatting * chore: lint * fix: update URL references to use document.location.href instead of document.URL * Add tape recordings for creating and developing activities - Created a new tape for the activity creation process, capturing the command execution and user inputs. - Added a tape for the activity development process, documenting the command and a pause for observation. * fix: update create-activity tape to include user ID input * fix: update description for timestamp setting to clarify functionality * chore: update stuff * fix: browsingTimestamp and ActivityAssets * feat: dep updates, favicon, allowURLOverrides * feat: new presencedata fields * chore: lint * chore: lint --------- Signed-off-by: Florian Metz <[email protected]> Co-authored-by: Dark_Ville <[email protected]> Co-authored-by: Bas950 <[email protected]>
1 parent 93b6920 commit b015329

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+10061
-7
lines changed

‎.github/workflows/deploy-docs.yml‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
# Trigger the workflow on push to main branch
5+
push:
6+
branches:
7+
- main
8+
paths:
9+
- 'docs/**'
10+
# Trigger on pull requests
11+
pull_request:
12+
types: [opened, synchronize, reopened]
13+
paths:
14+
- 'docs/**'
15+
# Allows you to run this workflow manually from the Actions tab
16+
workflow_dispatch:
17+
18+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
19+
permissions:
20+
contents: read
21+
pages: write
22+
id-token: write
23+
pull-requests: write
24+
25+
# Allow only one concurrent deployment
26+
concurrency:
27+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
28+
cancel-in-progress: true
29+
30+
jobs:
31+
# Build job
32+
build:
33+
runs-on: ubuntu-latest
34+
steps:
35+
- name: Checkout
36+
uses: actions/checkout@v4
37+
with:
38+
fetch-depth: 0
39+
40+
- name: Setup Node
41+
uses: actions/setup-node@v4
42+
with:
43+
node-version: 20
44+
cache: npm
45+
cache-dependency-path: docs/package-lock.json
46+
47+
- name: Setup Pages
48+
uses: actions/configure-pages@v4
49+
50+
- name: Install dependencies
51+
run: cd docs && npm ci
52+
53+
- name: Build with VitePress
54+
run: cd docs && npm run build
55+
56+
- name: Upload artifact
57+
uses: actions/upload-pages-artifact@v3
58+
with:
59+
path: docs/.vitepress/dist
60+
name: github-pages
61+
62+
# Deployment job for main branch
63+
deploy-production:
64+
if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
65+
environment:
66+
name: github-pages
67+
url: ${{ steps.deployment.outputs.page_url }}
68+
needs: build
69+
runs-on: ubuntu-latest
70+
steps:
71+
- name: Deploy to GitHub Pages
72+
id: deployment
73+
uses: actions/deploy-pages@v4
74+
75+
# Deployment job for PR previews
76+
deploy-preview:
77+
if: github.event_name == 'pull_request'
78+
environment:
79+
name: preview-pr-${{ github.event.pull_request.number }}
80+
url: ${{ steps.deployment.outputs.page_url }}
81+
needs: build
82+
runs-on: ubuntu-latest
83+
steps:
84+
- name: Deploy to GitHub Pages
85+
id: deployment
86+
uses: actions/deploy-pages@v4
87+
with:
88+
artifact_name: github-pages
89+
90+
- name: Comment on PR
91+
uses: actions/github-script@v7
92+
with:
93+
github-token: ${{ secrets.GITHUB_TOKEN }}
94+
script: |
95+
// Check if we already commented on this PR
96+
const { data: comments } = await github.rest.issues.listComments({
97+
issue_number: context.issue.number,
98+
owner: context.repo.owner,
99+
repo: context.repo.repo,
100+
});
101+
102+
const commentMarker = '## 📝 Documentation Preview';
103+
const existingComment = comments.find(comment => comment.body.includes(commentMarker));
104+
105+
const body = `${commentMarker}\n\n**Your documentation changes are ready for preview!**\n\n🔍 [View Preview](${process.env.DEPLOYMENT_URL})\n\n_This preview will be automatically updated when you push new commits to this PR._`;
106+
107+
if (existingComment) {
108+
// Update existing comment
109+
await github.rest.issues.updateComment({
110+
comment_id: existingComment.id,
111+
owner: context.repo.owner,
112+
repo: context.repo.repo,
113+
body: body
114+
});
115+
console.log(`Updated existing comment ID ${existingComment.id}`);
116+
} else {
117+
// Create new comment
118+
const { data: newComment } = await github.rest.issues.createComment({
119+
issue_number: context.issue.number,
120+
owner: context.repo.owner,
121+
repo: context.repo.repo,
122+
body: body
123+
});
124+
console.log(`Created new comment ID ${newComment.id}`);
125+
}
126+
env:
127+
DEPLOYMENT_URL: ${{ steps.deployment.outputs.page_url }}

‎.github/workflows/vhs.yaml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: VHS
2+
on:
3+
push:
4+
paths:
5+
- 'docs/taps/*.tape'
6+
workflow_dispatch:
7+
permissions:
8+
contents: read
9+
jobs:
10+
vhs:
11+
name: Create VHS
12+
runs-on: ubuntu-latest
13+
if: ${{github.repository=='PreMiD/Activities'}}
14+
permissions:
15+
contents: write
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@v4
19+
20+
- name: Setup Node
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version-file: package.json
24+
cache: npm
25+
26+
- name: Install dependencies
27+
run: npm ci
28+
29+
- uses: charmbracelet/[email protected]
30+
with:
31+
path: docs/tapes/create-activity.tape
32+
33+
- uses: charmbracelet/[email protected]
34+
with:
35+
path: docs/tapes/developing-activity.tape
36+
37+
- uses: stefanzweifel/git-auto-commit-action@v4
38+
env:
39+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
40+
with:
41+
commit_message: 'docs(tapes): Update GIFs'
42+
file_pattern: 'docs/public/tapes/*.gif'

‎@types/premid/index.d.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ declare global {
1313
/** Display the state field - e.g. "Listening to Rick Astley" */
1414
State = 1,
1515
/** Display the details field - e.g. "Listening to Never Gonna Give You Up" */
16-
Details = 2
16+
Details = 2,
1717
}
1818

1919
/**
@@ -426,12 +426,12 @@ declare global {
426426
event: 'reconnect'
427427
}
428428

429-
type PresenceClassEvents =
430-
| PresenceClassSetActivityEvent
431-
| PresenceClassClearActivityEvent
432-
| PresenceClassGetPresenceLetiableEvent
433-
| PresenceClassGetPageVariablesEvent
434-
| PresenceClassReconnectEvent
429+
type PresenceClassEvents
430+
= | PresenceClassSetActivityEvent
431+
| PresenceClassClearActivityEvent
432+
| PresenceClassGetPresenceLetiableEvent
433+
| PresenceClassGetPageVariablesEvent
434+
| PresenceClassReconnectEvent
435435

436436
type ConsoleLogType = 'log' | 'info' | 'warn' | 'error'
437437
interface ConsoleLog<T = unknown> {

‎docs/.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# VitePress build output
2+
.vitepress/dist/
3+
.vitepress/cache/
4+
5+
# Node modules
6+
node_modules/
7+
8+
# Environment variables
9+
.env
10+
.env.local
11+
.env.*.local
12+
13+
# Editor directories and files
14+
.idea/
15+
.vscode/
16+
*.suo
17+
*.ntvs*
18+
*.njsproj
19+
*.sln
20+
*.sw?
21+
22+
# OS specific files
23+
.DS_Store
24+
Thumbs.db

‎docs/.vitepress/config.ts‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
// Define available versions
4+
interface VersionItem {
5+
text: string
6+
link: string
7+
disabled?: boolean
8+
}
9+
10+
const versions: VersionItem[] = [
11+
{ text: 'v1 (Current)', link: '/' },
12+
{ text: 'v2 (Coming Soon)', link: '#', disabled: true },
13+
]
14+
15+
export default defineConfig({
16+
base: '/Activities',
17+
title: 'PreMiD',
18+
description: 'Documentation for developing PreMiD Activities',
19+
head: [['link', { rel: 'icon', href: 'https://cdn.rcd.gg/PreMiD.png', type: 'image/png' }]],
20+
themeConfig: {
21+
search: {
22+
provider: 'local',
23+
},
24+
logo: 'https://cdn.rcd.gg/PreMiD.png',
25+
nav: [
26+
{ text: 'Home', link: '/' },
27+
{ text: 'Guide', link: '/v1/guide/' },
28+
{ text: 'API Reference', link: '/v1/api/' },
29+
{ text: 'Examples', link: '/v1/examples/' },
30+
{
31+
text: versions[0].text,
32+
items: [
33+
...versions,
34+
{
35+
text: 'GitHub Repository',
36+
link: 'https://github.com/PreMiD/Activities',
37+
},
38+
],
39+
},
40+
],
41+
sidebar: {
42+
// v1 Sidebar
43+
'/v1/guide/': [
44+
{
45+
text: 'Getting Started',
46+
items: [
47+
{ text: 'Introduction', link: '/v1/guide/' },
48+
{ text: 'Installation', link: '/v1/guide/installation' },
49+
{ text: 'Creating Your First Activity', link: '/v1/guide/first-activity' },
50+
],
51+
},
52+
{
53+
text: 'Core Concepts',
54+
items: [
55+
{ text: 'Activity Structure', link: '/v1/guide/structure' },
56+
{ text: 'Metadata', link: '/v1/guide/metadata' },
57+
{ text: 'Presence Class', link: '/v1/guide/presence-class' },
58+
{ text: 'Settings', link: '/v1/guide/settings' },
59+
{ text: 'Dependencies', link: '/v1/guide/dependencies' },
60+
{ text: 'Loading Activities', link: '/v1/guide/loading-activities' },
61+
{ text: 'Developer Tools', link: '/v1/guide/developer-tools' },
62+
],
63+
},
64+
{
65+
text: 'Advanced Topics',
66+
items: [
67+
{ text: 'iFrames', link: '/v1/guide/iframes' },
68+
{ text: 'Slideshows', link: '/v1/guide/slideshows' },
69+
{ text: 'Localization', link: '/v1/guide/localization' },
70+
{ text: 'Best Practices', link: '/v1/guide/best-practices' },
71+
{ text: 'Guidelines', link: '/v1/guide/guidelines' },
72+
],
73+
},
74+
{
75+
text: 'Extension Features',
76+
items: [
77+
{ text: 'Activity Forwarding', link: '/activity-forwarding' },
78+
],
79+
},
80+
],
81+
'/v1/api/': [
82+
{
83+
text: 'API Reference',
84+
items: [
85+
{ text: 'Overview', link: '/v1/api/' },
86+
{ text: 'Presence Class', link: '/v1/api/presence-class' },
87+
{ text: 'PresenceData Interface', link: '/v1/api/presence-data' },
88+
{ text: 'metadata.json Structure', link: '/v1/api/metadata-json' },
89+
{ text: 'Slideshow Class', link: '/v1/api/slideshow' },
90+
{ text: 'iFrame Class', link: '/v1/api/iframe' },
91+
{ text: 'Utility Functions', link: '/v1/api/utility-functions' },
92+
],
93+
},
94+
],
95+
'/v1/examples/': [
96+
{
97+
text: 'Examples',
98+
items: [
99+
{ text: 'Basic Activity', link: '/v1/examples/' },
100+
{ text: 'Media Activity', link: '/v1/examples/media' },
101+
{ text: 'Activity with Settings', link: '/v1/examples/settings' },
102+
{ text: 'Activity with iFrames', link: '/v1/examples/iframes' },
103+
{ text: 'Activity with Slideshow', link: '/v1/examples/slideshow' },
104+
],
105+
},
106+
],
107+
108+
// v2 Sidebar (Coming Soon)
109+
'/v2/': [
110+
{
111+
text: 'Coming Soon',
112+
items: [
113+
{ text: 'API Version 2', link: '/v2/' },
114+
],
115+
},
116+
],
117+
},
118+
socialLinks: [
119+
{ icon: 'github', link: 'https://github.com/PreMiD/Activities' },
120+
],
121+
footer: {
122+
message: 'Released under the MPL-2.0 License.',
123+
copyright: 'Copyright © 2018-present Recodive oHG',
124+
},
125+
},
126+
})

0 commit comments

Comments
 (0)