chore(docs): migrate the docs site from Fumadocs to Blume (#753)
* Update documentation for ClassroomIO: change Fumadocs to Blume, revise MDX format conventions, and clarify sidebar navigation requirements. * docs: update README and scripts for improved preview and error handling * docs: update Discord link in configuration and documentation * docs: add token-auth route and update documentation formatting * Fix formatting in auto-comment-issues.yml * Fix JSON syntax by adding a comma * fix(docs): declare Blume's Astro build deps so Cloudflare build resolves them blume build generates an Astro project under apps/docs/.blume/ that imports astro, @astrojs/mdx, @tailwindcss/vite, tailwindcss, @tailwindcss/typography, @shikijs/twoslash and @scalar/astro. Under pnpm's isolated node_modules these are nested inside blume and not resolvable from the docs app, so a clean --frozen-lockfile build (Cloudflare) fails at 'Cannot find module astro/config'. Declare them directly in @cio/docs, pinned to blume's resolved versions. * refactor(docs): update API reference paths and documentation for clarity * fix: change platofrm url to docs home page * Refactor documentation for self-hosting ClassroomIO - Removed the Supabase Cloud setup guide as it is no longer needed. - Updated the Enterprise SSO documentation to include a reference link for SSO & licensing. - Added new documentation for Content Security Policy (CSP) configuration. - Created a new section for configuring SMTP for email notifications. - Introduced a comprehensive configuration index for self-hosted ClassroomIO, detailing environment variables and their usage. - Added documentation for optional integrations including Google OAuth, OpenAI, and Unsplash. - Documented the generation and usage of required secrets for ClassroomIO. - Created a section for SSO & licensing, detailing the requirements for Enterprise features. - Added object storage configuration documentation, covering both bundled MinIO and external S3-compatible services. - Documented versioning and upgrade processes for ClassroomIO. - Updated the Coolify and Docker self-hosting guides to streamline configuration references and upgrade instructions. - Enhanced the Railway self-hosting guide with links to relevant configuration sections. - Updated token authentication documentation to reference SSO & licensing. * Add comprehensive guides for ClassroomIO features and functionalities - Introduced a new guide for the Student Dashboard, detailing navigation and features available to students. - Added a guide on using Tags for organizing and filtering courses within ClassroomIO. - Created a guide on how to take attendance in courses, including marking attendance and related functionalities. - Developed a Terminology guide to clarify key terms used throughout ClassroomIO. - Implemented a Token Auth guide for signing users into ClassroomIO from external applications using JWT. - Added instructions for using math in the editor with LaTeX support. - Created a guide for customizing the welcome email sent to students upon enrollment in courses. - Added a guide explaining what ClassroomIO is and its key features. - Updated the home documentation to provide a clearer overview of ClassroomIO and its resources. - Enhanced self-hosted configuration documentation with a new guide for deploying ClassroomIO on Dokploy. - Updated links in the self-hosted configuration documentation for better navigation. - Added new images to support the Dokploy deployment guide. - Updated asset packaging script to handle redirects for the new guide structure. - Fixed footer link to point to the correct Getting Started guide. * chore: uprage version * feat(docs): add DigitalOcean deployment guide and flatten guides structure - Add a guide for deploying ClassroomIO on DigitalOcean using Docker Compose and Caddy for automatic HTTPS. - List DigitalOcean as a deployment option in the self-hosting index. - Move guides out of content/docs/guides into content/docs (student-dashboard, tags, terminology, token-auth, what-is-classroomio, audience, cohorts, community, course, enterprise-sso, mcp, organization, quickstart/*). - Rename home.mdx to index.mdx. - Update package-assets script to emit redirects for the old guides paths. --------- Co-authored-by: Rotimi Best <[email protected]>
This commit is contained in:
Abdulmuizz Hamzat
co-authored by
Rotimi Best
Rotimi Best
parent
5efd7a38c8
commit
b599f1a017
@@ -0,0 +1,66 @@
|
||||
/**
|
||||
* Fetches the public API OpenAPI spec from R2 and enriches it with the bearer
|
||||
* auth scheme, so Blume can render the API reference statically at build time.
|
||||
*
|
||||
* This replaces the old SSR route that fetched the spec on every request. The
|
||||
* page now refreshes when the docs are rebuilt — .github/workflows/upload-openapi-spec.yml
|
||||
* triggers a docs deploy after it publishes a new spec.
|
||||
*
|
||||
* If the fetch fails but a previously fetched spec is on disk, that one is
|
||||
* reused: a network blip should not stop you building or previewing the docs.
|
||||
* With no spec at all there is nothing to render, so the build fails.
|
||||
*/
|
||||
import { access, mkdir, writeFile } from 'node:fs/promises';
|
||||
import { dirname, resolve } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
import { enrichPublicApiOpenApiSpec, PUBLIC_API_OPENAPI_URL } from '@cio/utils/openapi/public-api';
|
||||
|
||||
const OUTPUT = resolve(dirname(fileURLToPath(import.meta.url)), '../openapi/public-api.json');
|
||||
|
||||
const exists = async (path) => {
|
||||
try {
|
||||
await access(path);
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
};
|
||||
|
||||
let response;
|
||||
|
||||
try {
|
||||
response = await fetch(PUBLIC_API_OPENAPI_URL);
|
||||
} catch (error) {
|
||||
if (await exists(OUTPUT)) {
|
||||
console.warn(
|
||||
`[docs] Could not reach ${PUBLIC_API_OPENAPI_URL} (${error.cause?.code ?? error.message}). Reusing the spec already in openapi/.`
|
||||
);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
throw new Error(
|
||||
`Failed to reach the OpenAPI spec at ${PUBLIC_API_OPENAPI_URL}, and no previously fetched copy exists in openapi/. The API reference cannot be built.`,
|
||||
{ cause: error }
|
||||
);
|
||||
}
|
||||
|
||||
if (!response.ok) {
|
||||
if (await exists(OUTPUT)) {
|
||||
console.warn(
|
||||
`[docs] ${PUBLIC_API_OPENAPI_URL} returned ${response.status} ${response.statusText}. Reusing the spec already in openapi/.`
|
||||
);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
throw new Error(
|
||||
`Failed to fetch the OpenAPI spec from ${PUBLIC_API_OPENAPI_URL}: ${response.status} ${response.statusText}`
|
||||
);
|
||||
}
|
||||
|
||||
const spec = enrichPublicApiOpenApiSpec(await response.json());
|
||||
|
||||
await mkdir(dirname(OUTPUT), { recursive: true });
|
||||
await writeFile(OUTPUT, `${JSON.stringify(spec, null, 2)}\n`);
|
||||
|
||||
console.log(`[docs] Wrote enriched OpenAPI spec to ${OUTPUT}`);
|
||||
@@ -0,0 +1,57 @@
|
||||
/**
|
||||
* Packages `blume build` output for the assets-only Cloudflare Worker.
|
||||
*
|
||||
* Two things have to be reconciled:
|
||||
*
|
||||
* 1. `deployment.base: '/docs'` makes Blume emit URLs like `/docs/foo`, but it
|
||||
* does NOT nest the output — pages land in `dist/foo/index.html`. The worker
|
||||
* is asked for `/docs/foo` (the website proxies the full path through), so
|
||||
* the build is moved under `build/docs/` to line up with the served paths.
|
||||
*
|
||||
* 2. Astro's own `redirects` are unusable under a base: it prefixes a
|
||||
* redirect's source but not its target, emitting `url=/guides` rather than
|
||||
* `/docs/guides`. So the redirects are written here as a Cloudflare
|
||||
* `_redirects` file, which must sit at the root of the assets directory.
|
||||
*/
|
||||
import { readdirSync } from 'node:fs';
|
||||
import { cp, mkdir, rm, writeFile } from 'node:fs/promises';
|
||||
import { dirname, resolve } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
|
||||
const dist = resolve(root, 'dist');
|
||||
const out = resolve(root, 'build');
|
||||
const content = resolve(root, 'content/docs');
|
||||
|
||||
const slugs = (dir) =>
|
||||
readdirSync(resolve(content, dir), { withFileTypes: true })
|
||||
.filter((e) => e.isFile() && e.name.endsWith('.mdx') && e.name !== 'index.mdx')
|
||||
.map((e) => e.name.replace(/\.mdx$/, ''));
|
||||
|
||||
// Guides moved from `/docs/<slug>` to `/docs/guides/<slug>` (Blume scopes a tab's
|
||||
// sidebar by route prefix). The old URLs are public, so forward them.
|
||||
const rootSlugs = new Set(slugs('.'));
|
||||
const GUIDE_REDIRECTS = slugs('guides')
|
||||
// A slug that is also a root page would shadow it — `_redirects` beats assets.
|
||||
.filter((slug) => !rootSlugs.has(slug))
|
||||
.map((slug) => `/docs/${slug} /docs/guides/${slug} 301`)
|
||||
.join('\n');
|
||||
|
||||
const REDIRECTS = `# Generated by scripts/package-assets.mjs — do not edit.
|
||||
/docs/ /docs 301
|
||||
/docs/home /docs 301
|
||||
/docs/how-to-guides/* /docs/:splat 301
|
||||
/docs/api/reference /docs/api 301
|
||||
|
||||
/docs/contributor-guides /docs/guides/contributing 301
|
||||
/docs/contributor-guides/* /docs/guides/contributing/:splat 301
|
||||
${GUIDE_REDIRECTS}
|
||||
`;
|
||||
|
||||
await rm(out, { recursive: true, force: true });
|
||||
await mkdir(out, { recursive: true });
|
||||
|
||||
await cp(dist, resolve(out, 'docs'), { recursive: true });
|
||||
await writeFile(resolve(out, '_redirects'), REDIRECTS);
|
||||
|
||||
console.log('[docs] Packaged dist/ -> build/docs/ with _redirects');
|
||||
Reference in New Issue
Block a user