saulteafarmer/castopod
1
0
Fork 0
mirror of https://code.castopod.org/adaures/castopod synced 2025-04-19 04:51:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(api): add available operations based on openapi schema

Browse Source 
use starlight-openapi plugin to generate docs

closes #536
This commit is contained in:
Yassine Doghri 2024-12-26 13:01:53 +00:00
parent 775b302f7c
commit 888d610c2d
22 changed files with 1305 additions and 1054 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.devcontainer/devcontainer.json
View File

@ -62,7 +62,8 @@
"stylelint.vscode-stylelint",
"unifiedjs.vscode-mdx",
"wayou.vscode-todo-highlight",
"yzhang.markdown-all-in-one"
"yzhang.markdown-all-in-one",
"42Crunch.vscode-openapi"
]
}
}

113
docs/astro.config.mjs
View File

@ -1,5 +1,6 @@
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
import starlightOpenAPI from "starlight-openapi";
import tailwind from "@astrojs/tailwind";
@ -122,6 +123,16 @@ export default defineConfig({
gitlab: "https://code.castopod.org/adaures/castopod",
github: "https://github.com/ad-aures/castopod",
},
plugins: [
starlightOpenAPI([
{
base: "en/api",
label: "API reference",
schema: "../modules/Api/Rest/V1/schema.yaml",
collapsed: true,
},
]),
],
sidebar: [
{
label: "Introduction",
@ -193,6 +204,77 @@ export default defineConfig({
},
],
},
{
label: "Plugins",
badge: {
text: "Experimental",
},
items: [
{
label: "Introduction",
link: "/plugins/",
},
{
label: "Creating a plugin",
link: "/plugins/create",
},
{
label: "Reference",
items: [
{
label: "manifest.json",
link: "/plugins/manifest",
},
{
label: "hooks",
link: "/plugins/hooks",
},
],
},
],
},
// TODO: openapi plugin does not handle i18n, manual sidebar workaround
// Add the generated sidebar group to the sidebar.
// ...openAPISidebarGroups,
{
label: "API reference",
translations: {},
items: [
{
label: "Overview",
link: "/api",
},
{
label: "Operations",
items: [
{
label: "Get all podcasts",
link: "/api/operations/get-all-podcasts",
},
{
label: "Get podcast by ID",
link: "/api/operations/get-podcast-by-id",
},
{
label: "Get all episodes",
link: "/api/operations/get-all-episodes",
},
{
label: "Add a new episode",
link: "/api/operations/add-episode",
},
{
label: "Get episode by ID",
link: "/api/operations/get-episode-by-id",
},
{
label: "Publish an episode",
link: "/api/operations/publish-episode",
},
],
},
],
},
{
label: "User guide",
translations: {},
@ -204,6 +286,7 @@ export default defineConfig({
{
label: "Manage your instance",
translations: {},
collapsed: true,
items: [
{
label: "Introduction",
@ -245,6 +328,7 @@ export default defineConfig({
{
label: "Manage your podcasts",
translations: {},
collapsed: true,
items: [
{
label: "Introduction",
@ -285,35 +369,6 @@ export default defineConfig({
},
],
},
{
label: "Plugins",
badge: {
text: "Experimental",
},
items: [
{
label: "Introduction",
link: "/plugins/",
},
{
label: "Creating a plugin",
link: "/plugins/create",
},
{
label: "Reference",
items: [
{
label: "manifest.json",
link: "/plugins/manifest",
},
{
label: "hooks",
link: "/plugins/hooks",
},
],
},
],
},
],
editLink: {
baseUrl: "https://code.castopod.org/adaures/castopod/-/edit/main/docs/",

1
docs/package.json
View File

@ -22,6 +22,7 @@
"cssnano": "^7.0.6",
"postcss-preset-env": "^10.1.2",
"sharp": "^0.33.5",
"starlight-openapi": "^0.9.0",
"tailwindcss": "^3.4.17",
"typescript": "^5.7.2",
"zod": "3.24.1"

249
docs/pnpm-lock.yaml generated
View File

@ -40,6 +40,9 @@ importers:
sharp:
specifier: ^0.33.5
version: 0.33.5
starlight-openapi:
specifier: ^0.9.0
version: 0.9.0(@astrojs/markdown-remark@6.0.1)(@astrojs/starlight@0.30.3(astro@5.1.1(jiti@2.4.2)(rollup@4.29.1)(typescript@5.7.2)(yaml@2.6.1)))(openapi-types@12.1.3)
tailwindcss:
specifier: ^3.4.17
version: 3.4.17
@ -58,6 +61,12 @@ packages:
}
engines: { node: ">=10" }
"@apidevtools/swagger-methods@3.0.2":
resolution:
{
integrity: sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg==,
}
"@astrojs/check@0.9.4":
resolution:
{
@ -162,6 +171,13 @@ packages:
integrity: sha512-GOfvSr5Nqy2z5XiwqTouBBpy5FyI6DEe+/g/Mk5am9SjILN1S5fOEvYK0GuWHg98yS/dobP4m8qyqw/URW35fQ==,
}
"@babel/code-frame@7.26.2":
resolution:
{
integrity: sha512-RJlIHRueQgwWitWgF8OdFYGZX328Ax5BCemNGlqHfplnRT9ESi8JkFlvaVYbS+UubVY6dpv87Fs2u5M29iNFVQ==,
}
engines: { node: ">=6.9.0" }
"@babel/helper-string-parser@7.25.9":
resolution:
{
@ -1090,6 +1106,13 @@ packages:
integrity: sha512-QyZQw03z/v1RltDPPtWxAQsYgmwbDY6CKH/YWubRY4x9UFGuAImwFYPitR2sTB/FBj0Dxf0DftoC9kqGZKWjug==,
}
"@humanwhocodes/momoa@2.0.4":
resolution:
{
integrity: sha512-RE815I4arJFtt+FVeU1Tgp9/Xvecacji8w/V6XtXsWWH/wz/eNkNbhb+ny/+PlVZjV0rxQpRSQKNKE3lcktHEA==,
}
engines: { node: ">=10.10.0" }
"@img/sharp-darwin-arm64@0.33.5":
resolution:
{
@ -1292,6 +1315,12 @@ packages:
integrity: sha512-vNk6aEwybGtawWmy/PzwnGDOjCkLWSD2wqvjGGAgOAwCGWySYXfYoxt00IJkTF+8Lb57DwOb3Aa0o9CApepiYQ==,
}
"@jsdevtools/ono@7.1.3":
resolution:
{
integrity: sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==,
}
"@mdx-js/mdx@3.1.0":
resolution:
{
@ -1511,6 +1540,37 @@ packages:
}
engines: { node: ">=14" }
"@readme/better-ajv-errors@1.6.0":
resolution:
{
integrity: sha512-9gO9rld84Jgu13kcbKRU+WHseNhaVt76wYMeRDGsUGYxwJtI3RmEJ9LY9dZCYQGI8eUZLuxb5qDja0nqklpFjQ==,
}
engines: { node: ">=14" }
peerDependencies:
ajv: 4.11.8 - 8
"@readme/json-schema-ref-parser@1.2.0":
resolution:
{
integrity: sha512-Bt3QVovFSua4QmHa65EHUmh2xS0XJ3rgTEUPH998f4OW4VVJke3BuS16f+kM0ZLOGdvIrzrPRqwihuv5BAjtrA==,
}
"@readme/openapi-parser@2.6.0":
resolution:
{
integrity: sha512-pyFJXezWj9WI1O+gdp95CoxfY+i+Uq3kKk4zXIFuRAZi9YnHpHOpjumWWr67wkmRTw19Hskh9spyY0Iyikf3fA==,
}
engines: { node: ">=18" }
peerDependencies:
openapi-types: ">=7"
"@readme/openapi-schemas@3.1.0":
resolution:
{
integrity: sha512-9FC/6ho8uFa8fV50+FPy/ngWN53jaUu4GRXlAjcxIRrzhltJnpKkBG2Tp0IDraFJeWrOpk84RJ9EMEEYzaI1Bw==,
}
engines: { node: ">=18" }
"@rollup/pluginutils@5.1.4":
resolution:
{
@ -1754,6 +1814,12 @@ packages:
integrity: sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==,
}
"@types/json-schema@7.0.15":
resolution:
{
integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==,
}
"@types/mdast@4.0.4":
resolution:
{
@ -1874,6 +1940,17 @@ packages:
engines: { node: ">=0.4.0" }
hasBin: true
ajv-draft-04@1.0.0:
resolution:
{
integrity: sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==,
}
peerDependencies:
ajv: ^8.5.0
peerDependenciesMeta:
ajv:
optional: true
ajv@8.17.1:
resolution:
{
@ -2070,6 +2147,12 @@ packages:
engines: { node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7 }
hasBin: true
call-me-maybe@1.0.2:
resolution:
{
integrity: sha512-HpX65o1Hnr9HH25ojC1YGs7HCQLq0GCOibSaWER0eNpgJ/Z1MZv2mTc7+xh6WOPxbRVcmgbv4hGU+uSQ/2xFZQ==,
}
camelcase-css@2.0.1:
resolution:
{
@ -2102,6 +2185,13 @@ packages:
integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==,
}
chalk@4.1.2:
resolution:
{
integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==,
}
engines: { node: ">=10" }
chalk@5.4.1:
resolution:
{
@ -2188,6 +2278,13 @@ packages:
}
engines: { node: ">=6" }
code-error-fragment@0.0.230:
resolution:
{
integrity: sha512-cadkfKp6932H8UkhzE/gcUqhRMNf8jHzkAN7+5Myabswaghu4xABTgPHDCjW+dBAJxj/SpkTYokpzDqY4pCzQw==,
}
engines: { node: ">= 4" }
collapse-white-space@2.1.0:
resolution:
{
@ -2861,12 +2958,25 @@ packages:
integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==,
}
grapheme-splitter@1.0.4:
resolution:
{
integrity: sha512-bzh50DW9kTPM00T8y4o8vQg89Di9oLJVLW/KaOGIXJWP/iqCN6WKYkbNOF04vFLJhwcpYUh9ydh/+5vpOqV4YQ==,
}
h3@1.13.0:
resolution:
{
integrity: sha512-vFEAu/yf8UMUcB4s43OaDaigcqpQd14yanmOsn+NcRX3/guSKncyE2rOYhq8RIchgJrPSs/QiIddnTTR1ddiAg==,
}
has-flag@4.0.0:
resolution:
{
integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==,
}
engines: { node: ">=8" }
hasown@2.0.2:
resolution:
{
@ -3204,6 +3314,12 @@ packages:
}
hasBin: true
js-tokens@4.0.0:
resolution:
{
integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==,
}
js-yaml@3.14.1:
resolution:
{
@ -3224,6 +3340,13 @@ packages:
integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==,
}
json-to-ast@2.1.0:
resolution:
{
integrity: sha512-W9Lq347r8tA1DfMvAGn9QNcgYm4Wm7Yc+k8e6vezpMnRT+NHbtlxgNBXRVjXe9YM6eTn6+p/MKOlV/aABJcSnQ==,
}
engines: { node: ">= 4" }
jsonc-parser@2.3.1:
resolution:
{
@ -3236,6 +3359,13 @@ packages:
integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==,
}
jsonpointer@5.0.1:
resolution:
{
integrity: sha512-p/nXbhSEcu3pZRdkW1OfJhpsVtW1gd4Wa1fnQc9YLiTfAjn0312eMKimbdIQzuZl9aa9xUGaRlP9T/CJE/ditQ==,
}
engines: { node: ">=0.10.0" }
kleur@3.0.3:
resolution:
{
@ -3250,6 +3380,13 @@ packages:
}
engines: { node: ">=6" }
leven@3.1.0:
resolution:
{
integrity: sha512-qsda+H8jTaUaN/x5vzW2rzc+8Rw4TAQ/4KjB46IwK5VH+IlVeeeje/EoZRpiXvIqjFgK84QffqPztGI3VBLG1A==,
}
engines: { node: ">=6" }
lilconfig@3.1.3:
resolution:
{
@ -3867,6 +4004,12 @@ packages:
integrity: sha512-dekySTEvCxCj0IgKcA2uUCO/e4ArsqpucDPcX26w9ajx+DvMWLc5eZeJaRQkd7oC/+rwif5gnT900tA34uN9Zw==,
}
openapi-types@12.1.3:
resolution:
{
integrity: sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw==,
}
p-limit@2.3.0:
resolution:
{
@ -4956,6 +5099,16 @@ packages:
integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==,
}
starlight-openapi@0.9.0:
resolution:
{
integrity: sha512-YKsYNqYhWu3VF91z4XB1os4ZXwTsgz1LCZggeK/G6RguV4hcaFH18wHYGtO9icqPR+ZbJyrLAdlAjF3CvGBAWA==,
}
engines: { node: ">=18.17.1" }
peerDependencies:
"@astrojs/markdown-remark": ">=6.0.0"
"@astrojs/starlight": ">=0.30.0"
std-env@3.8.0:
resolution:
{
@ -5052,6 +5205,13 @@ packages:
engines: { node: ">=16 || 14 >=14.17" }
hasBin: true
supports-color@7.2.0:
resolution:
{
integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==,
}
engines: { node: ">=8" }
supports-preserve-symlinks-flag@1.0.0:
resolution:
{
@ -5751,6 +5911,8 @@ packages:
snapshots:
"@alloc/quick-lru@5.2.0": {}
"@apidevtools/swagger-methods@3.0.2": {}
"@astrojs/check@0.9.4(typescript@5.7.2)":
dependencies:
"@astrojs/language-server": 2.15.4(typescript@5.7.2)
@ -5904,6 +6066,12 @@ snapshots:
dependencies:
yaml: 2.6.1
"@babel/code-frame@7.26.2":
dependencies:
"@babel/helper-validator-identifier": 7.25.9
js-tokens: 4.0.0
picocolors: 1.1.1
"@babel/helper-string-parser@7.25.9": {}
"@babel/helper-validator-identifier@7.25.9": {}
@ -6373,6 +6541,8 @@ snapshots:
"@fontsource/rubik@5.1.0": {}
"@humanwhocodes/momoa@2.0.4": {}
"@img/sharp-darwin-arm64@0.33.5":
optionalDependencies:
"@img/sharp-libvips-darwin-arm64": 1.0.4
@ -6474,6 +6644,8 @@ snapshots:
"@jridgewell/resolve-uri": 3.1.2
"@jridgewell/sourcemap-codec": 1.5.0
"@jsdevtools/ono@7.1.3": {}
"@mdx-js/mdx@3.1.0(acorn@8.14.0)":
dependencies:
"@types/estree": 1.0.6
@ -6603,6 +6775,38 @@ snapshots:
"@pkgjs/parseargs@0.11.0":
optional: true
"@readme/better-ajv-errors@1.6.0(ajv@8.17.1)":
dependencies:
"@babel/code-frame": 7.26.2
"@babel/runtime": 7.26.0
"@humanwhocodes/momoa": 2.0.4
ajv: 8.17.1
chalk: 4.1.2
json-to-ast: 2.1.0
jsonpointer: 5.0.1
leven: 3.1.0
"@readme/json-schema-ref-parser@1.2.0":
dependencies:
"@jsdevtools/ono": 7.1.3
"@types/json-schema": 7.0.15
call-me-maybe: 1.0.2
js-yaml: 4.1.0
"@readme/openapi-parser@2.6.0(openapi-types@12.1.3)":
dependencies:
"@apidevtools/swagger-methods": 3.0.2
"@jsdevtools/ono": 7.1.3
"@readme/better-ajv-errors": 1.6.0(ajv@8.17.1)
"@readme/json-schema-ref-parser": 1.2.0
"@readme/openapi-schemas": 3.1.0
ajv: 8.17.1
ajv-draft-04: 1.0.0(ajv@8.17.1)
call-me-maybe: 1.0.2
openapi-types: 12.1.3
"@readme/openapi-schemas@3.1.0": {}
"@rollup/pluginutils@5.1.4(rollup@4.29.1)":
dependencies:
"@types/estree": 1.0.6
@ -6719,6 +6923,8 @@ snapshots:
"@types/js-yaml@4.0.9": {}
"@types/json-schema@7.0.15": {}
"@types/mdast@4.0.4":
dependencies:
"@types/unist": 3.0.3
@ -6799,6 +7005,10 @@ snapshots:
acorn@8.14.0: {}
ajv-draft-04@1.0.0(ajv@8.17.1):
optionalDependencies:
ajv: 8.17.1
ajv@8.17.1:
dependencies:
fast-deep-equal: 3.1.3
@ -6999,6 +7209,8 @@ snapshots:
node-releases: 2.0.19
update-browserslist-db: 1.1.1(browserslist@4.24.3)
call-me-maybe@1.0.2: {}
camelcase-css@2.0.1: {}
camelcase@8.0.0: {}
@ -7014,6 +7226,11 @@ snapshots:
ccount@2.0.1: {}
chalk@4.1.2:
dependencies:
ansi-styles: 4.3.0
supports-color: 7.2.0
chalk@5.4.1: {}
character-entities-html4@2.1.0: {}
@ -7062,6 +7279,8 @@ snapshots:
clsx@2.1.1: {}
code-error-fragment@0.0.230: {}
collapse-white-space@2.1.0: {}
color-convert@2.0.1:
@ -7485,6 +7704,8 @@ snapshots:
graceful-fs@4.2.11: {}
grapheme-splitter@1.0.4: {}
h3@1.13.0:
dependencies:
cookie-es: 1.2.2
@ -7498,6 +7719,8 @@ snapshots:
uncrypto: 0.1.3
unenv: 1.10.0
has-flag@4.0.0: {}
hasown@2.0.2:
dependencies:
function-bind: 1.1.2
@ -7776,6 +7999,8 @@ snapshots:
jiti@2.4.2: {}
js-tokens@4.0.0: {}
js-yaml@3.14.1:
dependencies:
argparse: 1.0.10
@ -7787,14 +8012,23 @@ snapshots:
json-schema-traverse@1.0.0: {}
json-to-ast@2.1.0:
dependencies:
code-error-fragment: 0.0.230
grapheme-splitter: 1.0.4
jsonc-parser@2.3.1: {}
jsonc-parser@3.3.1: {}
jsonpointer@5.0.1: {}
kleur@3.0.3: {}
kleur@4.1.5: {}
leven@3.1.0: {}
lilconfig@3.1.3: {}
lines-and-columns@1.2.4: {}
@ -8405,6 +8639,8 @@ snapshots:
regex: 5.0.2
regex-recursion: 5.0.0
openapi-types@12.1.3: {}
p-limit@2.3.0:
dependencies:
p-try: 2.2.0
@ -9212,6 +9448,15 @@ snapshots:
sprintf-js@1.0.3: {}
starlight-openapi@0.9.0(@astrojs/markdown-remark@6.0.1)(@astrojs/starlight@0.30.3(astro@5.1.1(jiti@2.4.2)(rollup@4.29.1)(typescript@5.7.2)(yaml@2.6.1)))(openapi-types@12.1.3):
dependencies:
"@astrojs/markdown-remark": 6.0.1
"@astrojs/starlight": 0.30.3(astro@5.1.1(jiti@2.4.2)(rollup@4.29.1)(typescript@5.7.2)(yaml@2.6.1))
"@readme/openapi-parser": 2.6.0(openapi-types@12.1.3)
github-slugger: 2.0.0
transitivePeerDependencies:
- openapi-types
std-env@3.8.0: {}
stream-replace-string@2.0.0: {}
@ -9275,6 +9520,10 @@ snapshots:
pirates: 4.0.6
ts-interface-checker: 0.1.13
supports-color@7.2.0:
dependencies:
has-flag: 4.0.0
supports-preserve-symlinks-flag@1.0.0: {}
svgo@3.3.2:

82
docs/src/content/docs/en/getting-started/create-episode.mdx
View File

@ -2,33 +2,37 @@
title: Create your first episode
---
To add an episode to your podcast, choose Podcasts -> All podcasts from your instance management left hand sidebar.
Then choose Podcast dashboard and press the Add an episode button in the upper right hand corner and fill out the
To add an episode to your podcast, choose Podcasts -> All podcasts from your
instance management left hand sidebar. Then choose Podcast dashboard and press
the Add an episode button in the upper right hand corner and fill out the
following fields.
## Episode Info
### Audio file
Press the `Choose File` button to select the audio file to upload to Castopod. The audio file must be an mp3 or m4a
file and cannot be larger than 512 megabytes.
Press the `Choose File` button to select the audio file to upload to Castopod.
The audio file must be an mp3 or m4a file and cannot be larger than 512
megabytes.
### Episode cover
You can optionally add a different podcast cover / artwork. Press `Choose File` and select an image from your computer
that must be at least 1400px wide and tall and no larger than 3000px wide and tall. If you do not choose an
episode cover, your default podcast artwork will be used.
You can optionally add a different podcast cover / artwork. Press `Choose File`
and select an image from your computer that must be at least 1400px wide and
tall and no larger than 3000px wide and tall. If you do not choose an episode
cover, your default podcast artwork will be used.
### Title
Enter the name for your new episode. Do not add the season or episode number in the **Title** field. Choose a clear
and concise episode name to help your listeners.
Enter the name for your new episode. Do not add the season or episode number in
the **Title** field. Choose a clear and concise episode name to help your
listeners.
### Permalink
The permalink is the link to the public episode page. This will be automatically filled out based on the title
you entered above. If you wish to have a different permalink, press the edit button to the right of the
displayed permalink.
The permalink is the link to the public episode page. This will be automatically
filled out based on the title you entered above. If you wish to have a different
permalink, press the edit button to the right of the displayed permalink.
### Season and Episode
@ -36,46 +40,54 @@ You can optionally add a season and / or episode number to your episode.
## Show Notes
Describe your episode in detail. You can use up to 4000 characters, and you can use Markdown to style your show
notes. You can expand the text box by pressing and holding the bottom right corner of the text box.
Describe your episode in detail. You can use up to 4000 characters, and you can
use Markdown to style your show notes. You can expand the text box by pressing
and holding the bottom right corner of the text box.
When your show notes are complete, press `Preview` to view how your show notes will be displayed.
When your show notes are complete, press `Preview` to view how your show notes
will be displayed.
## Additional Files
### Transcripts
You can add a transcript to your episode by choosing a file in SRT or VTT format to upload. Transcripts will be
shown in a tab on the episode page and some podcast apps such as Apple Podcasts can display the transcript.
Transcripts help users who may have a hearing disability and can also help with search engine optimization.
You can add a transcript to your episode by choosing a file in SRT or VTT format
to upload. Transcripts will be shown in a tab on the episode page and some
podcast apps such as Apple Podcasts can display the transcript.
Transcripts help users who may have a hearing disability and can also help with
search engine optimization.
### Chapters
You can optionally upload a chapters file in JSON format. To learn more about chapters and for an example of the
correct format, visit the [Podcast Namespace](https://github.com/Podcastindex-org/podcast-namespace/blob/main/chapters/jsonChapters.md).
You can optionally upload a chapters file in JSON format. To learn more about
chapters and for an example of the correct format, visit the
[Podcast Namespace](https://github.com/Podcastindex-org/podcast-namespace/blob/main/chapters/jsonChapters.md).
!!! note
Not all podcast players natively support chapters in JSON format. More modern players, such as Fountain and
Apple Podcasts, do support chapters in JSON format.
!!! note Not all podcast players natively support chapters in JSON format. More
modern players, such as Fountain and Apple Podcasts, do support chapters in JSON
format.
## Publish your episode
When complete, press the `Create episode` button at the bottom of the page. You will be automatically directed to
the next step to publish your episode. Your episode is in draft mode and is not yet published. You can preview
how your episode will look when published or publish your episode. To publish your episode, press the `Publish` button
in the upper right hand corner.
When complete, press the `Create episode` button at the bottom of the page. You
will be automatically directed to the next step to publish your episode. Your
episode is in draft mode and is not yet published. You can preview how your
episode will look when published or publish your episode. To publish your
episode, press the `Publish` button in the upper right hand corner.
### Create your announcement post
After pressing `Publish` you will be directed to the next page to draft your announcement post. Write your message
in the text box provided. This will be the message broadcast to the Fediverse and published on your podcast's home
page.
After pressing `Publish` you will be directed to the next page to draft your
announcement post. Write your message in the text box provided. This will be the
message broadcast to the Fediverse and published on your podcast's home page.
### Publication date
Choose `Now` or `Schedule` to publish your episode. If you choose `Now`, your episode will be live. Or you can
schedule the day and time to publish your episode by choosing the `Schedule` radio button and choosing the day and
time. Press `Publish` to finish.
Choose `Now` or `Schedule` to publish your episode. If you choose `Now`, your
episode will be live. Or you can schedule the day and time to publish your
episode by choosing the `Schedule` radio button and choosing the day and time.
Press `Publish` to finish.
Your RSS feed will be automatically updated with your episode information and listeners who subscribe will be
notified of a new episode. Congratulations on publishing your first episode!
Your RSS feed will be automatically updated with your episode information and
listeners who subscribe will be notified of a new episode. Congratulations on
publishing your first episode!

89
docs/src/content/docs/en/getting-started/create-podcast.mdx
View File

@ -4,15 +4,16 @@ title: Create your first podcast
import { Aside } from "@astrojs/starlight/components";
From the left hand navigation sidebar, press the `+` sign to the right of Podcasts to create your first podcast.
From the left hand navigation sidebar, press the `+` sign to the right of
Podcasts to create your first podcast.
## Podcast Identity
### Podcast Cover
To upload your podcast cover art, press the `Choose File` button and choose your cover art from your computer. The
cover art needs to be in JPG or PNG format and a minimum of 1400px wide and tall with a maximum of 3000px wide and
tall.
To upload your podcast cover art, press the `Choose File` button and choose your
cover art from your computer. The cover art needs to be in JPG or PNG format and
a minimum of 1400px wide and tall with a maximum of 3000px wide and tall.
### Title
@ -20,13 +21,15 @@ Enter the name of your podcast in the **Title** field.
### Description
Describe what your podcast is about. You can use Markdown to style the text and you can resize the text box by
pressing and holding the bottom right hand corner of the text box.
Describe what your podcast is about. You can use Markdown to style the text and
you can resize the text box by pressing and holding the bottom right hand corner
of the text box.
### Type
Choose how your listeners should listen to your podcast. **Episodic** lets listeners know they can consume your podcast
in any order, such as an interview podcast. Choose **Serial** if your episodes are meant to be listened to in
Choose how your listeners should listen to your podcast. **Episodic** lets
listeners know they can consume your podcast in any order, such as an interview
podcast. Choose **Serial** if your episodes are meant to be listened to in
sequential order.
### Medium
@ -34,8 +37,10 @@ sequential order.
Choose the type of audio for your podcast:
- **Podcast**: a standard podcast.
- **Music**: A feed of music organized into an "album" with each item a song within the album.
- **Audiobook**: A specific type of audio with one item per feed, or where items represent chapters within a book.
- **Music**: A feed of music organized into an "album" with each item a song
within the album.
- **Audiobook**: A specific type of audio with one item per feed, or where items
represent chapters within a book.
## Classification
@ -45,7 +50,8 @@ From the dropdown menu, choose which language is spoken in your podcast.
### Category
Choose the category that represents your podcast, such as Arts, Comedy, Sports, Technology, etc.
Choose the category that represents your podcast, such as Arts, Comedy, Sports,
Technology, etc.
### Other categories (optional)
@ -53,21 +59,25 @@ You can choose a second category in addition to the main category you set up.
### Parental advisory
Choose if your podcast has explicit content or swearing or choose Clean if your podcast is suitable for everyone. You
can also choose to leave this category as undefined. When [creating a new episode](../podcast/episodes),
you will also have the opportunity to choose clean, explicit, or undefined on a per episode basis.
Choose if your podcast has explicit content or swearing or choose Clean if your
podcast is suitable for everyone. You can also choose to leave this category as
undefined. When [creating a new episode](../podcast/episodes), you will also
have the opportunity to choose clean, explicit, or undefined on a per episode
basis.
## Author
### Owner name and email
Enter the owner name and email in the provided fields. This is only visible in the RSS feed and is used by other
podcasting platforms to verify your ownership of your podcast. You can choose to remove the owner email
from the public RSS feed by using the provided toggle.
Enter the owner name and email in the provided fields. This is only visible in
the RSS feed and is used by other podcasting platforms to verify your ownership
of your podcast. You can choose to remove the owner email from the public RSS
feed by using the provided toggle.
### Publisher
If your podcast is part of a podcast network or is produced by a company, enter the publisher here.
If your podcast is part of a podcast network or is produced by a company, enter
the publisher here.
### Copyright
@ -75,40 +85,47 @@ You can optionally add the copyright holder in this field.
### Fediverse identity
Enter the handle (or nickname) for your podcast. This will allow people on Mastodon and other Fediverse services
to follow your podcast. Your handle will be shown as @yourdomain.com@handle on the Fediverse.
Enter the handle (or nickname) for your podcast. This will allow people on
Mastodon and other Fediverse services to follow your podcast. Your handle will
be shown as @yourdomain.com@handle on the Fediverse.
To learn more about Fediverse integration, visit the [Fediverse documentation page](../instance/fediverse).
To learn more about Fediverse integration, visit the
[Fediverse documentation page](../instance/fediverse).
### Podcast banner
Upload a banner image to be displayed at the top of your podcast's home page. The banner must have a 3:1 ration and
be at least 1500px wide.
Upload a banner image to be displayed at the top of your podcast's home page.
The banner must have a 3:1 ration and be at least 1500px wide.
### Premium
Toggle this setting to set all episodes by default as premium. When creating an episode, it will default to premium,
and you can still choose to make some episodes, trailers, or bonus content as free and public.
Toggle this setting to set all episodes by default as premium. When creating an
episode, it will default to premium, and you can still choose to make some
episodes, trailers, or bonus content as free and public.
## Open Podcast Prefix Project (OP3)
The [Open Podcast Prefix Project](https://op3.dev) is an open source and trusted third party analytics service. If
you toggle this to enabled, you will be able to view analytics for your podcast over time including the number of
listens over time, episode comparison charts, and more.
The [Open Podcast Prefix Project](https://op3.dev) is an open source and trusted
third party analytics service. If you toggle this to enabled, you will be able
to view analytics for your podcast over time including the number of listens
over time, episode comparison charts, and more.
## Location
You can optionally add a real or fictitious location name in this field. When
[creating a new episode](../podcast/episodes) you also can add a location to an individual episode.
[creating a new episode](../podcast/episodes) you also can add a location to an
individual episode.
## Advanced Parameters
You can optionally toggle the following settings:
- **Prevent podcast from being copied**: this locks your podcast and does not allow other podcast platforms to import
your podcast. If you decide in the future to migrate away from Castopod to a new platform, this toggle will need to be
unchecked.
- **Podcast should be hidden from public catalogues**: If toggled, a best effort is made to hide the entire podcast from
appearing in Apple Podcasts, YouTube Music, and any other third party podcast apps. (Not guaranteed)
- **Podcast will not be having new episodes**: If your podcast comes to an end, you can toggle this to let listeners
know there will not be new episodes.
- **Prevent podcast from being copied**: this locks your podcast and does not
allow other podcast platforms to import your podcast. If you decide in the
future to migrate away from Castopod to a new platform, this toggle will need
to be unchecked.
- **Podcast should be hidden from public catalogues**: If toggled, a best effort
is made to hide the entire podcast from appearing in Apple Podcasts, YouTube
Music, and any other third party podcast apps. (Not guaranteed)
- **Podcast will not be having new episodes**: If your podcast comes to an end,
you can toggle this to let listeners know there will not be new episodes.

35
docs/src/content/docs/en/user-guide/instance/fediverse.mdx
View File

@ -6,30 +6,35 @@ title: Fediverse
Wikipedia defines the Fediverse as:
> The fediverse is a collection of social networking services that can communicate with each other using a common
> protocol, ActivityPub. Users of different websites can send and receive status updates, multimedia files and other
> data across the network.
> The fediverse is a collection of social networking services that can
> communicate with each other using a common protocol, ActivityPub. Users of
> different websites can send and receive status updates, multimedia files and
> other data across the network.
Your podcast is connected to the Fediverse and, for example, Mastodon users can subscribe to your handle and will
receive a message every time your podcast publishes a new episode. You can also broadcast messages to your followers
on the Fediverse from your [home page](../website#home). Mastodon users can like and share your posts.
Your podcast is connected to the Fediverse and, for example, Mastodon users can
subscribe to your handle and will receive a message every time your podcast
publishes a new episode. You can also broadcast messages to your followers on
the Fediverse from your [home page](../website#home). Mastodon users can like
and share your posts.
## Manage Fediverse Blocks
You can block a Fediverse user or an entire domain to help stop harassment or spam.
You can block a Fediverse user or an entire domain to help stop harassment or
spam.
### Blocked Accounts
To block a specific Fediverse user, enter the user's handle in the **Account Handle** text box. It should be in
the format of `@user@domain.com`. Press `Block` to block the user from following your podcast.
To block a specific Fediverse user, enter the user's handle in the **Account
Handle** text box. It should be in the format of `@user@domain.com`. Press
`Block` to block the user from following your podcast.
A list of all blocked accounts is shown below the **Account Handle** text box. You can choose to unblock a user
by pressing the `Unblock` button.
A list of all blocked accounts is shown below the **Account Handle** text box.
You can choose to unblock a user by pressing the `Unblock` button.
### Blocked Domains
To block an entire domain, enter the domain name such as `www.example.com` in the **Domain Name** field and press
`Block`.
To block an entire domain, enter the domain name such as `www.example.com` in
the **Domain Name** field and press `Block`.
A list of all blocked domains is shown below the **Domain Name** text box. You can choose to unblock a domain
by pressing the `Unblock` button.
A list of all blocked domains is shown below the **Domain Name** text box. You
can choose to unblock a domain by pressing the `Unblock` button.

12
docs/src/content/docs/en/user-guide/instance/index.mdx
View File

@ -6,15 +6,17 @@ import { LinkCard, CardGrid } from "@astrojs/starlight/components";
## What is an instance?
Your podcast is hosted on your sever and connected to the [Fediverse](fediverse) in what is called an _instance_.
Your instance can manage multiple podcasts, people and users, and host additional pages found on all of your podcasts.
Your podcast is hosted on your sever and connected to the [Fediverse](fediverse)
in what is called an _instance_. Your instance can manage multiple podcasts,
people and users, and host additional pages found on all of your podcasts.
Managing your instance, including podcasts, people, and users is separate from the settings for each
individual podcast.
Managing your instance, including podcasts, people, and users is separate from
the settings for each individual podcast.
## Ready to get started?
Learn more about adding podcasts, users, and more by clicking one of the links below.
Learn more about adding podcasts, users, and more by clicking one of the links
below.
<CardGrid>
<LinkCard title="Create or import a podcast" href="podcast" />

19
docs/src/content/docs/en/user-guide/instance/pages.mdx
View File

@ -4,8 +4,8 @@ title: Pages
## Add Pages
You can add static pages linked from your podcast's home page. From the left hand navigation, choose the `+` sign or
click `Pages` -> `New Page`.
You can add static pages linked from your podcast's home page. From the left
hand navigation, choose the `+` sign or click `Pages` -> `New Page`.
### Title
@ -13,16 +13,19 @@ In the **Title** text box, enter the name for the page you are adding.
### Permalink
In the `Permalink` text box, enter the permalink if you want it different than the title.
In the `Permalink` text box, enter the permalink if you want it different than
the title.
### Content
You can add your page content in the **Content** text box. You can use Markdown to style your text.
You can add your page content in the **Content** text box. You can use Markdown
to style your text.
When finished, press the `Create page` button. You can view your page from your podcast's home page. It will be
linked in the right hand side bar navigation.
When finished, press the `Create page` button. You can view your page from your
podcast's home page. It will be linked in the right hand side bar navigation.
## Delete or Edit a Page
After adding a page, you can delete the page or edit it by choosing `Pages` -> `All Pages` from the instance
navigation sidebar on the left. Press the corresponding button to view the page, edit it, or delete it.
After adding a page, you can delete the page or edit it by choosing `Pages` ->
`All Pages` from the instance navigation sidebar on the left. Press the
corresponding button to view the page, edit it, or delete it.

27
docs/src/content/docs/en/user-guide/instance/persons.mdx
View File

@ -2,21 +2,24 @@
title: Manage Podcast contributors
---
The **Persons** section allows you to add podcast contributors. It is needed in the Podcast section to assign
roles and is also used on the **Credits** page linked from your podcast's homepage.
The **Persons** section allows you to add podcast contributors. It is needed in
the Podcast section to assign roles and is also used on the **Credits** page
linked from your podcast's homepage.
From the left hand navigation, press `Persons` to expand the menu. To view a list of all people that have been
added to Castopod, press `All Persons`.
From the left hand navigation, press `Persons` to expand the menu. To view a
list of all people that have been added to Castopod, press `All Persons`.
## Add a person
To add a person, press `New Person` from the left hand sidebar or press `Create a person` from the upper right hand
corner of the **All Persons** page and fill out the following fields:
To add a person, press `New Person` from the left hand sidebar or press
`Create a person` from the upper right hand corner of the **All Persons** page
and fill out the following fields:
- **Avatar**: You can optionally add a picture or avatar of the person. Press `Choose File` and upload a picture
from your computer. It must be at least 400px wide and tall.
- **Avatar**: You can optionally add a picture or avatar of the person. Press
`Choose File` and upload a picture from your computer. It must be at least
400px wide and tall.
- **Full Name**: Enter the name as you want it displayed on your website.
- **Unique Name**: Enter a unique username for the person you are adding. This will be displayed in the Podcasts
secton when assigning this person a role.
- **Information URL**: Enter a URL for the person's homepage, profile, or social media account to be linked from the
[Credits page](../website/credits).
- **Unique Name**: Enter a unique username for the person you are adding. This
will be displayed in the Podcasts secton when assigning this person a role.
- **Information URL**: Enter a URL for the person's homepage, profile, or social
media account to be linked from the [Credits page](../website/credits).

128
docs/src/content/docs/en/user-guide/instance/podcast.mdx
View File

@ -2,19 +2,21 @@
title: Create or import a podcast
---
You can create a new podcast or import an existing podcast into Castopod in the Podcasts section. If you are adding
a second podcast to Castopod, see the [Home page documentation](../website#home-page) for how that will change your
You can create a new podcast or import an existing podcast into Castopod in the
Podcasts section. If you are adding a second podcast to Castopod, see the
[Home page documentation](../website#home-page) for how that will change your
home page.
From the left hand navigation sidebar, press the `+` sign to the right of Podcasts to create your first podcast.
From the left hand navigation sidebar, press the `+` sign to the right of
Podcasts to create your first podcast.
## Podcast Identity
### Podcast Cover
To upload your podcast cover art, press the `Choose File` button and choose your cover art from your computer. The
cover art needs to be in JPG or PNG format and a minimum of 1400px wide and tall with a maximum of 3000px wide and
tall.
To upload your podcast cover art, press the `Choose File` button and choose your
cover art from your computer. The cover art needs to be in JPG or PNG format and
a minimum of 1400px wide and tall with a maximum of 3000px wide and tall.
### Title
@ -22,13 +24,15 @@ Enter the name of your podcast in the **Title** field.
### Description
Describe what your podcast is about. You can use Markdown to style the text and you can resize the text box by
pressing and holding the bottom right hand corner of the text box.
Describe what your podcast is about. You can use Markdown to style the text and
you can resize the text box by pressing and holding the bottom right hand corner
of the text box.
### Type
Choose how your listeners should listen to your podcast. **Episodic** lets listeners know they can consume your podcast
in any order, such as an interview podcast. Choose **Serial** if your episodes are meant to be listened to in
Choose how your listeners should listen to your podcast. **Episodic** lets
listeners know they can consume your podcast in any order, such as an interview
podcast. Choose **Serial** if your episodes are meant to be listened to in
sequential order.
### Medium
@ -36,8 +40,10 @@ sequential order.
Choose the type of audio for your podcast:
- **Podcast**: a standard podcast.
- **Music**: A feed of music organized into an "album" with each item a song within the album.
- **Audiobook**: A specific type of audio with one item per feed, or where items represent chapters within a book.
- **Music**: A feed of music organized into an "album" with each item a song
within the album.
- **Audiobook**: A specific type of audio with one item per feed, or where items
represent chapters within a book.
## Classification
@ -47,7 +53,8 @@ From the dropdown menu, choose which language is spoken in your podcast.
### Category
Choose the category that represents your podcast, such as Arts, Comedy, Technology, etc.
Choose the category that represents your podcast, such as Arts, Comedy,
Technology, etc.
### Other categories (optional)
@ -55,21 +62,25 @@ You can choose a second category in addition to the main category you set up.
### Parental advisory
Choose if your podcast has explicit content or swearing or choose Clean if your podcast is suitable for everyone. You
can also choose to leave this category as undefined. When [creating a new episode](../podcast/episodes),
you will also have the opportunity to choose clean, explicit, or undefined on a per episode basis.
Choose if your podcast has explicit content or swearing or choose Clean if your
podcast is suitable for everyone. You can also choose to leave this category as
undefined. When [creating a new episode](../podcast/episodes), you will also
have the opportunity to choose clean, explicit, or undefined on a per episode
basis.
## Author
### Owner name and email
Enter the owner name and email in the provided fields. This is only visible in the RSS feed and is used by other
podcasting platforms to verify your ownership of your podcast. You can choose to remove the owner email
from the public RSS feed by using the provided toggle.
Enter the owner name and email in the provided fields. This is only visible in
the RSS feed and is used by other podcasting platforms to verify your ownership
of your podcast. You can choose to remove the owner email from the public RSS
feed by using the provided toggle.
### Publisher
If your podcast is part of a podcast network or is produced by a company, enter the publisher here.
If your podcast is part of a podcast network or is produced by a company, enter
the publisher here.
### Copyright
@ -77,69 +88,82 @@ You can optionally add the copyright holder in this field.
### Fediverse identity
Enter the handle (or nickname) for your podcast. This will allow people on Mastodon and other Fediverse services
to follow your podcast. Your handle will be shown as @yourdomain.com@handle on the Fediverse.
Enter the handle (or nickname) for your podcast. This will allow people on
Mastodon and other Fediverse services to follow your podcast. Your handle will
be shown as @yourdomain.com@handle on the Fediverse.
To learn more about Fediverse integration, visit the [Fediverse documentation page](../instance/fediverse).
To learn more about Fediverse integration, visit the
[Fediverse documentation page](../instance/fediverse).
### Podcast banner
Upload a banner image to be displayed at the top of your podcast's home page. The banner must have a 3:1 ration and
be at least 1500px wide.
Upload a banner image to be displayed at the top of your podcast's home page.
The banner must have a 3:1 ration and be at least 1500px wide.
### Premium
Toggle this setting to set all episodes by default as premium. When creating an episode, it will default to premium,
and you can still choose to make some episodes, trailers, or bonus content as free and public.
Toggle this setting to set all episodes by default as premium. When creating an
episode, it will default to premium, and you can still choose to make some
episodes, trailers, or bonus content as free and public.
## Open Podcast Prefix Project (OP3)
The [Open Podcast Prefix Project](https://op3.dev) is an open source and trusted third party analytics service. If
you toggle this to enabled, you will be able to view analytics for your podcast over time including the number of
listens over time, episode comparison charts, and more.
The [Open Podcast Prefix Project](https://op3.dev) is an open source and trusted
third party analytics service. If you toggle this to enabled, you will be able
to view analytics for your podcast over time including the number of listens
over time, episode comparison charts, and more.
## Location
You can optionally add a real or fictitious location name in this field. When
[creating a new episode](../podcast/episodes) you also can add a location to an individual episode.
[creating a new episode](../podcast/episodes) you also can add a location to an
individual episode.
## Advanced Parameters
You can optinally toggle the following settings:
- **Prevent podcast from being copied**: this locks your podcast and does not allow other podcast platforms to import
your podcast. If you decide in the future to migrate away from Castopod to a new platform, this toggle will need to be
unchecked.
- **Podcast should be hidden from public catalogues**: If toggled, a best effort is made to hide the entire podcast from
appearing in Apple Podcasts, YouTube Music, and any other third party podcast apps. (Not guaranteed)
- **Podcast will not be having new episodes**: If your podcast comes to an end, you can toggle this to let listeners
know there will not be new episodes.
- **Prevent podcast from being copied**: this locks your podcast and does not
allow other podcast platforms to import your podcast. If you decide in the
future to migrate away from Castopod to a new platform, this toggle will need
to be unchecked.
- **Podcast should be hidden from public catalogues**: If toggled, a best effort
is made to hide the entire podcast from appearing in Apple Podcasts, YouTube
Music, and any other third party podcast apps. (Not guaranteed)
- **Podcast will not be having new episodes**: If your podcast comes to an end,
you can toggle this to let listeners know there will not be new episodes.
## Import an existing podcast
When importing a podcast, make sure you own the rights for this podcast before importing it.
Copying and broadcasting a podcast without the proper rights is piracy and is liable to prosecution.
When importing a podcast, make sure you own the rights for this podcast before
importing it. Copying and broadcasting a podcast without the proper rights is
piracy and is liable to prosecution.
### Import the podcast
To import a podcast, enter the podcast's **Feed URL**. The feed must be in XML or RSS format. You may want to validate
the feed to make sure there are no errors in the RSS or XML feed prior to importing as errors may cause the import
to fail. One popular feed validator is [Cast Feed Validator](https://www.castfeedvalidator.com) from
Blubrry Podcasting.
To import a podcast, enter the podcast's **Feed URL**. The feed must be in XML
or RSS format. You may want to validate the feed to make sure there are no
errors in the RSS or XML feed prior to importing as errors may cause the import
to fail. One popular feed validator is
[Cast Feed Validator](https://www.castfeedvalidator.com) from Blubrry
Podcasting.
### Podcast information
Enter the handle for your podcast. This will be part of the URL for others to interact with your podcast on the
Fediverse. It will be yourdomain.com@nameofyourpodcast.
Enter the handle for your podcast. This will be part of the URL for others to
interact with your podcast on the Fediverse. It will be
yourdomain.com@nameofyourpodcast.
Choose the language your podcast is recorded in from the drop down box.
Lastly, choose the Category of your podcast, such as Sports, Technology, Arts, etc.
Lastly, choose the Category of your podcast, such as Sports, Technology, Arts,
etc.
When complete, click Add import to queue. You will then be redirected to a Podcast imports page to view the status
of the import. You can refresh the page to see the status of the import including the import duration and how many
When complete, click Add import to queue. You will then be redirected to a
Podcast imports page to view the status of the import. You can refresh the page
to see the status of the import including the import duration and how many
episodes were imported when complete.
!!! note
If your import times out, check your `max_execution_time` in your `PHP.ini` file. You may need to increase it
from 30 seconds (the default) to add more time, such as 300 seconds (5 minutes) for larger podcasts.
!!! note If your import times out, check your `max_execution_time` in your
`PHP.ini` file. You may need to increase it from 30 seconds (the default) to add
more time, such as 300 seconds (5 minutes) for larger podcasts.

22
docs/src/content/docs/en/user-guide/instance/settings.mdx
View File

@ -2,7 +2,8 @@
title: Settings
---
To change or update the settings for your instance, choose `Settings` from the left hand navigation.
To change or update the settings for your instance, choose `Settings` from the
left hand navigation.
## General settings
@ -18,21 +19,26 @@ Update description of your instance in the `Site description` text box.
#### Site icon
You can upload a site icon, also known as a favicon, by pressing `Choose file`. Site icons are what you see
on your browser tabs, bookmarks, and shortcuts on mobile devices. The image must be at least 500px tall and wide.
You can upload a site icon, also known as a favicon, by pressing `Choose file`.
Site icons are what you see on your browser tabs, bookmarks, and shortcuts on
mobile devices. The image must be at least 500px tall and wide.
### Images
If you come across broken or missing images on your site, press `Regenerate images`. This process may take time.
If you come across broken or missing images on your site, press
`Regenerate images`. This process may take time.
### Housekeeping
You can run various tasks for your instance:
- **Reset counts**: This will reset and recalculate counts for followers, posts, and comments.
- **Rename episode files**: This option renames all episodes files to a random name. If one of your private
episodes leaks, toggle this setting to effectively hide the episode.
- **Clear all cache**: This option will flush the Redis cache or writable / cache files.
- **Reset counts**: This will reset and recalculate counts for followers, posts,
and comments.
- **Rename episode files**: This option renames all episodes files to a random
name. If one of your private episodes leaks, toggle this setting to
effectively hide the episode.
- **Clear all cache**: This option will flush the Redis cache or writable /
cache files.
## Theme

20
docs/src/content/docs/en/user-guide/instance/users.mdx
View File

@ -2,15 +2,19 @@
title: Users
---
Roles and permissions in Castopod are defined in two ways, **Instance** users and
[**Podcast**. contributors](../podcast/contributors). For a detailed list of permissions, view
he [Auth](../../getting-started/auth) page.
Roles and permissions in Castopod are defined in two ways, **Instance** users
and [**Podcast**. contributors](../podcast/contributors). For a detailed list of
permissions, view he [Auth](../../getting-started/auth) page.
## Adding a User to the instance
You can add a user to your instance by choosing `Users` -> `New User` from the left hand navigation menu. There
are three roles you can assign to an instance user:
You can add a user to your instance by choosing `Users` -> `New User` from the
left hand navigation menu. There are three roles you can assign to an instance
user:
- **Super Admin**: This user has complete control over Castopod including adding or removing podcasts or users.
- **Manager**: This user can manage Castopod's content, such as adding or importing a new podcast and managing people.
- **Podcaster**: This is for general users of Castopod who can access the admin interface.
- **Super Admin**: This user has complete control over Castopod including adding
or removing podcasts or users.
- **Manager**: This user can manage Castopod's content, such as adding or
importing a new podcast and managing people.
- **Podcaster**: This is for general users of Castopod who can access the admin
interface.

31
docs/src/content/docs/en/user-guide/podcast/analytics.mdx
View File

@ -2,22 +2,24 @@
title: Analytics
---
Castopod comes with a number of different analytics and statistics about your podcast(s). From the left hand
navigation, choose `Analytics` to view the various options.
Castopod comes with a number of different analytics and statistics about your
podcast(s). From the left hand navigation, choose `Analytics` to view the
various options.
## Audience overview
This page provides an overview of your episode's daily downloads, monthly downloads, and daily bandwidth used.
This page provides an overview of your episode's daily downloads, monthly
downloads, and daily bandwidth used.
## Unique listeners
View graphs of the number of daily and monthly users of your podcast. Use the zoom function at the top of each
graph to zoom in or out.
View graphs of the number of daily and monthly users of your podcast. Use the
zoom function at the top of each graph to zoom in or out.
## Listening time
View graphs of your listener's daily and monthly cumulative listening time. Use the zoom function at the top of each
graph to zoom in or out.
View graphs of your listener's daily and monthly cumulative listening time. Use
the zoom function at the top of each graph to zoom in or out.
## Players
@ -28,8 +30,9 @@ This page provides four pie charts to view statistics for the last week:
- Episode downloads by device
- Episode downloads by operating system
You can hover over each graph and press the three dots to download statistics for the graph you are hovering over.
You can interact with the graphs to download or print:
You can hover over each graph and press the three dots to download statistics
for the graph you are hovering over. You can interact with the graphs to
download or print:
- Image (PNG, JPG, SVG, or PDF)
- Data (JSON, CSV, XLSX, HTML, or PDF)
@ -37,13 +40,15 @@ You can interact with the graphs to download or print:
## Locations
You can view where your listeners are located by choosing _Locations_. Two pie charts are available showing
episode downloads by country for the past week and past year. At the bottom of the page, you can view a world map
showing your listener's locations.
You can view where your listeners are located by choosing _Locations_. Two pie
charts are available showing episode downloads by country for the past week and
past year. At the bottom of the page, you can view a world map showing your
listener's locations.
## Time periods
Two bar graphs displaying the week day and time of day your listeners listen to your podcsat.
Two bar graphs displaying the week day and time of day your listeners listen to
your podcsat.
## Web pages visits

40
docs/src/content/docs/en/user-guide/podcast/broadcast.mdx
View File

@ -4,31 +4,35 @@ title: Broadcast your podcast
## Add your podcast to podcast directories
Listeners can add your RSS feed to their podcast app of choice to subscribe to your podcast. Most listeners will
find your podcast in a podcast directory, such as Apple Podcasts, YouTube Music, Spotify, or the Podcast Index.
These four are the most popular podcast directories and a number of other directories pull their data from Apple
Podcasts.
Listeners can add your RSS feed to their podcast app of choice to subscribe to
your podcast. Most listeners will find your podcast in a podcast directory, such
as Apple Podcasts, YouTube Music, Spotify, or the Podcast Index. These four are
the most popular podcast directories and a number of other directories pull
their data from Apple Podcasts.
Visit [Podnews](https://podnews.net/article/all-the-podcast-directories) to learn how to add your podcast to
most of the podcast directories.
Visit [Podnews](https://podnews.net/article/all-the-podcast-directories) to
learn how to add your podcast to most of the podcast directories.
Once your podcast is listed in the podcast directories, you can link to them on your home page by choosing
`Broadcast` from the left hand navigation.
Once your podcast is listed in the podcast directories, you can link to them on
your home page by choosing `Broadcast` from the left hand navigation.
### Podcasting Apps
Castopod provides the ability to link to a majority of podcast directories where users can find your podcast.
For each directory listed fill out the link to your podcast in a specific directory and the ID. If you want
an icon displayed on your home page, toggle `Display in podcast homepage?`.
Castopod provides the ability to link to a majority of podcast directories where
users can find your podcast. For each directory listed fill out the link to your
podcast in a specific directory and the ID. If you want an icon displayed on
your home page, toggle `Display in podcast homepage?`.
After pressing `Save` in the upper right hand corner, visit your home page to see the icons with hyperlinks
on the right hand side of your home page under _Listen on_.
After pressing `Save` in the upper right hand corner, visit your home page to
see the icons with hyperlinks on the right hand side of your home page under
_Listen on_.
### Social Networks
If your podcast has a presence on social networks, Castopod provides the ability to link to your social network
profiles. Add the link to your profile page in the text field and toggle if you want it displayed on your
home page.
If your podcast has a presence on social networks, Castopod provides the ability
to link to your social network profiles. Add the link to your profile page in
the text field and toggle if you want it displayed on your home page.
After pressing `Save` in the upper right hand corner, visit your home page to see the icons with hyperlinks
on the right hand side of your home page under _Find your podcast on_.
After pressing `Save` in the upper right hand corner, visit your home page to
see the icons with hyperlinks on the right hand side of your home page under
_Find your podcast on_.

16
docs/src/content/docs/en/user-guide/podcast/contributors.mdx
View File

@ -2,8 +2,9 @@
title: Contributors
---
From the podcast dashboard, click **Contributors** to add or edit users to have access to the podcast and its settings.
For a detailed list of permissions, view the [Auth](../../getting-started/auth) page.
From the podcast dashboard, click **Contributors** to add or edit users to have
access to the podcast and its settings. For a detailed list of permissions, view
the [Auth](../../getting-started/auth) page.
## Roles
@ -15,14 +16,15 @@ The admin user has complete control over the individual podcast.
### Editor
The editor has access to management functions including podcast import, managing persons, creating or deleting
episodes, and managing clips.
The editor has access to management functions including podcast import, managing
persons, creating or deleting episodes, and managing clips.
### Author
The autorh can manage content of the podcast, but cannot publish an episode. They can manage
[contributors](contributors), create clips, and create episodes.
The autorh can manage content of the podcast, but cannot publish an episode.
They can manage [contributors](contributors), create clips, and create episodes.
### Guest
The guest can view the podcast dashboard and view episodes. They cannot edit or add any content.
The guest can view the podcast dashboard and view episodes. They cannot edit or
add any content.

52
docs/src/content/docs/en/user-guide/podcast/dashboard.mdx
View File

@ -2,49 +2,59 @@
title: Podcast Dashboard
---
When you choose your podcast from the Admin dashboard you will be redirected to the Podcast dashboard page.
When you choose your podcast from the Admin dashboard you will be redirected to
the Podcast dashboard page.
The Podcast dashboard shows you up to five of the latest episodes, both those published and scheduled. You can click
on any of these episodes to view them or click `See all episodes` to see a list of every episode.
The Podcast dashboard shows you up to five of the latest episodes, both those
published and scheduled. You can click on any of these episodes to view them or
click `See all episodes` to see a list of every episode.
## Edit your podcast
To edit your podcast, press `Edit podcast` in the upper right hand corner or `Edit podcast` in the left hand side
navigation.
To edit your podcast, press `Edit podcast` in the upper right hand corner or
`Edit podcast` in the left hand side navigation.
You can edit any of the [fields you filled out when creating your podcast](../instance/podcast).
You can edit any of the
[fields you filled out when creating your podcast](../instance/podcast).
When finished press the `Save podcast` button in the upper right hand corner.
You can also choose to delete your podcast by pressing `Delete podcast` at the bottom of the Edit podcast page.
You can also choose to delete your podcast by pressing `Delete podcast` at the
bottom of the Edit podcast page.
## Manage persons
If you have added people to Persons in the Admin dashboard, you can assign them a role here. People assigned roles
will show up on the [Credits page](../website/credits) linked from your home page to give them
If you have added people to Persons in the Admin dashboard, you can assign them
a role here. People assigned roles will show up on the
[Credits page](../website/credits) linked from your home page to give them
credit for contributing to the podcast.
Roles include Administration, Audio production, cast, guests, hosts, writing, and more.
Roles include Administration, Audio production, cast, guests, hosts, writing,
and more.
From the **Persons** drop down, choose the person you want to add. Then choose a role from the \*_Roles_ drop down and
press `Add person(s)`.
From the **Persons** drop down, choose the person you want to add. Then choose a
role from the \*_Roles_ drop down and press `Add person(s)`.
A list of all people assigned roles will be displayed. You can remove them by pressing the `Remove` button.
A list of all people assigned roles will be displayed. You can remove them by
pressing the `Remove` button.
Adding persons to your podcast populates the Credits page linked from your
[home page](../website).
## Podcast imports
Podcast imports show you the status of a feed that you imported into Castopod, including the feed name,
how long the import took, and how many episodes were imported. Under **Actions** you can try re-import the feed
if the original import failed or delete the status message for the imported feed.
Podcast imports show you the status of a feed that you imported into Castopod,
including the feed name, how long the import took, and how many episodes were
imported. Under **Actions** you can try re-import the feed if the original
import failed or delete the status message for the imported feed.
If the feed you imported has been updated after your import, press `Synchronize Feeds` in the upper right hand
corner to import the missing episodes.
If the feed you imported has been updated after your import, press
`Synchronize Feeds` in the upper right hand corner to import the missing
episodes.
## Sync feeds
You can also synchronize missing episode from an imported feed by choosing `Sync Feeds` from the Podcast dashboard
menu. The **Feed URL** should auto-populate if you have previously imported a feed. Press `Add to queue` to import
any missing episodes from the feed.
You can also synchronize missing episode from an imported feed by choosing
`Sync Feeds` from the Podcast dashboard menu. The **Feed URL** should
auto-populate if you have previously imported a feed. Press `Add to queue` to
import any missing episodes from the feed.

146
docs/src/content/docs/en/user-guide/podcast/episodes.mdx
View File

@ -2,130 +2,150 @@
title: Episodes
---
From the left hand navigation, click **Episodes** and the menu will expand to **All Episodes** and **New Episode**.
From the left hand navigation, click **Episodes** and the menu will expand to
**All Episodes** and **New Episode**.
## All Episodes
To view a list of all episodes, click `All Episodes`. Each episode will be displayed in a list with its name and
notes, Visibility such as published or scheduled, and how many downloads and comments each episode has.
To view a list of all episodes, click `All Episodes`. Each episode will be
displayed in a list with its name and notes, Visibility such as published or
scheduled, and how many downloads and comments each episode has.
### Actions and the Episode Dashboard
Click the three dots under **Actions** to view a menu of options for an episode or click on an individual episode to
view the available actions:
Click the three dots under **Actions** to view a menu of options for an episode
or click on an individual episode to view the available actions:
- **Go to page**: This will redirect you to the public page of the episode and display the show notes.
- **Edit**: This allows you to change the fields you filled when creating the episode (see below).
- **Go to page**: This will redirect you to the public page of the episode and
display the show notes.
- **Edit**: This allows you to change the fields you filled when creating the
episode (see below).
### Embeddable player
Choose a theme color and press the copy button to the right of the text box to copy the
code to your clipboard. Insert the code into a web page to display the episode.
Choose a theme color and press the copy button to the right of the text box to
copy the code to your clipboard. Insert the code into a web page to display the
episode.
### Persons
If you have added people in the Admin interface, you can choose a person and assign them a role, such
as guest, for a given episode.
If you have added people in the Admin interface, you can choose a person and
assign them a role, such as guest, for a given episode.
### Video clips and Soundbites
The process to create a video clip and soundbite is the same. It may take a minute for the file to load and you
will see the waveform.
The process to create a video clip and soundbite is the same. It may take a
minute for the file to load and you will see the waveform.
A video clip will create an MP4 video of the audio with text from the transcript matched to the audio. A soundbite
will create an audio clip.
A video clip will create an MP4 video of the audio with text from the transcript
matched to the audio. A soundbite will create an audio clip.
Enter the name of the clip you want to create. Then drag the slider to where you want to start and end your
video clip or soundbite. You can press the `Play` button to preview your clip.
Enter the name of the clip you want to create. Then drag the slider to where you
want to start and end your video clip or soundbite. You can press the `Play`
button to preview your clip.
For video clips, choose a format, including Landscape, Portrait or Squared and a background theme color.
For video clips, choose a format, including Landscape, Portrait or Squared and a
background theme color.
Then press the `Create` button, you will be redirected to a status page displaying the status of creating the clip.
Refresh the page to see if it's `Running` or completed. You may need to be patient depending on the length of the clip.
Then press the `Create` button, you will be redirected to a status page
displaying the status of creating the clip. Refresh the page to see if it's
`Running` or completed. You may need to be patient depending on the length of
the clip.
:::note
To create video clips and soundbites, your server must have `FFMPEG` installed and a transcript.
:::
:::note To create video clips and soundbites, your server must have `FFMPEG`
installed and a transcript. :::
## Create episode
To add an episode, press the `Add an episode button` in the upper right hand corner of the Episode dashboard or click
`New episode` in the left hand navigation under `Episodes`.
To add an episode, press the `Add an episode button` in the upper right hand
corner of the Episode dashboard or click `New episode` in the left hand
navigation under `Episodes`.
### Episode Info
#### Audio file
Press the `Choose File` button to select the audio file to upload to Castopod. The audio file must be an mp3 or m4a
file and cannot be larger than 512 megabytes.
Press the `Choose File` button to select the audio file to upload to Castopod.
The audio file must be an mp3 or m4a file and cannot be larger than 512
megabytes.
### Episode cover
You can optionally add a different podcast cover / artwork. Press `Choose File` and select an image from your computer
that must be at least 1400px wide and tall and no larger than 3000px wide and tall. If you do not choose an
episode cover, your default podcast artwork will be used.
You can optionally add a different podcast cover / artwork. Press `Choose File`
and select an image from your computer that must be at least 1400px wide and
tall and no larger than 3000px wide and tall. If you do not choose an episode
cover, your default podcast artwork will be used.
#### Title
Enter the name for your new episode. Do not add the season or episode number in the **Title** field. Choose a clear
and concise episode name to help your listeners.
Enter the name for your new episode. Do not add the season or episode number in
the **Title** field. Choose a clear and concise episode name to help your
listeners.
#### Permalink
The permalink is the link to the public episode page. This will be automatically filled out based on the title
you entered above. If you wish to have a different permalink, press the edit button to the right of the
displayed permalink.
The permalink is the link to the public episode page. This will be automatically
filled out based on the title you entered above. If you wish to have a different
permalink, press the edit button to the right of the displayed permalink.
#### Season and Episode
You can optionally add a season and / or episode number to your episode. If you are adding a new episode and a
previous episode had a season and /or episode number, the field(s) will be auto filled for you. You can leave it or
update with a different season and / or episode number.
You can optionally add a season and / or episode number to your episode. If you
are adding a new episode and a previous episode had a season and /or episode
number, the field(s) will be auto filled for you. You can leave it or update
with a different season and / or episode number.
### Show Notes
Describe your episode in detail. You can use up to 4000 characters, and you can use Markdown to style your show
notes. You can expand the text box by pressing and holding the bottom right corner of the text box.
Describe your episode in detail. You can use up to 4000 characters, and you can
use Markdown to style your show notes. You can expand the text box by pressing
and holding the bottom right corner of the text box.
When your show notes are complete, press `Preview` to view how your show notes will be displayed.
When your show notes are complete, press `Preview` to view how your show notes
will be displayed.
### Additional Files
#### Transcripts
You can add a transcript to your episode by choosing a file in SRT or VTT format to upload. Transcripts will be
shown in a tab on the episode page and some podcast apps such as Apple Podcasts can display the transcript.
Transcripts help users who may have a hearing disability and can also help with search engine optimization.
You can add a transcript to your episode by choosing a file in SRT or VTT format
to upload. Transcripts will be shown in a tab on the episode page and some
podcast apps such as Apple Podcasts can display the transcript.
Transcripts help users who may have a hearing disability and can also help with
search engine optimization.
#### Chapters
You can optionally upload a chapters file in JSON format. To learn more about chapters and for an example of the
correct format, visit the [Podcast Namespace](https://github.com/Podcastindex-org/podcast-namespace/blob/main/chapters/jsonChapters.md).
You can optionally upload a chapters file in JSON format. To learn more about
chapters and for an example of the correct format, visit the
[Podcast Namespace](https://github.com/Podcastindex-org/podcast-namespace/blob/main/chapters/jsonChapters.md).
:::note
Not all podcast players natively support chapters in JSON format. More modern players, such as Fountain and
Apple Podcasts, do support chapters in JSON format. Chapters do not allow you to click to select the chapter
in Castopod's embeddable player at this time.
:::
:::note Not all podcast players natively support chapters in JSON format. More
modern players, such as Fountain and Apple Podcasts, do support chapters in JSON
format. Chapters do not allow you to click to select the chapter in Castopod's
embeddable player at this time. :::
### Publish your episode
When complete, press the `Create episode` button at the bottom of the page. You will be automatically directed to
the next step to publish your episode. Your episode is in draft mode and is not yet published. You can preview
how your episode will look when published or publish your episode. To publish your episode, press the `Publish` button
in the upper right hand corner.
When complete, press the `Create episode` button at the bottom of the page. You
will be automatically directed to the next step to publish your episode. Your
episode is in draft mode and is not yet published. You can preview how your
episode will look when published or publish your episode. To publish your
episode, press the `Publish` button in the upper right hand corner.
### Create your announcement post
After pressing `Publish` you will be directed to the next page to draft your announcement post. Write your message
in the text box provided. This will be the message broadcast to the Fediverse and published on your podcast's home
page.
After pressing `Publish` you will be directed to the next page to draft your
announcement post. Write your message in the text box provided. This will be the
message broadcast to the Fediverse and published on your podcast's home page.
### Publication date
Choose `Now` or `Schedule` to publish your episode. If you choose `Now`, your episode will be live. Or you can
schedule the day and time to publish your episode by choosing the `Schedule` radio button and choosing the day and
time. Press `Publish` to finish.
Choose `Now` or `Schedule` to publish your episode. If you choose `Now`, your
episode will be live. Or you can schedule the day and time to publish your
episode by choosing the `Schedule` radio button and choosing the day and time.
Press `Publish` to finish.
Your RSS feed will be automatically updated with your episode information and listeners who subscribe will be
notified of a new episode. Congratulations on publishing your first episode!
Your RSS feed will be automatically updated with your episode information and
listeners who subscribe will be notified of a new episode. Congratulations on
publishing your first episode!

9
docs/src/content/docs/en/user-guide/podcast/index.mdx
View File

@ -4,11 +4,12 @@ title: Manage Podcasts
import { LinkCard, CardGrid } from "@astrojs/starlight/components";
From the Castopod admin interface, click **Podcasts** and then **All Podcasts** and you will be redirected to the
podcast dashboard. This page displays the latest episodes, including any scheduled episodes.
From the Castopod admin interface, click **Podcasts** and then **All Podcasts**
and you will be redirected to the podcast dashboard. This page displays the
latest episodes, including any scheduled episodes.
From the podcast dashboard, you can add episodes, view analytics, add links to your homepage, and more. Learn more
by clicking the links below.
From the podcast dashboard, you can add episodes, view analytics, add links to
your homepage, and more. Learn more by clicking the links below.
<CardGrid>
<LinkCard title="Podcast dashboard" href="dashboard" />

76
docs/src/content/docs/en/user-guide/website/index.mdx
View File

@ -2,64 +2,75 @@
title: Podcast Home Page
---
The podcast home page is your landing page for your listeners to view episode announcements, messages, episodes,
and links to where to find your podcast. If you have only one podcast, your users will be automatically redirected
from your top level domain, such as `www.yourpodcast.com`, to the podcast page at
The podcast home page is your landing page for your listeners to view episode
announcements, messages, episodes, and links to where to find your podcast. If
you have only one podcast, your users will be automatically redirected from your
top level domain, such as `www.yourpodcast.com`, to the podcast page at
`www.yourpodcast.com/yourpodcasthandle`.
If you are hosting multiple podcasts, your top level page will display the artwork for each podcast. Clicking on
the podcast artwork will take you to your podcast page at `www.yourpodcast.com/yourpodcasthandle`.
If you are hosting multiple podcasts, your top level page will display the
artwork for each podcast. Clicking on the podcast artwork will take you to your
podcast page at `www.yourpodcast.com/yourpodcasthandle`.
## Home Page
If you are logged in to your podcast, you will see a strip across the top of the page with a link to the admin
interface of your podcast, a bell that will show if you have any new notifications, and the user who is logged in.
You can click on the user for quick access to your account, changing your password, or to log out.
If you are logged in to your podcast, you will see a strip across the top of the
page with a link to the admin interface of your podcast, a bell that will show
if you have any new notifications, and the user who is logged in. You can click
on the user for quick access to your account, changing your password, or to log
out.
:::note
If you have multiple podcasts, you can click the user dropdown to switch to choose which podcast to interact with.
If your account has access to two or more podcasts, pay attention to which podcast is broadcasting messages!
:::
:::note If you have multiple podcasts, you can click the user dropdown to switch
to choose which podcast to interact with. If your account has access to two or
more podcasts, pay attention to which podcast is broadcasting messages! :::
Listeners can click the `Follow` button to follow any messages, including episode announcements, from a Fediverse
app, such as Mastodon. After clicking `Follow` a pop-up box will be displayed where the user enterse their Fediverse
Listeners can click the `Follow` button to follow any messages, including
episode announcements, from a Fediverse app, such as Mastodon. After clicking
`Follow` a pop-up box will be displayed where the user enterse their Fediverse
handle and then clicks `Proceed to follow`.
### Podcast RSS feed
On the right hand side is a link to your RSS Podcast feed. Users can copy that and subscribe directly in their
podcast app.
On the right hand side is a link to your RSS Podcast feed. Users can copy that
and subscribe directly in their podcast app.
### Social Networks
Below the RSS feed is are icons that link to all of the social networks you toggled on in the
[Broadcast](../podcast/broadcast#podcasting-apps) section of the podcast's admin section.
Below the RSS feed is are icons that link to all of the social networks you
toggled on in the [Broadcast](../podcast/broadcast#podcasting-apps) section of
the podcast's admin section.
### Podcast Directories
Below the social networking links is **Listen On** which displays icons linked to the podcast directories you
toggled on in the [Broadcast](../podcast/broadcast#social-networks) section of the podcast's
admin section.
Below the social networking links is **Listen On** which displays icons linked
to the podcast directories you toggled on in the
[Broadcast](../podcast/broadcast#social-networks) section of the podcast's admin
section.
## Activity
The **Activity** tab is located directly under your podcast artwork is the default home page for your podcast. Website
visitors are presented with a list of messages in chronological order. If you are logged in as a podcast
administrator, you will see a text box where you can write a message to be broadcasted to your followers. If you
include the episode URL, a preview of that episode will be included in your message.
The **Activity** tab is located directly under your podcast artwork is the
default home page for your podcast. Website visitors are presented with a list
of messages in chronological order. If you are logged in as a podcast
administrator, you will see a text box where you can write a message to be
broadcasted to your followers. If you include the episode URL, a preview of that
episode will be included in your message.
Below each message there are four icons:
- **Comments**: This will show you the number of comments on a given message. Clicking this will show you all replies to
your message. You can click the three dots to block a user or a domain in case of spam.
- **Shares**: This shows the number of times your message was shared by other users.
- **Comments**: This will show you the number of comments on a given message.
Clicking this will show you all replies to your message. You can click the
three dots to block a user or a domain in case of spam.
- **Shares**: This shows the number of times your message was shared by other
users.
- **Favorites**: This shows how many people liked your message.
## Episodes
The **Episodes** tab shows a list of all episode announcements you have shared. If you are using season numbers, it
will default to the current season. Users can click the **Season** link above all of the messages for a dropdown menu
to view past episodes by season.
The **Episodes** tab shows a list of all episode announcements you have shared.
If you are using season numbers, it will default to the current season. Users
can click the **Season** link above all of the messages for a dropdown menu to
view past episodes by season.
## About
@ -67,7 +78,8 @@ The About tab shares general information about your podcast, including:
- Podcast description
- Podcast category
- The [people](../podcast/dashboard#manage-persons) who contribute to the podcast
- The [people](../podcast/dashboard#manage-persons) who contribute to the
podcast
- Statistics
- Number of seasons
- Number of episodes

687
modules/Api/Rest/V1/podcast.json
View File

@ -1,687 +0,0 @@
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Castopod podcasts"
},
"paths": {
"/api/rest/v1/podcasts": {
"get": {
"summary": "List all podcasts",
"responses": {
"200": {
"description": "Object of podcasts",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Podcasts"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/rest/v1/podcasts/{id}": {
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the podcast to retrieve",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
}
}
],
"get": {
"summary": "Info for a specific podcast",
"responses": {
"200": {
"description": "Expected response to a valid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Podcast"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/rest/v1/episodes": {
"get": {
"summary": "List all episodes",
"responses": {
"200": {
"description": "Object of episodes",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Episodes"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"summary": "Create a new episode",
"requestBody": {
"description": "Episode object that needs to be added",
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/EpisodeCreateRequest"
}
}
}
},
"responses": {
"201": {
"description": "Episode created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Episode"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/rest/v1/episodes/{id}": {
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the episode to retrieve",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
}
}
],
"get": {
"summary": "Info for a specific episode",
"responses": {
"200": {
"description": "Expected response to a valid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Episode"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/rest/v1/episodes/{id}/publish": {
"post": {
"summary": "Publish an episode",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the episode to publish",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
}
}
],
"requestBody": {
"description": "Publish parameters",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EpisodePublishRequest"
}
}
}
},
"responses": {
"200": {
"description": "Episode published successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Episode"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Podcast": {
"type": "object",
"required": [
"id",
"guid",
"actor_id",
"handle",
"title",
"description_markdown",
"description_html",
"cover_id",
"language_code",
"category_id",
"owner_name",
"owner_email",
"type",
"is_blocked",
"is_completed",
"is_locked",
"is_published_on_hubs",
"created_by",
"updated_by",
"created_at",
"updated_at",
"feed_url"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"guid": {
"type": "string",
"maxLength": 36
},
"actor_id": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"handle": {
"type": "string",
"maxLength": 32
},
"title": {
"type": "string",
"maxLength": 128
},
"description_markdown": {
"type": "string"
},
"description_html": {
"type": "string"
},
"cover_id": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"banner_id": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"language_code": {
"type": "string",
"maxLength": 2
},
"category_id": {
"type": "integer",
"format": "int64",
"minimum": 1
},
"parental_advisory": {
"type": "string",
"enum": ["clean", "explicit"]
},
"owner_name": {
"type": "string",
"maxLength": 128
},
"owner_email": {
"type": "string",
"maxLength": 255
},
"publisher": {
"type": "string",
"maxLength": 128
},
"type": {
"type": "string",
"enum": ["episodic", "serial"]
},
"copyright": {
"type": "string",
"maxLength": 128
},
"episode_description_footer_markdown": {
"type": "string"
},
"episode_description_footer_html": {
"type": "string"
},
"is_blocked": {
"type": "integer",
"format": "int32",
"enum": [0, 1],
"minLength": 1
},
"is_completed": {
"type": "integer",
"format": "int32",
"enum": [0, 1],
"minLength": 1
},
"is_locked": {
"type": "integer",
"format": "int32",
"enum": [0, 1],
"minLength": 1
},
"imported_feed_url": {
"type": "string",
"maxLength": 512
},
"new_feed_url": {
"type": "string",
"maxLength": 512
},
"payment_pointer": {
"type": "string",
"maxLength": 128
},
"location_name": {
"type": "string",
"maxLength": 128
},
"location_geo": {
"type": "string",
"maxLength": 32
},
"location_osm": {
"type": "string",
"maxLength": 12
},
"custom_rss": {
"type": "string"
},
"is_published_on_hubs": {
"type": "integer",
"format": "int32",
"enum": [0, 1],
"minLength": 1
},
"partner_id": {
"type": "string",
"maxLength": 32
},
"partner_link_url": {
"type": "string",
"maxLength": 512
},
"partner_image_url": {
"type": "string",
"maxLength": 512
},
"created_by": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"updated_by": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"created_at": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date-time"
},
"timezone_type": {
"type": "integer",
"format": "int32"
},
"timezone": {
"type": "string"
}
}
},
"updated_at": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date-time"
},
"timezone_type": {
"type": "integer",
"format": "int32"
},
"timezone": {
"type": "string"
}
}
},
"feed_url": {
"type": "string"
}
}
},
"Podcasts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Podcast"
}
},
"Episode": {
"type": "object",
"required": [
"id",
"title",
"slug",
"podcast_id",
"created_by",
"updated_by",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"podcast_id": {
"type": "integer",
"format": "int64"
},
"description_markdown": {
"type": "string"
},
"description_html": {
"type": "string"
},
"audio_url": {
"type": "string",
"format": "uri"
},
"cover_url": {
"type": "string",
"format": "uri"
},
"duration": {
"type": "integer",
"format": "int32"
},
"published_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "integer",
"format": "int64"
},
"updated_by": {
"type": "integer",
"format": "int64"
}
}
},
"Episodes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Episode"
}
},
"EpisodeCreateRequest": {
"type": "object",
"required": [
"user_id",
"updated_by",
"title",
"slug",
"podcast_id",
"audio_file"
],
"properties": {
"user_id": {
"type": "integer",
"format": "int64",
"description": "ID of the user creating the episode"
},
"updated_by": {
"type": "integer",
"format": "int64",
"description": "ID of the user updating the episode"
},
"title": {
"type": "string",
"description": "Title of the episode"
},
"slug": {
"type": "string",
"description": "URL-friendly slug of the episode"
},
"podcast_id": {
"type": "integer",
"format": "int64",
"description": "ID of the podcast the episode belongs to"
},
"audio_file": {
"type": "string",
"format": "binary",
"description": "Audio file for the episode"
},
"cover": {
"type": "string",
"format": "binary",
"description": "Cover image for the episode"
},
"description": {
"type": "string",
"description": "Description of the episode"
},
"location_name": {
"type": "string",
"description": "Location associated with the episode"
},
"parental_advisory": {
"type": "string",
"enum": ["clean", "explicit"],
"description": "Parental advisory rating"
},
"episode_number": {
"type": "integer",
"format": "int32",
"description": "Episode number (for serial podcasts)"
},
"season_number": {
"type": "integer",
"format": "int32",
"description": "Season number (for serial podcasts)"
},
"type": {
"type": "string",
"enum": ["full", "trailer", "bonus"],
"description": "Type of episode"
},
"block": {
"type": "string",
"enum": ["yes", "no"],
"description": "Block episode from being published"
},
"custom_rss": {
"type": "string",
"description": "Custom RSS content"
},
"premium": {
"type": "string",
"enum": ["yes", "no"],
"description": "Mark episode as premium content"
},
"transcript-choice": {
"type": "string",
"enum": ["upload-file", "remote-url"],
"description": "Transcript source choice"
},
"transcript_file": {
"type": "string",
"format": "binary",
"description": "Transcript file"
},
"transcript_remote_url": {
"type": "string",
"format": "uri",
"description": "Remote URL for transcript"
},
"chapters-choice": {
"type": "string",
"enum": ["upload-file", "remote-url"],
"description": "Chapters source choice"
},
"chapters_file": {
"type": "string",
"format": "binary",
"description": "Chapters file"
},
"chapters_remote_url": {
"type": "string",
"format": "uri",
"description": "Remote URL for chapters"
}
}
},
"EpisodePublishRequest": {
"type": "object",
"required": ["publication_method"],
"properties": {
"publication_method": {
"type": "string",
"enum": ["now", "schedule", "with_podcast"],
"description": "Method of publication"
},
"scheduled_publication_date": {
"type": "string",
"format": "date-time",
"description": "Scheduled date and time for publication"
},
"client_timezone": {
"type": "string",
"description": "Timezone of the client"
}
}
},
"Error": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"format": "int32"
},
"error": {
"type": "integer",
"format": "int32"
},
"messages": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
}
}
}
}
}
}
}

502
modules/Api/Rest/V1/schema.yaml Normal file
View File

@ -0,0 +1,502 @@
openapi: 3.1.0
info:
version: 1.0.0
title: Castopod API
license:
name: AGPL v3
url: https://code.castopod.org/adaures/castopod/-/blob/develop/LICENSE.md
paths:
/podcasts:
get:
summary: Get all podcasts
operationId: get-all-podcasts
responses:
"200":
description: Successful operation
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Podcast"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/podcasts/{podcastId}:
parameters:
- name: podcastId
in: path
description: The id of the podcast to retrieve
required: true
schema:
type: integer
format: int64
get:
summary: Get podcast by ID
description: Returns a single podcast
operationId: get-podcast-by-id
responses:
"200":
description: Successful operation
content:
application/json:
schema:
$ref: "#/components/schemas/Podcast"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/episodes:
get:
summary: Get all episodes
operationId: get-all-episodes
responses:
"200":
description: Object of episodes
content:
application/json:
schema:
type: "array"
items:
$ref: "#/components/schemas/Episode"
default:
description: Unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
post:
summary: Add a new episode
operationId: add-episode
requestBody:
description: Episode object that needs to be added
required: true
content:
multipart/form-data:
schema:
$ref: "#/components/schemas/EpisodeCreateRequest"
responses:
"201":
description: Episode created successfully
content:
application/json:
schema:
$ref: "#/components/schemas/Episode"
default:
description: Unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/episodes/{episodeId}:
parameters:
- name: episodeId
in: path
description: The id of the episode to retrieve
required: true
schema:
type: integer
format: int64
get:
summary: Get episode by ID
description: Returns a single episode
operationId: get-episode-by-id
responses:
"200":
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/Episode"
default:
description: Unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/episodes/{episodeId}/publish:
post:
summary: Publish an episode
operationId: publish-episode
parameters:
- name: episodeId
in: path
description: The id of the episode to publish
required: true
schema:
type: integer
format: int64
requestBody:
description: Publish parameters
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/EpisodePublishRequest"
responses:
"200":
description: Successful operation
content:
application/json:
schema:
$ref: "#/components/schemas/Episode"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
Podcast:
type: object
required:
- id
- guid
- actor_id
- handle
- title
- description_markdown
- description_html
- cover_id
- language_code
- category_id
- owner_name
- owner_email
- type
- is_blocked
- is_completed
- is_locked
- is_published_on_hubs
- created_by
- updated_by
- created_at
- updated_at
- feed_url
properties:
id:
type: integer
format: int64
guid:
type: string
maxLength: 36
actor_id:
type: integer
format: int64
handle:
type: string
maxLength: 32
title:
type: string
maxLength: 128
description_markdown:
type: string
description_html:
type: string
cover_id:
type: integer
format: int64
banner_id:
type: integer
format: int64
language_code:
type: string
maxLength: 2
category_id:
type: integer
format: int64
minimum: 1
parental_advisory:
type: string
enum:
- clean
- explicit
owner_name:
type: string
maxLength: 128
owner_email:
type: string
maxLength: 255
publisher:
type: string
maxLength: 128
type:
type: string
enum:
- episodic
- serial
copyright:
type: string
maxLength: 128
episode_description_footer_markdown:
type: string
episode_description_footer_html:
type: string
is_blocked:
type: integer
format: int32
enum:
- 0
- 1
is_completed:
type: integer
format: int32
enum:
- 0
- 1
is_locked:
type: integer
format: int32
enum:
- 0
- 1
imported_feed_url:
type: string
maxLength: 512
new_feed_url:
type: string
maxLength: 512
location_name:
type: string
maxLength: 128
location_geo:
type: string
maxLength: 32
location_osm:
type: string
maxLength: 12
custom_rss:
type: string
is_published_on_hubs:
type: integer
format: int32
enum:
- 0
- 1
partner_id:
type: string
maxLength: 32
partner_link_url:
type: string
maxLength: 512
partner_image_url:
type: string
maxLength: 512
created_by:
type: integer
format: int64
updated_by:
type: integer
format: int64
created_at:
type: object
properties:
date:
type: string
format: date-time
timezone_type:
type: integer
format: int32
timezone:
type: string
updated_at:
type: object
properties:
date:
type: string
format: date-time
timezone_type:
type: integer
format: int32
timezone:
type: string
feed_url:
type: string
Episode:
type: object
required:
- id
- title
- slug
- podcast_id
- created_by
- updated_by
- created_at
- updated_at
properties:
id:
type: integer
format: int64
title:
type: string
slug:
type: string
podcast_id:
type: integer
format: int64
description_markdown:
type: string
description_html:
type: string
audio_url:
type: string
format: uri
cover_url:
type: string
format: uri
duration:
type: integer
format: int32
published_at:
type: string
format: date-time
created_by:
type: integer
format: int64
updated_by:
type: integer
format: int64
EpisodeCreateRequest:
type: object
required:
- user_id
- updated_by
- title
- slug
- podcast_id
- audio_file
properties:
user_id:
type: integer
format: int64
description: ID of the user creating the episode
updated_by:
type: integer
format: int64
description: ID of the user updating the episode
title:
type: string
description: Title of the episode
slug:
type: string
description: URL-friendly slug of the episode
podcast_id:
type: integer
format: int64
description: ID of the podcast the episode belongs to
audio_file:
type: string
format: binary
description: Audio file for the episode
cover:
type: string
format: binary
description: Cover image for the episode
description:
type: string
description: Description of the episode
location_name:
type: string
description: Location associated with the episode
parental_advisory:
type: string
enum:
- clean
- explicit
description: Parental advisory rating
episode_number:
type: integer
format: int32
description: Episode number (for serial podcasts)
season_number:
type: integer
format: int32
description: Season number (for serial podcasts)
type:
type: string
enum:
- full
- trailer
- bonus
description: Type of episode
block:
type: string
enum:
- "yes"
- "no"
description: Block episode from being published
custom_rss:
type: string
description: Custom RSS content
premium:
type: string
enum:
- "yes"
- "no"
description: Mark episode as premium content
transcript-choice:
type: string
enum:
- upload-file
- remote-url
description: Transcript source choice
transcript_file:
type: string
format: binary
description: Transcript file
transcript_remote_url:
type: string
format: uri
description: Remote URL for transcript
chapters-choice:
type: string
enum:
- upload-file
- remote-url
description: Chapters source choice
chapters_file:
type: string
format: binary
description: Chapters file
chapters_remote_url:
type: string
format: uri
description: Remote URL for chapters
EpisodePublishRequest:
type: object
required:
- publication_method
properties:
publication_method:
type: string
enum:
- now
- schedule
- with_podcast
description: Method of publication
scheduled_publication_date:
type: string
format: date-time
description: Scheduled date and time for publication
client_timezone:
type: string
description: Timezone of the client
Error:
type: object
properties:
status:
type: integer
format: int32
error:
type: integer
format: int32
messages:
type: object
properties:
error:
type: string