diff --git a/astro.config.mts b/astro.config.mts index b322bcd0..a4c4c00a 100644 --- a/astro.config.mts +++ b/astro.config.mts @@ -34,7 +34,7 @@ export const locales = { fr: { label: 'Français', lang: 'fr' }, // it: { label: 'Italiano', lang: 'it' }, // id: { label: 'Bahasa Indonesia', lang: 'id' }, - // 'zh-cn': { label: '简体中文', lang: 'zh-CN' }, + 'zh-cn': { label: '简体中文', lang: 'zh-CN' }, // 'pt-br': { label: 'Português do Brasil', lang: 'pt-BR' }, // 'pt-pt': { label: 'Português', lang: 'pt-PT' }, ko: { label: '한국어', lang: 'ko' }, diff --git a/lunaria.config.ts b/lunaria.config.ts index b33d1470..7d3e1c3d 100644 --- a/lunaria.config.ts +++ b/lunaria.config.ts @@ -56,13 +56,13 @@ export default defineConfig({ // tag: 'id', // }, // }, - // { - // label: '简体中文', - // lang: 'zh-cn', - // parameters: { - // tag: 'zh-CN', - // }, - // }, + { + label: '简体中文', + lang: 'zh-cn', + parameters: { + tag: 'zh-CN', + }, + }, // { // label: 'Português do Brasil', // lang: 'pt-br', diff --git a/src/content/docs/zh-cn/config-reference/dashboard.mdx b/src/content/docs/zh-cn/config-reference/dashboard.mdx new file mode 100644 index 00000000..9c607d5b --- /dev/null +++ b/src/content/docs/zh-cn/config-reference/dashboard.mdx @@ -0,0 +1,227 @@ +--- +i18nReady: true +title: "仪表板配置" +description: "StudioCMSOptions dashboardConfig 参考文档" +sidebar: + order: 6 +--- + +import ReadMore from '~/components/ReadMore.astro'; + +StudioCMS 集成配置选项架构参考 + +```ts twoslash title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + dashboardConfig: { + dashboardEnabled: true, + dashboardRouteOverride: 'dashboard', + developerConfig: {}, + faviconURL: '/favicon.svg', + inject404Route: true, + versionCheck: true, + AuthConfig: {}, + }, +}); +``` + +## `dashboardEnabled` + +`dashboardEnabled` 是用于确定是否启用仪表板的布尔值。 + +- **类型:** `boolean` +- **默认值:** `true` + +### 用法示例 + +```ts twoslash {3} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + dashboardConfig: { + dashboardEnabled: true, // 默认值 - 启用仪表板 + } +}) +``` + +## `DashboardRouteOverride` + +`DashboardRouteOverride` 是用于设置仪表板路由路径的字符串。 + +- **类型:** `string` +- **默认值:** `'dashboard'` + +### 用法示例 + +```ts twoslash {3} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + dashboardConfig: { + dashboardRouteOverride: 'dashboard', // 默认值 - 设置仪表板路由为 /dashboard + } +}) +``` + +## `developerConfig` + +`developerConfig` 是用于配置仪表板开发者设置的对象。 + +### 用法示例 + +```ts twoslash {3-5} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + dashboardConfig: { + developerConfig: { + demoMode: false, // 默认值 - 禁用演示模式 + }, + } +}) +``` + +## `faviconURL` + +`faviconURL` 是用于设置仪表板网站图标的路径字符串。 + +- **类型:** `string` +- **默认值:** `'/favicon.svg'` + +### 用法示例 + +```ts twoslash {3} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + dashboardConfig: { + faviconURL: '/favicon.svg', // 默认值 - 设置仪表板网站图标 + } +}) +``` + +## `inject404Route` + +`inject404Route` 是用于确定是否注入404路由的布尔值。 + +- **类型:** `boolean` +- **默认值:** `true` + +### 用法示例 + +```ts twoslash {3} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + dashboardConfig: { + inject404Route: true, // 默认值 - 注入404路由 + } +}) +``` + +## `versionCheck` + +`versionCheck` 是用于确定是否启用版本检查的布尔值。 + +- **类型:** `boolean` +- **默认值:** `true` + +### 用法示例 + +```ts twoslash {3} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + dashboardConfig: { + versionCheck: true, // 默认值 - 启用版本检查 + } +}) +``` + +## `AuthConfig` + +`AuthConfig` 是用于配置仪表板认证设置的对象。 + +### 用法示例 + +```ts twoslash {3-5} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + dashboardConfig: { + AuthConfig: { + enabled: true, // 默认值 - 启用认证功能 + }, + } +}) +``` + +### `providers` + +`providers` 是用于配置仪表板认证提供商的对象。 + +- **类型:** [`AuthProviders`](#authprovider) +- **默认值:** `{}` + +#### 用法示例 + +```ts twoslash {4-11} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + dashboardConfig: { + AuthConfig: { + providers: { + google: true, + github: true, + discord: true, + auth0: true, + usernameAndPassword: true, + usernameAndPasswordConfig: {}, + }, + }, + }, +}) +``` + +#### `usernameAndPasswordConfig` + +`usernameAndPasswordConfig` 是用于配置用户名密码认证设置的对象。 + +- **类型:** `{ allowUserRegistration?: boolean }` +- **默认值:** `{}` + +##### 用法示例 + +```ts twoslash {5-8} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + dashboardConfig: { + AuthConfig: { + providers: { + usernameAndPassword: true, + usernameAndPasswordConfig: { + allowUserRegistration: true, // 默认值 - 允许用户注册 + }, + }, + }, + }, +}) +``` + +###### `AuthProvider` + +```ts +type AuthProviders: { + github?: boolean | undefined; + discord?: boolean | undefined; + google?: boolean | undefined; + auth0?: boolean | undefined; + usernameAndPassword?: boolean | undefined; + usernameAndPasswordConfig?: { + allowUserRegistration?: boolean | undefined; + } | undefined; +} | undefined +``` \ No newline at end of file diff --git a/src/content/docs/zh-cn/config-reference/default-frontend-config.mdx b/src/content/docs/zh-cn/config-reference/default-frontend-config.mdx new file mode 100644 index 00000000..b5c7c11c --- /dev/null +++ b/src/content/docs/zh-cn/config-reference/default-frontend-config.mdx @@ -0,0 +1,119 @@ +--- +i18nReady: true +title: "默认前端配置" +description: "StudioCMSOptions defaultFrontEndConfig 参考文档" +sidebar: + order: 5 +--- + +import ReadMore from '~/components/ReadMore.astro'; + +StudioCMS 集成配置选项架构参考 + +```ts twoslash title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + defaultFrontEndConfig: { + favicon: '/favicon.svg', + htmlDefaultLanguage: 'en', + htmlDefaultHead: [], + injectQuickActionsMenu: true, + }, +}); +``` + +## `favicon` + +`favicon` 是用于设置网站图标路径的字符串。 + +- **类型:** `string` +- **默认值:** `'/favicon.svg'` + +### 用法示例 + +```ts twoslash {3} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + defaultFrontEndConfig: { + favicon: '/favicon.svg', // 默认值 - 使用默认网站图标 + } +}) +``` + +## `htmlDefaultLanguage` + +`htmlDefaultLanguage` 是用于设置网站默认语言的字符串。 + +- **类型:** `string` +- **默认值:** `'en'` + +### 用法示例 + +```ts twoslash {3} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + defaultFrontEndConfig: { + htmlDefaultLanguage: 'en', // 默认值 - 使用默认语言 + } +}) +``` + +## `htmlDefaultHead` + +**类型:** [`HeadConfig[]`](#headconfig) + +向网站头部区域添加自定义标签。适用于添加分析工具脚本和第三方资源。 + +```ts twoslash {3} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + defaultFrontEndConfig: { + htmlDefaultHead: [ + // 示例：添加 Fathom 分析脚本 + { + tag: 'script', + attrs: { + src: 'https://cdn.usefathom.com/script.js', + 'data-site': 'MY-FATHOM-ID', + defer: true, + }, + }, + ], + }, +}); +``` + +`htmlDefaultHead` 中的内容会直接转换为 HTML 元素，不会经过 Astro 的 [脚本处理](https://docs.astro.build/zh-cn/guides/client-side-scripts/#script-processing) 或 [样式处理](https://docs.astro.build/zh-cn/guides/styling/#styling-in-astro)。 + +#### `HeadConfig` + +```ts +interface HeadConfig { + tag: string; // HTML标签名 + attrs?: Record; // 标签属性 + content?: string; // 标签内容 +} +``` + +## `injectQuickActionsMenu` + +**类型:** `boolean` +**默认值:** `true` + +在网站右下角注入快速操作菜单界面，允许用户快速访问 StudioCMS 管理后台。 + +### 用法示例 + +```ts twoslash {3} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + defaultFrontEndConfig: { + injectQuickActionsMenu: true, // 默认值 - 注入快速操作菜单 + } +}) +``` \ No newline at end of file diff --git a/src/content/docs/zh-cn/config-reference/image-service.mdx b/src/content/docs/zh-cn/config-reference/image-service.mdx new file mode 100644 index 00000000..152f5726 --- /dev/null +++ b/src/content/docs/zh-cn/config-reference/image-service.mdx @@ -0,0 +1,28 @@ +--- +i18nReady: true +title: "图像服务" +description: "StudioCMSOptions imageService 参考文档" +sidebar: + order: 4 +--- + +import ReadMore from '~/components/ReadMore.astro'; + +StudioCMS 集成配置选项架构参考 + +```ts twoslash title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + imageService: { + cdnPlugin: 'cloudinary-js' + }, +}); +``` + +## `cdnPlugin` + +`cdnPlugin` 是一个枚举值，用于指定启用的图像处理 CDN 插件。 + +- **类型:** `'cloudinary-js'` | `undefined` +- **默认值:** `undefined` \ No newline at end of file diff --git a/src/content/docs/zh-cn/config-reference/included-integrations.mdx b/src/content/docs/zh-cn/config-reference/included-integrations.mdx new file mode 100644 index 00000000..9d02664e --- /dev/null +++ b/src/content/docs/zh-cn/config-reference/included-integrations.mdx @@ -0,0 +1,56 @@ +--- +i18nReady: true +title: "内置集成功能" +description: "StudioCMSOptions IncludedIntegrations 参考文档" +sidebar: + order: 7 +--- + +import ReadMore from '~/components/ReadMore.astro'; + +StudioCMS 集成配置选项架构参考 + +```ts twoslash title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + includedIntegrations: { + robotsTXT: true + }, +}); +``` + +## `robotsTXT` + +`robotsTXT` 是一个布尔值或对象配置，用于控制是否启用 robots.txt 文件功能。 + +- **类型:** `boolean` | [`RobotsConfig`](#robotsconfig) | `undefined` +- **默认值:** `true` + +### 用法示例 + +```ts twoslash {3} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + includedIntegrations: { + robotsTXT: true, // 默认值 - 启用 robots.txt 文件功能 + } +}) +``` + +##### `RobotsConfig` + +```ts +interface RobotsConfig { + host?: boolean | string; // 网站主域名配置 + sitemap?: boolean | string | string[]; // 站点地图URL配置 + policy?: { // 爬虫规则策略 + userAgent?: string; // 目标用户代理 + disallow?: string | string[]; // 禁止访问路径 + allow?: string | string[]; // 允许访问路径 + crawlDelay?: number; // 爬取延迟（秒） + cleanParam?: string | string[]; // 需要清除的参数 + }[] | undefined; +} +``` \ No newline at end of file diff --git a/src/content/docs/zh-cn/config-reference/index.mdx b/src/content/docs/zh-cn/config-reference/index.mdx new file mode 100644 index 00000000..09c1f50d --- /dev/null +++ b/src/content/docs/zh-cn/config-reference/index.mdx @@ -0,0 +1,187 @@ +--- +i18nReady: true +title: "StudioCMSOptions 配置总览" +description: "StudioCMSOptions 核心配置参考文档" +sidebar: + order: 1 +--- + +import ReadMore from '~/components/ReadMore.astro'; + +StudioCMS 集成配置选项架构参考 + +```ts twoslash title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +// 以下为默认值示例 +export default defineStudioCMSConfig({ + dbStartPage: true, + dateLocale: 'en-us', + verbose: false, + plugins: [], + componentRegistry: {}, + overrides: {}, + imageService: {}, + defaultFrontEndConfig: {}, + dashboardConfig: {}, + includedIntegrations: {}, + dateTimeFormat: {}, + sdk: {}, + pageTypeOptions: {} +}); +``` + +## `dbStartPage` + +项目初始化页面 - 用于首次设置时创建数据库配置。 + +- **类型:** `boolean` +- **默认值:** `true` + +### 用法示例 + +```ts twoslash {2} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + dbStartPage: true, // 默认值 - 注入初始化页面用于数据库配置 +}) +``` + +## `dateLocale` + +`dateLocale` 是用于设置日期格式化的区域字符串。 + +- **类型:** `string` +- **默认值:** `'en-us'` + +### 用法示例 + +```ts twoslash {2} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + dateLocale: 'en-us', // 默认值 - 设置日期格式化的区域 +}) +``` + +## `verbose` + +`verbose` 是用于启用或禁用详细日志记录的布尔值。 + +- **类型:** `boolean` +- **默认值:** `false` + +### 用法示例 + +```ts twoslash {2} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + verbose: false, // 默认值 - 关闭详细日志记录 +}) +``` + +## `plugins` + +`plugins` 是用于加载插件的数组配置。 + +- **类型:** `StudioCMSPlugin[]` +- **默认值:** `[]` + +### 用法示例 + +```ts twoslash {1, 3-5} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +import blog from '@studiocms/blog'; +export default defineStudioCMSConfig({ + plugins: [ + blog(), + ], +}) +``` + +## `componentRegistry` + +`componentRegistry` 是用于注册组件的对象配置。 + +- **类型:** `Record` +- **默认值:** `{}` + +### 用法示例 + +```ts twoslash {2-4} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + componentRegistry: { + 'my-component': 'src/components/MyComponent.astro', + }, +}) +``` + +## `dateTimeFormat` + +`dateTimeFormat` 是用于配置日期时间格式的对象。 + +- **类型:** `Intl.DateTimeFormatOptions` +- **默认值:** `{}` + +### 用法示例 + +```ts twoslash {2-6} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + dateTimeFormat: { + year: "numeric", // 年份（数字） + month: "short", // 月份（简写） + day: "numeric" // 日期（数字） + }, +}) +``` + +## `overrides` + +`overrides` 是用于覆盖默认配置的对象。 + +[查看 `overrides` 完整选项][overrides] + +## `imageService` + +`imageService` 是用于配置图像服务的对象。 + +[查看 `imageService` 完整选项][image-service] + +## `defaultFrontEndConfig` + +`defaultFrontEndConfig` 是用于配置默认前端的对象。 + +[查看 `defaultFrontEndConfig` 完整选项][default-frontend-config] + +## `dashboardConfig` + +`dashboardConfig` 是用于配置仪表板的对象。 + +[查看 `dashboardConfig` 完整选项][dashboard] + +## `includedIntegrations` + +`includedIntegrations` 是用于配置内置集成功能的对象。 + +[查看 `includedIntegrations` 完整选项][included-integrations] + +## `sdk` + +`sdk` 是用于配置 SDK 的对象。 + +[查看 `sdk` 完整选项][sdk] + +{/* Links */} +[overrides]: /zh-cn/config-reference/overrides/ +[image-service]: /zh-cn/config-reference/image-service/ +[default-frontend-config]: /zh-cn/config-reference/default-frontend-config/ +[dashboard]: /zh-cn/config-reference/dashboard/ +[included-integrations]: /zh-cn/config-reference/included-integrations/ +[sdk]: /zh-cn/config-reference/sdk/ \ No newline at end of file diff --git a/src/content/docs/zh-cn/config-reference/overrides.mdx b/src/content/docs/zh-cn/config-reference/overrides.mdx new file mode 100644 index 00000000..bbc3e61c --- /dev/null +++ b/src/content/docs/zh-cn/config-reference/overrides.mdx @@ -0,0 +1,80 @@ +--- +i18nReady: true +title: "配置覆盖" +description: "StudioCMSOptions overrides 参考文档" +sidebar: + order: 2 +--- + +import ReadMore from '~/components/ReadMore.astro'; + +StudioCMS 集成配置选项架构参考 + +```ts twoslash title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + overrides: { + CustomImageOverride: 'src/components/CustomImage.astro', + FormattedDateOverride: 'src/components/FormattedDate.astro', + }, +}); +``` + +## `CustomImageOverride` + +`CustomImageOverride` 是用于指定自定义图像组件路径的字符串配置。 + +- **类型:** `string` +- **默认值:** `undefined`（未定义） + +### 用法示例 + +```ts twoslash {3} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + overrides: { + CustomImageOverride: 'src/components/CustomImage.astro', + }, +}) +``` + +## `FormattedDateOverride` + +`FormattedDateOverride` 是用于指定自定义日期组件路径的字符串配置。 + +- **类型:** `string` +- **默认值:** `undefined`（未定义） + +### 用法示例 + +```ts twoslash {3} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + overrides: { + FormattedDateOverride: 'src/components/FormattedDate.astro', + }, +}) +``` + +### 默认日期组件实现 + +```astro title="FormattedDate.astro" +--- +import config from 'studiocms:config'; // 导入StudioCMS配置 + +interface Props { + date: Date; // 日期属性 +} + +const datetime = Astro.props.date.toISOString(); // 转换为ISO格式 +const formattedDate = Astro.props.date.toLocaleDateString( + config.dateLocale, // 使用配置的区域设置 + config.dateTimeFormat // 使用配置的日期时间格式 +); +--- + + +``` \ No newline at end of file diff --git a/src/content/docs/zh-cn/config-reference/sdk.mdx b/src/content/docs/zh-cn/config-reference/sdk.mdx new file mode 100644 index 00000000..c395501b --- /dev/null +++ b/src/content/docs/zh-cn/config-reference/sdk.mdx @@ -0,0 +1,43 @@ +--- +i18nReady: true +title: "SDK 配置" +description: "StudioCMSOptions sdk 参考文档" +sidebar: + order: 8 +--- + +import ReadMore from '~/components/ReadMore.astro'; + +StudioCMS 集成配置选项架构参考 + +```ts twoslash title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + sdk: { + cacheConfig: {}, + }, +}); +``` + +## `cacheConfig` + +`cacheConfig` 是用于配置 SDK 缓存行为的对象。 + +- **类型:** `boolean` | `{ lifetime?: string | undefined; }` | `undefined` +- **默认值:** `{}` + +### 用法示例 + +```ts twoslash {3-7} title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +// ---cut--- +export default defineStudioCMSConfig({ + sdk: { + // 默认配置 - 使用默认 5 分钟缓存生命周期 + cacheConfig: { + lifetime: '5m', + }, + } +}) +``` \ No newline at end of file diff --git a/src/content/docs/zh-cn/guides/contributing/code-contributions.mdx b/src/content/docs/zh-cn/guides/contributing/code-contributions.mdx new file mode 100644 index 00000000..3a141a85 --- /dev/null +++ b/src/content/docs/zh-cn/guides/contributing/code-contributions.mdx @@ -0,0 +1,64 @@ +--- +i18nReady: true +title: 代码贡献指南 +description: 了解如何为 StudioCMS 贡献代码 +sidebar: + order: 2 +--- + +import { Steps } from '@astrojs/starlight/components'; + +本指南将概述完整的贡献流程：从提交问题、创建 PR、审核到合并 PR。 + +如果您想为本项目贡献代码，请遵循以下步骤： + +## 解决现有问题 + +浏览我们的[现有问题](https://github.com/withstudiocms/studiocms/issues)，寻找您感兴趣的任务。您可以使用`标签`作为筛选器缩小搜索范围。如果找到要处理的问题，欢迎提交包含修复方案的 PR。 + +## 进行更改 + + +1. **分叉仓库** + - 使用 GitHub Desktop: + - [GitHub Desktop 入门指南](https://docs.github.com/zh-CN/desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop)将引导您设置 Desktop + - 设置完成后，您可以用它来[分叉仓库](https://docs.github.com/zh-CN/desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop)！ + + - 使用命令行: + - [分叉仓库](https://docs.github.com/zh-CN/github/getting-started-with-github/fork-a-repo#fork-an-example-repository)，这样您可以在准备好合并更改前不影响原始项目 + +2. **安装或更新 Node.js 和 pnpm**，版本需符合 [`.prototools`](https://github.com/withstudiocms/studiocms/blob/main/.prototools) 中的指定要求 + +3. **创建工作分支并开始您的更改！** + +4. **为您的更改编写测试**（如果适用） + +5. **更新文档**（如果需要） + + +## 提交更改 + +当您对更改满意后，提交这些更改。 + +## 拉取请求 (PR) + +完成更改后，创建拉取请求（也称为 PR）。 +- 填写"准备审核"模板，以便我们审核您的 PR。此模板帮助审核者理解您的更改以及 PR 的目的 +- 如果您正在解决问题，别忘了[将 PR 链接到问题](https://docs.github.com/zh-CN/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) +- 启用[允许维护者编辑](https://docs.github.com/zh-CN/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork)复选框，以便可以更新分支进行合并 + +提交 PR 后，文档团队成员将审核您的提案。我们可能会提出问题或要求提供额外信息。 +- 在 PR 合并前，我们可能会要求进行更改，可能使用[建议的更改](https://docs.github.com/zh-CN/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request)或 PR 评论。您可以直接通过 UI 应用建议的更改。您可以在自己的分叉中进行任何其他更改，然后将它们提交到您的分支 +- 当您更新 PR 并应用更改时，将每个对话标记为[已解决](https://docs.github.com/zh-CN/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations) +- 如果遇到任何合并问题，请查看此 [Git 教程](https://github.com/skills/resolve-merge-conflicts)以帮助您解决合并冲突和其他问题 + +## 您的 PR 已合并！ + +恭喜！StudioCMS 团队感谢您。您的贡献将成为下一个版本的一部分。 + +现在您已成为 StudioCMS 社区的一员，可以帮助我们审核其他 PR、回答问题并帮助其他贡献者。如果尚未加入，请参加我们的 [Discord](https://chat.studiocms.dev)，与其他贡献者和 StudioCMS 团队联系。 + +哦，您还会在[贡献者列表][contributors]中看到自己！🎉 + +{/* Links */} +[contributors]: /zh-cn/guides/contributing/getting-started/#我们的贡献者 \ No newline at end of file diff --git a/src/content/docs/zh-cn/guides/contributing/getting-started.mdx b/src/content/docs/zh-cn/guides/contributing/getting-started.mdx new file mode 100644 index 00000000..f391dfb2 --- /dev/null +++ b/src/content/docs/zh-cn/guides/contributing/getting-started.mdx @@ -0,0 +1,27 @@ +--- +i18nReady: true +title: 入门指南 +description: 学习为 StudioCMS 贡献的基础知识 +sidebar: + order: 1 +--- +import ContributorList from '~/components/ContributorList.astro'; + +感谢您投入时间贡献我们的项目！ + +请阅读我们的[行为准则](https://github.com/withstudiocms/studiocms?tab=coc-ov-file#code-of-conduct-)，以保持社区的可亲近性和尊重氛围。 + +我们欢迎社区的各种贡献！无论是错误报告、功能请求还是代码贡献，我们都感激您帮助项目变得更好。要自信地浏览我们的代码库，请参阅[工作原理][how-it-works]部分。 + +## 我们的贡献者 + +项目的存在归功于所有参与贡献的人。[在 GitHub 上加入我们](https://github.com/withstudiocms/studiocms)，您的个人资料图片将自动出现在此列表中： + + + +## 错误报告与功能请求 + +如果您遇到错误或想建议新功能，请在[GitHub 仓库](https://github.com/withstudiocms/studiocms)上提交问题。创建新问题时，请提供尽可能多的细节，包括重现问题的步骤（针对错误）以及对提议功能的清晰描述。 + +{/* Links */} +[how-it-works]: /zh-cn/how-it-works/ \ No newline at end of file diff --git a/src/content/docs/zh-cn/guides/contributing/translations.mdx b/src/content/docs/zh-cn/guides/contributing/translations.mdx new file mode 100644 index 00000000..8b72591d --- /dev/null +++ b/src/content/docs/zh-cn/guides/contributing/translations.mdx @@ -0,0 +1,121 @@ +--- +i18nReady: true +title: 翻译贡献指南 +description: 了解如何为 StudioCMS 贡献翻译 +sidebar: + order: 2 +--- + +import ReadMore from '~/components/ReadMore.astro'; +import { FileTree } from '@astrojs/starlight/components'; + +StudioCMS 是一个全球化项目，我们致力于让所有人都能使用它。如果您精通多种语言，欢迎帮助我们将 StudioCMS 翻译成您的母语。 + +## 加入 Discord 社区 + +开始翻译前，请先加入我们的 [Discord 聊天室](https://chat.studiocms.dev)。 + +加入 Discord 意味着您可以： +- 实时获取问题解答 +- 与其他译者协调工作，避免重复劳动 +- 参与 i18n 讨论和样式指南制定 +- 学习最佳实践并参与决策 + +:::tip[无法访问 Discord？] +我们依然欢迎您的参与！请在 GitHub 上为[文档](https://github.com/withstudiocms/docs/issues/new/choose)或[核心包](https://github.com/withstudiocms/studiocms/issues/new/choose)创建新问题提问。 +::: + +## 核心包翻译 + +当前翻译状态： + +翻译状态 + +访问[我们的 i18n 控制面板](https://i18n.studiocms.dev)帮助翻译 StudioCMS 核心包。如果您的语言未列出，可直接在控制面板中添加。 + +### 通过 GitHub 贡献 +翻译文件位于 [`packages/studiocms/src/lib/i18n/translations`](https://github.com/withstudiocms/studiocms/tree/main/packages/studiocms/src/lib/i18n/translations/) 目录。英文参考文件为 [`en.json`](https://github.com/withstudiocms/studiocms/blob/main/packages/studiocms/src/lib/i18n/translations/en.json)。 + +无论通过 Crowdin 还是 GitHub 贡献，信息都会自动同步并在下个版本发布。 + + +所有 StudioCMS 包使用 [Crowdin](https://crowdin.com/) 管理翻译。新手可查阅 Crowdin 官网的[译者指南](https://support.crowdin.com/for-translators/)。 + + +翻译添加后，将被集成到 [StudioCMS i18n 配置](https://github.com/withstudiocms/studiocms/blob/main/packages/studiocms/src/lib/i18n/index.ts#L8)中。 + +## 文档翻译 + +StudioCMS 正在积极将文档翻译成多种语言，当前重点语言包括： + +- 西班牙语 +- 法语 +- 德语 +- 韩语 + +衷心感谢社区译者的无私奉献！由于新增语言需要组建团队维护多代码库，我们优先支持已有翻译团队的语言。 + +### 快速入门 + +访问[翻译追踪器](https://i18n.docs.studiocms.dev)查看实时状态： +- 页面更新状态 +- 需要修改的内容 +- 待审核的 PR + +或在 GitHub 直接操作： +1. 按 i18n 标签筛选您语言的 PR +2. 检查拼写和翻译准确性 +3. 提交审核意见 + +### 文档结构 + +文档仓库包含三类可翻译内容： + + + +- ... +- src/ + - ... + - content/ + - docs/ MDX 页面内容（按语言分目录） + - de/ + - en/ + - es/ + - ... + - i18n/ UI 字符串翻译（按语言分文件） + - de.json + - en.json + - es.json + - ... + - starlight-sidebar/ 侧边栏翻译（按语言分文件） + - de.json + - en.json + - es.json + - ... +- astro.config.ts +- package.json +- ... + + + +### 翻译流程 + +按内容类型定位文件： +1. **页面内容**（标题、正文等） + ➤ `src/content/docs/{语言代码}/{页面标识}.mdx` + +2. **共享文本**（搜索框、右侧边栏、"下一篇文章"链接等） + ➤ `src/content/i18n/{语言代码}.json` + +3. **主侧边栏翻译** + ➤ `src/starlight-sidebar/{语言代码}.json` + +当你找到目标文件后，请先查阅[翻译追踪清单](https://i18n.docs.studiocms.dev/)和现有PR——可能已经有人在进行翻译。若确认无人认领，请立刻在Discord的`docs-i18n`频道招呼一声，千万别重复劳动！ + +:::note +不确定某内容是否需要翻译？组件如何工作？请查阅[参考文档](/zh-cn/config-reference/)。 +::: + +:::caution +并非所有页面都开放翻译。我们根据页面稳定性逐步开放，请勿翻译右侧边栏”贡献“区域没有”翻译此页“按钮的页面。 +::: \ No newline at end of file diff --git a/src/content/docs/zh-cn/guides/database/sqld-server.mdx b/src/content/docs/zh-cn/guides/database/sqld-server.mdx new file mode 100644 index 00000000..2b03e476 --- /dev/null +++ b/src/content/docs/zh-cn/guides/database/sqld-server.mdx @@ -0,0 +1,148 @@ +--- +i18nReady: true +title: 自托管 libSQL 服务器 +description: 使用 Docker 托管您的 sqld libSQL 服务器 +--- + +import ReadMore from '~/components/ReadMore.astro' +import { PackageManagers } from 'starlight-package-managers' +import { FileTree, TabItem, Tabs, Steps, Aside } from '@astrojs/starlight/components'; + +`sqld`（SQL 守护进程）是由 Turso 开发的 libSQL 服务器模式。本指南将介绍如何通过 Docker 容器设置和配置 `sqld` 以用于 StudioCMS 项目。 + +通过[官方文档][sql-docs]了解更多关于 `sqld` 的信息 + +## 先决条件 + +- [Docker 和 Docker Compose][docker-docs]（可在服务器或本地运行） +- 已安装 [OpenSSL][openssl-docs] +- StudioCMS CLI（位于 StudioCMS 项目根目录） + +本地测试时的最终文件结构示例： + + + +- docker-compose.yml +- data/ +- keys/ +- my-studiocms-project/ + - astro.config.mjs + - studiocms.config.mjs + - package.json + - src/ + + + +## 生成公私钥对 + +在 `keys` 目录中执行以下命令创建 PKCS#8 编码的 Ed25519 密钥对： +```bash +openssl genpkey -algorithm Ed25519 -out ./libsql.pem +``` + +提取公钥： +```bash +openssl pkey -in ./libsql.pem -pubout -out ./libsql.pub +``` + +这将生成用于 `sqld` 服务器的 PKCS#8 密钥对。 + +## 生成 JWT 令牌 + +进入 StudioCMS 项目目录并执行： + + + +输出包含标准格式和 Base64URL 编码的 JWT 认证令牌，用于 libSQL 身份验证。该令牌有效期为 1 年！ + +### 更新 StudioCMS 的 `.env` 文件 + +```sh +ASTRO_DB_REMOTE_URL=http://localhost:8080 # 指向 Docker 服务器/本地系统 +ASTRO_DB_APP_TOKEN= # 粘贴您的标准 JWT 认证令牌 +``` + +## 配置 Docker 容器 + +在 StudioCMS 项目目录外创建 `docker-compose.yml` 文件。您有两种配置 libSQL 认证的方式： + + + + + +```yml +services: + libsql: + image: ghcr.io/tursodatabase/libsql-server:latest + platform: linux/amd64 + ports: + - "8080:8080" # HTTP API 端口 + - "5001:5001" # gRPC 端口 + environment: + - SQLD_NODE=primary # 主节点模式 + - SQLD_AUTH_JWT_KEY_FILE=/home/.ssh/libsql.pub # 公钥路径 + volumes: + - ./data/libsql:/var/lib/sqld # 数据持久化 + - ./keys/libsql.pub:/home/.ssh/libsql.pub # 挂载公钥 +``` + + + + + +```yml +services: + libsql: + image: ghcr.io/tursodatabase/libsql-server:latest + platform: linux/amd64 + ports: + - "8080:8080" + - "5001:5001" + environment: + - SQLD_NODE=primary + - SQLD_AUTH_JWT_KEY=粘贴您的Base64URL编码JWT令牌 + volumes: + - ./data/libsql:/var/lib/sqld # 数据持久化 +``` + + + + + + + +## 启动服务 + + + +1. 启动 Docker 容器： + 在基础目录（或服务器目录）执行： + ```sh + docker compose up -d + ``` + +2. 同步数据库架构： + 进入 StudioCMS 项目目录执行： + + +3. 完成首次设置： + 遵循新数据库的首次设置流程： + - 参考[入门指南][getting-started] + + :::note 注意 + 若非首次设置 StudioCMS 项目，需在 `studiocms.config.mjs` 中启用 `dbStartPage` 选项 + ::: + + + +## 总结 + +如果你想为 StudioCMS 自托管 libSQL 数据库，`sqld` 是一个可行的选择。只要采用正确方法，部署和运行过程并不复杂。遵循本指南操作，你将为 StudioCMS 项目获得一个安全的 libSQL 服务器。 + +{/* Links */} +[sql-docs]: https://github.com/tursodatabase/libsql/blob/main/docs/USER_GUIDE.md +[docker-docs]: https://docs.docker.com/get-started/get-docker/ +[openssl-docs]: https://docs.openssl.org/3.2/man7/ossl-guide-introduction/#getting-and-installing-openssl +[getting-started]: /zh-cn/start-here/getting-started/#首次设置或数据表结构更新时 \ No newline at end of file diff --git a/src/content/docs/zh-cn/guides/index.mdx b/src/content/docs/zh-cn/guides/index.mdx new file mode 100644 index 00000000..e408e27b --- /dev/null +++ b/src/content/docs/zh-cn/guides/index.mdx @@ -0,0 +1,20 @@ +--- +i18nReady: true +title: 教程与指南 +description: StudioCMS 使用教程和开发指南 +--- + +## 贡献指南 + +- [入门指南](/zh-cn/guides/contributing/getting-started/) - 学习为 StudioCMS 做贡献的基础知识 +- [代码贡献](/zh-cn/guides/contributing/code-contributions/) - 了解如何向 StudioCMS 贡献代码 +- [翻译协作](/zh-cn/guides/contributing/translations/) - 学习如何参与 StudioCMS 的翻译工作 + +## 升级指南 + +- [发布说明](/zh-cn/guides/upgrade/release-notes/) - 从 StudioCMS 更新日志自动生成的发布说明 +- 更多版本特定指南请查看侧边栏导航 + +## 数据库指南 + +- [自托管 libSQL 服务器](/zh-cn/guides/database/sqld-server/) - 使用 Docker 部署您自己的 sqld libSQL 服务器 \ No newline at end of file diff --git a/src/content/docs/zh-cn/guides/upgrade/version-guides/0-1-0-beta-16.mdx b/src/content/docs/zh-cn/guides/upgrade/version-guides/0-1-0-beta-16.mdx new file mode 100644 index 00000000..cf057b29 --- /dev/null +++ b/src/content/docs/zh-cn/guides/upgrade/version-guides/0-1-0-beta-16.mdx @@ -0,0 +1,45 @@ +--- +i18nReady: true +title: "升级指南：0.1.0-beta.16" +description: StudioCMS Beta.16 版本升级说明 +sidebar: + label: 0.1.0-beta.16 + order: 999999 +--- + +import ReadMore from '~/components/ReadMore.astro' +import QuickUpdate from '~/components/QuickUpdate.astro' + + + +## 重大变更 + +- **最低 Astro 版本要求**：升级至 `Astro v5.7.1` +- **密码安全策略更新**： + - 升级后需提示用户更新密码 + - 旧版密码哈希支持将在未来版本移除 + +## 新功能与改进 + +### CLI 工具增强 + +- **新增命令**：`studiocms add <插件名>` + - 快速添加插件到 StudioCMS 项目 + ```bash + studiocms add @studiocms/blog + ``` + +- **安全工具集**：`studiocms crypto [命令]` + - 新增 JWT 生成工具： + ```bash + studiocms crypto gen-jwt ../keys/private.pem + ``` + +- **用户管理修复**： + - 支持通过 CLI 编辑用户信息 + - 基于 Drizzle 架构重构用户权限系统 + +详细了解 CLI 新功能请参阅[命令行工具文档][cli-docs] + +{/* Links */} +[cli-docs]: /zh-cn/how-it-works/cli/ \ No newline at end of file diff --git a/src/content/docs/zh-cn/guides/upgrade/version-guides/0-1-0-beta-17.mdx b/src/content/docs/zh-cn/guides/upgrade/version-guides/0-1-0-beta-17.mdx new file mode 100644 index 00000000..77e44af5 --- /dev/null +++ b/src/content/docs/zh-cn/guides/upgrade/version-guides/0-1-0-beta-17.mdx @@ -0,0 +1,32 @@ +--- +i18nReady: true +title: "升级指南：0.1.0-beta.17" +description: StudioCMS Beta.17 版本升级说明 +sidebar: + label: 0.1.0-beta.17 + order: 999998 +--- + +import ReadMore from '~/components/ReadMore.astro' +import QuickUpdate from '~/components/QuickUpdate.astro' +import { Aside } from '@astrojs/starlight/components' + + + +此版本虽无重大变更，但我们进行了多项优化与问题修复，全面提升了 StudioCMS 的性能和稳定性。 + +## 版本更新摘要 + +- **新增功能** + - 仪表板新增用户反馈系统 +- **问题修复** + - 解决 Astro 字体渲染问题 + - 优化 [`crypto gen-jwt`](/zh-cn/how-it-works/cli/#crypto-gen-jwt) CLI 命令的密钥文件路径检测 +- **性能优化** + - 将 [lodash](https://www.npmjs.com/package/lodash) 替换为 [deepmerge-ts](https://www.npmjs.com/package/deepmerge-ts) 提升性能 + - 优化中间件的 Promise 处理逻辑 + - 改进权限等级处理机制 + + \ No newline at end of file diff --git a/src/content/docs/zh-cn/guides/upgrade/version-guides/0-1-0-beta-18.mdx b/src/content/docs/zh-cn/guides/upgrade/version-guides/0-1-0-beta-18.mdx new file mode 100644 index 00000000..64d567cf --- /dev/null +++ b/src/content/docs/zh-cn/guides/upgrade/version-guides/0-1-0-beta-18.mdx @@ -0,0 +1,33 @@ +--- +i18nReady: true +title: "升级指南：0.1.0-beta.18" +description: StudioCMS Beta.18 版本升级说明 +sidebar: + label: 0.1.0-beta.18 + badge: + text: 新版 + variant: success + order: 999997 +--- + +import ReadMore from '~/components/ReadMore.astro' +import QuickUpdate from '~/components/QuickUpdate.astro' +import { Aside } from '@astrojs/starlight/components' + + + +## 重大变更 + +- 全新的基于 Hook 的插件系统 - 详见更新版[插件文档][plugin-doc] + +## 错误修复 + +- 重构 `gen-jwt` 命令 - 详见更新版[CLI文档][cli-doc] + + + +{/* Links */} +[plugin-doc]: /zh-cn/plugins/ +[cli-doc]: /zh-cn/how-it-works/cli/#crypto-gen-jwt \ No newline at end of file diff --git a/src/content/docs/zh-cn/how-it-works/cli.mdx b/src/content/docs/zh-cn/how-it-works/cli.mdx new file mode 100644 index 00000000..047d6dd4 --- /dev/null +++ b/src/content/docs/zh-cn/how-it-works/cli.mdx @@ -0,0 +1,325 @@ +--- +i18nReady: true +title: "命令行工具集" +description: "StudioCMS CLI 工具使用详解" +sidebar: + order: 2 + badge: + text: 已更新 + variant: success +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 4 +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; +import ReadMore from '~/components/ReadMore.astro'; + +StudioCMS CLI 工具集提供快速创建项目和实用功能操作能力，包含三个核心工具： + +- **[`studiocms`](#studiocms)**：核心功能工具 +- **[`create-studiocms`](#create-studiocms)**：项目脚手架工具 +- **[`@studiocms/upgrade`](#studiocms-upgrade)**：项目升级工具 + +## `studiocms` + +### 完整命令选项 + +```log +用法: studiocms [选项] [命令] + +选项: + -V, --version 显示当前CLI版本 + -h, --help 显示命令帮助 + --color 强制启用彩色输出 + --no-color 禁用彩色输出 + +命令: + add 添加插件 + crypto 安全加密工具 + get-turso 安装Turso CLI + init 初始化StudioCMS项目 + users 用户管理工具 +``` + +### 使用示例 + +在项目根目录执行： + + + + ```sh + npm run studiocms [command] + ``` + + + ```sh + pnpm studiocms [command] + ``` + + + ```sh + yarn studiocms [command] + ``` + + + +### 命令详解 + +#### `add` + +```log +用法: studiocms add <插件名...> + +安装StudioCMS插件到当前项目 + +参数: + plugins 要安装的插件列表 + +选项: + -h, --help 显示帮助信息 +``` + +#### `crypto` + +```log +用法: studiocms crypto [命令] + +安全加密工具集 + +选项: + -h, --help 显示帮助信息 + +子命令: + gen-jwt 生成JWT令牌 +``` + +#### `crypto gen-jwt` + +```log +用法: studiocms crypto gen-jwt [选项] <密钥文件> + +根据PEM密钥文件生成JWT令牌 + +参数: + key-file PEM密钥文件相对路径 (如: `../keys/libsql.pem`) + +选项: + -e, --exp <有效期秒数> 相对签发时间(iat)的有效期 (>=0) + -h, --help 显示帮助信息 +``` + +#### `get-turso` + +下载并安装最新版 [Turso CLI](https://docs.turso.tech/cli/installation) + +:::caution 注意 +Windows 系统需使用 WSL 环境 +::: + +```log +用法: getTurso [选项] + +Turso CLI 安装器 + +选项: + -h, --help 显示帮助信息 +``` + +#### `init` + +```log +用法: studiocms init [选项] + +初始化新安装的StudioCMS项目 + +选项: + -d, --dry-run 模拟运行模式 + --skip-banners 跳过引导提示 + --debug 启用调试模式 + -h, --help 显示帮助信息 +``` + +初始化命令提供交互式设置引导，协助您： + +1. 配置环境文件 (.env)： + - 可基于模板创建 + - 支持交互式配置： + - 新建Turso数据库（非Windows系统） + - 配置OAuth提供商（GitHub/Discord/Google/Auth0） + - 设置加密密钥等关键变量 + +2. 在设置数据库时，该命令会按需自动安装并完成 Turso CLI 的认证流程 + +完整环境变量列表请参阅[环境变量文档][environment-variables] + +#### `users` + +```log +用法: studiocms users [选项] + +用户管理系统工具 + +选项: + -h, --help 显示帮助信息 +``` + +## `create-studiocms` + +### 完整命令选项 + +```log +用法: create-studiocms [选项] [命令] + +选项: + -V, --version 显示当前CLI版本 + -h, --help 显示命令帮助 + --color 强制彩色输出 + --no-color 禁用彩色输出 + +命令: + get-turso 安装Turso CLI + help 显示帮助信息 + interactive* 启动交互式CLI + + * 默认命令 +``` + +### 使用示例 + + + + ```sh + npm create studiocms@latest + ``` + + + ```sh + pnpm create studiocms + ``` + + + ```sh + yarn create studiocms + ``` + + + +`create-studiocms` 工具默认运行于**交互模式**，但您也可以通过命令行参数直接指定项目名称与模板。 + + + + ```sh + npm create studiocms@latest -- --template studiocms/basics --project-name my-project + ``` + + + ```sh + pnpm create studiocms --template studiocms/basics --project-name my-project + ``` + + + ```sh + yarn create studiocms --template studiocms/basics --project-name my-project + ``` + + + +[完整模板列表][templates]可在GitHub仓库查看。 + +使用 `--template` 参数时，CLI会在模板仓库中搜索所有文件夹。例如，`studiocms/basics` 模板对应仓库根目录下 `studiocms` 文件夹中的 `basics` 项目。 + +### 命令详解 + +#### interactive (默认命令) + +```log +用法: create-studiocms interactive [选项] + +启动交互式项目创建向导 [基于clack](https://clack.cc) + +选项: + -t, --template <模板> 使用指定模板 + -r, --template-ref <模板引用> 指定模板版本引用 + -p, --project-name <项目名称> 指定项目名称 + -i, --install 自动安装依赖 + -g, --git 初始化Git仓库 + -y, --yes 跳过所有提示使用默认值 + -n, --no 跳过所有提示使用默认值 + -q, --skip-banners 跳过引导提示 + -d, --dry-run 模拟运行（不实际执行） + -h, --help 显示帮助信息 + --do-not-install 跳过依赖安装 + --do-not-init-git 跳过Git初始化 +``` + +#### `get-turso` + +您可通过 Turso 官方[安装文档][turso-docs]提供的脚本下载并安装最新版本。 + +:::note +注意：根据 Turso 官方要求，Windows 系统必须使用 WSL 环境 +::: + +```log +用法: getTurso [选项] + +Turso CLI 安装器 + +选项: + -h, --help 显示命令帮助信息 +``` + +## `@studiocms-upgrade` + +专用于升级 StudioCMS 运行环境和依赖项的命令行工具。 + +在终端运行此命令时，将在升级 StudioCMS 的同时，同步更新您项目中的官方 Astro 核心模块及所有集成依赖。 + +### 使用示例 + + + + ```sh + npx @studiocms/upgrade + ``` + + + ```sh + pnpm dlx @studiocms/upgrade + ``` + + + ```sh + yarn dlx @studiocms/upgrade + ``` + + + +### 可选参数 + +#### tag (指定版本) + +默认使用 `latest` 版本，支持其他版本标签： + + + + ```sh + npx @studiocms/upgrade beta + ``` + + + ```sh + pnpm dlx @studiocms/upgrade beta + ``` + + + ```sh + yarn dlx @studiocms/upgrade beta + ``` + + + +[turso-docs]: https://docs.turso.tech/cli/installation +[templates]: https://github.com/withstudiocms/templates +[environment-variables]: /zh-cn/start-here/environment-variables/ \ No newline at end of file diff --git a/src/content/docs/zh-cn/how-it-works/index.mdx b/src/content/docs/zh-cn/how-it-works/index.mdx new file mode 100644 index 00000000..2c81bbd9 --- /dev/null +++ b/src/content/docs/zh-cn/how-it-works/index.mdx @@ -0,0 +1,144 @@ +--- +i18nReady: true +title: "核心集成架构" +description: 深入解析 StudioCMS 如何通过其核心组件管理和交付内容 +sidebar: + order: 1 +--- + +# 架构解析 + +StudioCMS 是专为 Astro 构建的强大 CMS 系统，基于 [Astro DB](https://docs.astro.build/zh-cn/guides/astro-db/) 实现内容管理与服务。其设计兼具易用性与灵活性，能处理各种类型的内容需求。 + +扩展 StudioCMS 非常简单！您可以创建自定义插件来增强系统功能。StudioCMS 集成是整个生态系统的基石，为 Astro 项目提供无头 CMS 解决方案。以下是其核心组件的详细解析。 + +## 虚拟模块系统 + +StudioCMS 集成提供多个[虚拟模块](https://vite.dev/guide/api-plugin#virtual-modules-convention)，使您能完全控制动态内容。这些模块主要供内部使用，但开发者也可访问 StudioCMS 数据： + +### 认证虚拟模块 + +| 模块路径 | 功能描述 | +|---------|---------| +| `studiocms:auth/lib/encryption` | 加密工具 | +| `studiocms:auth/lib/password` | 密码管理工具 | +| `studiocms:auth/lib/rate-limit` | 请求限流工具 | +| `studiocms:auth/lib/session` | 会话管理工具 | +| `studiocms:auth/lib/types` | 类型定义 | +| `studiocms:auth/lib/user` | 用户管理工具 | +| `studiocms:auth/utils/authEnvCheck` | 认证环境检查工具 | +| `studiocms:auth/utils/getLabelForPermissionLevel` | 权限标签工具 | + +### 核心虚拟模块 + +| 模块路径 | 功能描述 | +|---------|---------| +| `studiocms:config` | 集成配置解析 | +| `studiocms:version` | 当前版本信息 | +| `studiocms:plugins` | 运行时插件接口 | +| `studiocms:plugin-helpers` | 插件辅助函数 | +| `studiocms:components` | 导出组件库 | +| `studiocms:components/Editors` | 页面编辑器组件 | +| `studiocms:components/dashboard-grid-components` | 仪表板内部组件 | +| `studiocms:components/dashboard-grid-items` | 仪表板网格项组件 | +| `studiocms:component-proxy` | 用户自定义组件代理 | +| `studiocms:lib` | 核心库辅助工具 | + +### SDK 虚拟模块 + +| 模块路径 | 功能描述 | +|---------|---------| +| `studiocms:sdk` | 主 SDK 接口 | +| `studiocms:sdk/cache` | 带缓存的 SDK | +| `studiocms:sdk/types` | SDK 类型定义 | + +### 国际化与渲染 + +| 模块路径 | 功能描述 | +|---------|---------| +| `studiocms:i18n` | 国际化支持 | +| `studiocms:renderer` | 内容渲染器 | +| `studiocms:renderer/config` | 渲染器配置 | +| `studiocms:renderer/current` | 当前渲染上下文 | +| `studiocms:renderer/markdown-remark/css` | Markdown 样式支持 | + +### 图像处理 + +| 模块路径 | 功能描述 | +|---------|---------| +| `studiocms:imageHandler/components` | 图像处理组件 | + +## 路由系统 + +### 仪表板路由（用户界面） + +#### 主路由 + +| 路径 | 功能 | +|------|------| +| `/dashboard/` | 主控制面板 | +| `/dashboard/profile/` | 用户配置管理 | +| `/dashboard/content-management/` | 内容管理界面 | +| `/dashboard/configuration/` | 系统配置中心 | +| `/dashboard/user-management/` | 用户管理系统 | +| `/dashboard/plugins/` | 插件管理中心 | + +#### 认证路由 + +| 路径 | 功能 | +|------|------| +| `/dashboard/login/` | 登录界面 | +| `/dashboard/signup/` | 注册界面 | +| `/dashboard/logout/` | 退出登录 | + +### API 路由（后端接口） + +#### 主接口 + +| 端点路径 | 功能 | +|----------|------| +| `/studiocms_api/dashboard/api-tokens` | API 令牌管理 | +| `/studiocms_api/dashboard/search-list` | 全局搜索接口 | +| `/studiocms_api/dashboard/live-render` | 实时内容预览 | +| `/studiocms_api/dashboard/user-list-items` | 用户列表项 | +| `/studiocms_api/dashboard/editor` | 编辑器数据接口 | +| `/studiocms_api/dashboard/config` | 配置管理接口 | +| `/studiocms_api/dashboard/users` | 用户数据接口 | +| `/studiocms_api/dashboard/profile` | 用户资料接口 | +| `/studiocms_api/dashboard/create-reset-link` | 密码重置链接生成 | +| `/studiocms_api/dashboard/reset-password` | 密码重置处理 | +| `/studiocms_api/dashboard/content/page` | 页面内容操作 | +| `/studiocms_api/dashboard/content/folder` | 文件夹管理 | +| `/studiocms_api/dashboard/plugins` | 插件管理接口 | +| `/studiocms_api/dashboard/create-user` | 用户创建接口 | +| `/studiocms_api/dashboard/update-user-invite` | 用户邀请更新 | + +#### 认证接口 + +| 端点路径 | 功能 | +|----------|------| +| `/studiocms_api/auth/login` | 登录认证 | +| `/studiocms_api/auth/logout` | 退出处理 | +| `/studiocms_api/auth/register` | 注册处理 | +| `/studiocms_api/auth/github` | GitHub 认证 | +| `/studiocms_api/auth/github/callback` | GitHub 回调 | +| `/studiocms_api/auth/discord` | Discord 认证 | +| `/studiocms_api/auth/discord/callback` | Discord 回调 | +| `/studiocms_api/auth/google` | Google 认证 | +| `/studiocms_api/auth/google/callback` | Google 回调 | +| `/studiocms_api/auth/auth0` | Auth0 认证 | +| `/studiocms_api/auth/auth0/callback` | Auth0 回调 | + +#### SDK 接口 + +| 端点路径 | 功能 | +|----------|------| +| `/studiocms_api/sdk/list-pages` | 页面列表获取 | +| `/studiocms_api/sdk/fallback-list-pages.json` | 页面列表回退机制 | +| `/studiocms_api/sdk/update-latest-version-cache` | 版本缓存更新 | + +#### 渲染接口 + +| 端点路径 | 功能 | +|----------|------| +| `/studiocms_api/renderer/render` | 动态内容渲染 | \ No newline at end of file diff --git a/src/content/docs/zh-cn/how-it-works/restapi.mdx b/src/content/docs/zh-cn/how-it-works/restapi.mdx new file mode 100644 index 00000000..c20116c8 --- /dev/null +++ b/src/content/docs/zh-cn/how-it-works/restapi.mdx @@ -0,0 +1,50 @@ +--- +i18nReady: true +title: "REST API 开发指南" +description: "StudioCMS REST API 详细使用说明" +sidebar: + order: 4 +--- + +# 技术导览 + +StudioCMS REST API 作为强大的编程接口，赋能开发者以编程方式管理内容资源。基于 Astro DB 构建的这套 RESTful 接口，为内容操作提供简洁灵活的实现方案。 + +该 API 由 Astro Endpoints 技术驱动，提供标准化接口实现内容交互操作，以下为完整的架构解析： + +## API 令牌认证 + +访问受保护的 API 端点需在 `Authorization` 请求头中携带有效的鉴权令牌. + +**令牌获取路径**：登录 StudioCMS 仪表板 → 用户配置中心 → **API 令牌管理**区域生成新令牌。 + +## 端点体系架构 + +StudioCMS REST API 提供多个功能端点，支持开发者与内容管理系统进行深度交互。这些端点主要服务于 StudioCMS 自身的内部处理流程，同时开放给开发者进行数据操作。以下是完整的 REST API 端点架构： + +### 公共端点 + +这些端点开放访问且无需认证，仅提供 StudioCMS 内容树的只读权限，因此仅支持 GET 请求方法。 + +| 端点路径 | 功能说明 | +|---------|---------| +| `GET /studiocms_api/rest/v1/public/folders/` | 获取所有公开文件夹列表 | +| `GET /studiocms_api/rest/v1/public/folders/[id]` | 获取指定ID的文件夹详情 | +| `GET /studiocms_api/rest/v1/public/pages/` | 获取所有公开页面列表 | +| `GET /studiocms_api/rest/v1/public/pages/[id]` | 获取指定ID的页面详情 | + +### 受保护端点（需认证令牌） + +完整管理接口支持多种HTTP方法： + +| 端点路径 | 支持方法 | 功能说明 | +|---------|---------|---------| +| `/studiocms_api/rest/v1/folders/` | GET, POST | 文件夹列表获取/新建 | +| `/studiocms_api/rest/v1/folders/[id]` | GET, PATCH, DELETE | 指定文件夹操作 | +| `/studiocms_api/rest/v1/pages/` | GET, POST | 页面列表获取/新建 | +| `/studiocms_api/rest/v1/pages/[id]` | GET, PATCH, DELETE | 指定页面操作 | +| `/studiocms_api/rest/v1/pages/[id]/history/` | GET | 页面历史版本列表 | +| `/studiocms_api/rest/v1/pages/[id]/history/[id]` | GET, PUT | 特定历史版本操作 | +| `/studiocms_api/rest/v1/settings/` | GET, PATCH | 系统配置获取/更新 | +| `/studiocms_api/rest/v1/users/` | GET | 用户列表获取 | +| `/studiocms_api/rest/v1/users/[id]` | GET, PATCH, DELETE | 指定用户操作 | \ No newline at end of file diff --git a/src/content/docs/zh-cn/how-it-works/sdk.mdx b/src/content/docs/zh-cn/how-it-works/sdk.mdx new file mode 100644 index 00000000..def6cf15 --- /dev/null +++ b/src/content/docs/zh-cn/how-it-works/sdk.mdx @@ -0,0 +1,294 @@ +--- +i18nReady: true +title: "SDK" +description: 了解 StudioCMS SDK 及其使用方法 +sidebar: + order: 3 +--- + +import ReadMore from '~/components/ReadMore.astro'; + +StudioCMS SDK 是一个强大的工具，允许您以编程方式与 StudioCMS 交互。它提供了一套函数和实用工具，使您能够使用 Astro DB 管理和提供内容。它同时也是 StudioCMS 仪表板的核心基础。 + +## 使用方法 + +StudioCMS SDK 在您的 Astro 项目中作为虚拟模块提供。您可以使用以下语法导入它： + +```ts twoslash +/// +// ---cut--- +import SDK from 'studiocms:sdk'; +// 或者 +import SDKCached from 'studiocms:sdk/cache'; +``` + +`studioCMSSDK` 对象提供了一套允许您与 StudioCMS 交互的函数和实用工具。您可以使用这些函数在 Astro 项目中创建、读取、更新和删除内容。 + +`studioCMSSDKCached` 对象提供了一套函数和实用工具，允许您在 StudioCMS SDK 之上使用缓存层进行交互。您可以使用这些函数在 Astro 项目中缓存内容。 + +## StudioCMS SDK (标准版) + +### `SDK.AUTH` + +`SDK.AUTH` 对象提供了一套管理 Astro 项目身份验证的函数和实用工具。您可以使用这些函数来验证用户、管理会话等。 + +```ts twoslash +/// +// ---cut--- +import SDK from 'studiocms:sdk'; + +const { + oAuth, + permission, + session, + user, +} = SDK.AUTH; +``` + +### `SDK.INIT` + +`SDK.INIT` 对象提供了一套用于在 Astro 项目中初始化 StudioCMS SDK 的函数和实用工具。您可以使用这些函数设置 SDK、进行配置等。 + +```ts twoslash +/// +// ---cut--- +import SDK from 'studiocms:sdk'; + +const { + siteConfig, + ghostUser, +} = SDK.INIT; +``` + +### `SDK.GET` + +`SDK.GET` 对象提供了一套从 Astro DB 检索内容的函数和实用工具。您可以使用这些函数按 ID 获取内容、按类型获取内容等。 + +```ts twoslash +/// +// ---cut--- +import SDK from 'studiocms:sdk'; + +const { + database, + databaseEntry, + databaseTable, + permissionsLists, + packagePages, +} = SDK.GET; +``` + +### `SDK.POST` + +`SDK.POST` 对象提供了一套在 Astro DB 中创建内容的函数和实用工具。您可以使用这些函数按类型创建内容、按 ID 创建内容等。 + +```ts twoslash +/// +// ---cut--- +import SDK from 'studiocms:sdk'; + +const { + databaseEntry, + databaseEntries, +} = SDK.POST; +``` + +### `SDK.UPDATE` + +`SDK.UPDATE` 对象提供了一套更新 Astro DB 中内容的函数和实用工具。您可以使用这些函数按 ID 更新内容、按类型更新内容等。 + +```ts twoslash +/// +// ---cut--- +import SDK from 'studiocms:sdk'; + +const { + page, + pageContent, + tags, + categories, + permissions, + siteConfig, + folder, +} = SDK.UPDATE; +``` + +### `SDK.DELETE` + +`SDK.DELETE` 对象提供了一套从 Astro DB 中删除内容的函数和实用工具。您可以使用这些函数按 ID 删除内容、按类型删除内容等。 + +```ts twoslash +/// +// ---cut--- +import SDK from 'studiocms:sdk'; + +const { + page, + pageContent, + pageContentLang, + tags, + categories, + permissions, + diffTracking, + folder, + user, +} = SDK.DELETE; +``` + +### `SDK.db` + +`SDK.db` 对象提供了一套直接与 Astro DB 交互的函数和实用工具。您可以使用这些函数查询数据库、运行自定义查询等。 + +```ts twoslash +/// +// ---cut--- +import SDK from 'studiocms:sdk'; + +const { db } = SDK; +``` + +有关如何使用 `db` 的更多信息，请查看 [Astro DB 指南](https://docs.astro.build/zh-cn/guides/astro-db/) + +### `SDK.REST_API` + +`SDK.REST_API` 对象提供了一套 REST API 用来与 StudioCMS 和 Astro DB 交互的函数和实用工具。 + +```ts twoslash +/// +// ---cut--- +import SDK from 'studiocms:sdk'; + +const { + tokens: { + get: getToken, + new: newToken, + delete: deleteToken, + verify: verifyToken, + }, +} = SDK.REST_API; +``` + +### `SDK.diffTracking` + +`SDK.diffTracking` 对象提供了一套跟踪 Astro DB 中变更的函数和实用工具。您可以使用这些函数跟踪内容变更、用户变更等。 + +```ts twoslash +/// +// ---cut--- +import SDK from 'studiocms:sdk'; + +const { + insert, + clear, + get, + revertToDiff +} = SDK.diffTracking; +``` + +### 实用工具函数 + +StudioCMS SDK 还提供了一套可与 SDK 交互的实用工具函数。这些函数包括： + +```ts twoslash +/// +// ---cut--- +import SDK from 'studiocms:sdk'; + +const { + addPageToFolderTree, + findNodeById, + findNodeByPath, + findNodesAlongPath, + getFullPath, + parseIdNumberArray, + parseIdStringArray, + generateRandomIDNumber, + generateToken, + testToken, + combineRanks, + verifyRank, + buildFolderTree, + getAvailableFolders, + clearUserReferences, + collectCategories, + collectTags, + collectPageData, + collectUserData, + generateRandomPassword, +} = SDK; +``` + +## StudioCMS SDK (缓存版) + +StudioCMS SDK 还提供了一个具有部分标准 SDK 功能并在其基础上增加缓存层的缓存版本。您可以使用以下语法导入缓存版 SDK： + +```ts twoslash +/// +// ---cut--- +import SDKCached from 'studiocms:sdk/cache'; +``` + +### `SDKCached.GET` + +`SDKCached.GET` 对象提供了一套带缓存的从 Astro DB 检索内容的函数和实用工具。您可以使用这些函数按 ID 获取内容、按类型获取内容等。 + +```ts twoslash +/// +// ---cut--- +import SDKCached from 'studiocms:sdk/cache'; + +const { + page, + pages, + siteConfig, + latestVersion, + folderTree, + pageFolderTree, + folderList, + folder, +} = SDKCached.GET; +``` + +### `SDKCached.CLEAR` + +`SDKCached.CLEAR` 对象提供了一套用于清除缓存版 SDK 中缓存的函数和实用工具。您可以使用这些函数清除特定内容类型的缓存、清除特定内容 ID 的缓存等。 + +```ts twoslash +/// +// ---cut--- +import SDKCached from 'studiocms:sdk/cache'; + +const { + page, + pages, + latestVersion, + folderTree, + folderList, +} = SDKCached.CLEAR; +``` + +### `SDKCached.UPDATE` + +`SDKCached.UPDATE` 对象提供了一套带缓存的更新 Astro DB 中内容的函数和实用工具。您可以使用这些函数按 ID 更新内容、按类型更新内容等。 + +```ts twoslash +/// +// ---cut--- +import SDKCached from 'studiocms:sdk/cache'; + +const { + page, + siteConfig, + latestVersion, + folderTree, + folderList, + folder, +} = SDKCached.UPDATE; +``` + +### `SDKCached.db` + +这是指向标准 SDK `db` 对象的直接通路。 + +更多信息请参见 [`SDK.db`](#sdkdb) +``` \ No newline at end of file diff --git a/src/content/docs/zh-cn/index.mdx b/src/content/docs/zh-cn/index.mdx new file mode 100644 index 00000000..cc387429 --- /dev/null +++ b/src/content/docs/zh-cn/index.mdx @@ -0,0 +1,97 @@ +--- +i18nReady: true +title: StudioCMS 文档 +description: 开始使用 StudioCMS 进行构建 +template: splash +editUrl: false +lastUpdated: false +hero: + tagline: 指南和资源助您学习使用 StudioCMS + image: + alt: StudioCMS 徽标 + dark: ../../../assets/logos/studioCMS.png + light: ../../../assets/logos/studioCMS-dark.png + actions: + - text: 开始使用 + link: /zh-cn/start-here/getting-started/ + icon: right-arrow + variant: primary + - text: GitHub 仓库 + link: https://github.com/withstudiocms/studiocms/ + icon: github +--- + +import { CardGrid, LinkButton } from '@astrojs/starlight/components'; +import Youtube from '~/components/Youtube.astro'; +import Card from '~/components/landing/Card.astro'; +import ListCard from '~/components/landing/ListCard.astro'; +import SplitCard from '~/components/landing/SplitCard.astro'; +import { Center } from 'studiocms:ui/components'; + + + + + + + + ```sh + # 创建新的 Astro 项目 + pnpm create studiocms@latest + + # 启动开发服务器 + cd my-studiocms-project + pnpm dev + ``` + +
+ 有关所需环境变量的更多信息，请参阅 [环境变量][environment-variables] 页面。 + + 如需更深入的指南，请查看 [入门指南][getting-started]。 + + 需要 libSQL 数据库？请了解 [Turso][turso]。 +
+ + + + + - [入门指南][getting-started] + - [环境变量][environment-variables] + - [为何选择 StudioCMS？][why-studiocms] + - [理解 StudioCMS][how-it-works] + + + + - [使用 SDK][using-the-sdk] + - [使用 REST API][using-rest-api] + - [查找和使用插件][package-catalog] + - [了解插件 API][plugin-api] + + + + +
+
+ 想参与 StudioCMS 社区吗？ + + + 加入我们的 Discord！ + +
+
+ +{/* Links */} +[environment-variables]: /zh-cn/start-here/getting-started/ +[getting-started]: /zh-cn/start-here/getting-started/ +[turso]: https://tur.so/studiocms +[why-studiocms]: /zh-cn/start-here/why-studiocms/ +[how-it-works]: /zh-cn/how-it-works/ +[using-the-sdk]: /zh-cn/how-it-works/sdk/ +[using-rest-api]: /zh-cn/how-it-works/restapi/ +[package-catalog]: /zh-cn/package-catalog/ +[plugin-api]: /zh-cn/plugins/ \ No newline at end of file diff --git a/src/content/docs/zh-cn/package-catalog/community-plugins/web-vitals.mdx b/src/content/docs/zh-cn/package-catalog/community-plugins/web-vitals.mdx new file mode 100644 index 00000000..1b5113a4 --- /dev/null +++ b/src/content/docs/zh-cn/package-catalog/community-plugins/web-vitals.mdx @@ -0,0 +1,76 @@ +--- +i18nReady: true +title: "@astrojs/web-vitals" +type: integration +catalogEntry: astrojs-web-vitals +description: "将网页指标集成到 StudioCMS 仪表盘" +sidebar: + badge: + text: '插件' + variant: 'tip' +--- + +import { PackageManagers } from 'starlight-package-managers' +import Gallery from '~/components/Gallery.astro'; +import { webVitalsImages } from "~/assets/index.ts"; +import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'; + +# 简介 + +该 Astro 集成支持跟踪真实世界的网站性能数据并将数据存储在 Astro DB 中。这些数据会在 StudioCMS 仪表盘中展示您的网站随时间变化的真实性能指标。 + +## 安装步骤 + + +{/* */} + +1. 安装软件包并将其添加到 Astro 配置中： + + + +2. 将新配置推送到您的远程数据库： + + + +{/* */} + + +{/* */} + +1. 使用以下命令安装软件包： + + + +2. 将 `@astrojs/web-vitals` 添加到您的 Astro 配置文件： + + ```ts twoslash title="astro.config.mjs" {12} ins={4, 13} + import node from '@astrojs/node'; + import studioCMS from 'studiocms'; + import db from '@astrojs/db'; + import webVitals from '@astrojs/web-vitals'; // 导入网页指标集成 + import { defineConfig } from 'astro/config'; + + export default defineConfig({ + site: 'https://demo.studiocms.dev/', + output: 'server', + adapter: node({ mode: "standalone" }), + integrations: [ + db(), // 必须项 + webVitals(), // 启用网页指标跟踪 + studioCMS(), // StudioCMS 核心集成 + ], + }); + ``` + +3. 将新配置推送到您的远程数据库： + + + +{/* */} + + + + +{/* ## Gallery Demo + + */} \ No newline at end of file diff --git a/src/content/docs/zh-cn/package-catalog/index.mdx b/src/content/docs/zh-cn/package-catalog/index.mdx new file mode 100644 index 00000000..93d0a238 --- /dev/null +++ b/src/content/docs/zh-cn/package-catalog/index.mdx @@ -0,0 +1,28 @@ +--- +i18nReady: true +title: 包目录 +description: "包目录是由 StudioCMS 或其社区提供的软件包集合。" +--- + +import PackageCatalog from '~/components/PackageCatalog.astro' +import { Badge } from '@astrojs/starlight/components'; + +包目录是 StudioCMS 或其社区成员提供的软件包集合，这些软件包默认不包含在 StudioCMS 中。此处列出的所有软件包都经过 StudioCMS 团队或其贡献者的验证和测试。 + +标记为的软件包是用于扩展 StudioCMS 或其仪表板功能的包。 + +插件可能同时标记为，这表示该插件仍处于早期开发阶段，其内部实现可能随时发生重大变更。此类插件也可能尚未准备好用于生产环境。 + +标记为的软件包可独立安装使用，无需依赖 StudioCMS 环境。 + +## 包目录分类 + +### StudioCMS 官方包目录 +--- + + + +### 社区包目录 +--- + + \ No newline at end of file diff --git a/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-blog.mdx b/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-blog.mdx new file mode 100644 index 00000000..71de80d8 --- /dev/null +++ b/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-blog.mdx @@ -0,0 +1,47 @@ +--- +i18nReady: true +title: "@studiocms/blog" +type: integration +catalogEntry: studiocms-blog +description: "StudioCMS 博客集成插件" +sidebar: + badge: + text: '插件' + variant: 'tip' +--- + +import { PackageManagers } from 'starlight-package-managers' +import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'; + +# 简介 + +该插件为 Astro 项目提供 StudioCMS 博客功能及前端界面，支持从 StudioCMS 仪表盘创建、编辑和管理博客文章。 + +## 安装步骤 + +1. 使用以下命令安装软件包： + + + +2. 在 StudioCMS 配置中添加该插件： + + ```ts twoslash title="studiocms.config.mjs" {2, 6} + import { defineStudioCMSConfig } from 'studiocms/config'; + import blog from '@studiocms/blog'; // 导入博客插件 + + export default defineStudioCMSConfig({ + plugins: [ + blog(), // 启用博客功能 + ], + }); + ``` +## 核心功能 + +### 此插件能做什么 + +该插件将向 StudioCMS 控制的前端应用添加以下路由： + +- `/[...slug]` - 通用内容路由（用于常规页面） +- `/blog` - 博客主页（文章列表） +- `/blog/[slug]` - 单篇博客文章详情页 +- `/rss.xml` - 自动生成的博客 RSS 订阅源 \ No newline at end of file diff --git a/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-devapps.mdx b/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-devapps.mdx new file mode 100644 index 00000000..2eb062a1 --- /dev/null +++ b/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-devapps.mdx @@ -0,0 +1,130 @@ +--- +i18nReady: true +title: "@studiocms/devapps" +type: integration +catalogEntry: studiocms-devapps +description: "在 Astro 开发模式下可用的实用工具集合" +sidebar: + badge: + text: '公开可用' + variant: 'caution' +--- + +import { PackageManagers } from 'starlight-package-managers' +import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'; + +# 简介 + +这是一个在 Astro 开发模式下可用的实用工具集合。 + +## 安装方法 + + + +1. 使用以下命令安装软件包并添加到 astro 配置： + + + +2. 按照下文 [示例配置](#示例配置) 更新配置文件 +{/* */} + + +{/* */} +1. 使用以下命令安装软件包： + + + +2. 将 `@studiocms/devapps` 添加到您的 astro 配置文件： + + ```ts twoslash title="astro.config.mjs" ins={3, 9} + import { defineConfig } from 'astro/config'; + import db from '@astrojs/db'; + import devApps from '@studiocms/devapps'; + + export default defineConfig({ + site: "https://example.com", + integrations: [ + db(), + devApps(), + ], + }); + ``` +{/* */} + + + +## 使用说明 + +所有工具仅在 `astro dev` 开发模式下可用，不会出现在生产部署中！ + +### 示例配置 + +```ts twoslash title="astro.config.mjs" {2, 8} ins={3, 9} +import { defineConfig } from 'astro/config'; +import db from '@astrojs/db'; +import devApps from '@studiocms/devapps'; + +export default defineConfig({ + site: "https://example.com", + integrations: [ + db(), // 必须项 + devApps(/* 配置选项见下文 */), + ], +}); +``` + +### 配置选项 + +以下是 `devApps` 集成的完整可用选项，其中显示了默认值。**所有选项均为可选**。 + +```ts twoslash +import devApps from '@studiocms/devapps'; +devApps({ +// ---cut--- +endpoint: '_studiocms-devapps', +verbose: false, +appsConfig: { + libSQLViewer: true, + wpImporter: true, +}, +// ---cut-after--- +}) +``` + +## 可用工具 + +### libSQL 查看器 + +在浏览器中查看 libSQL 数据库表的开发工具。该工具依赖于 `@astrojs/db` 的远程数据库连接凭证。 + +#### 环境要求 + +需设置以下环境变量（同时用于 `@astrojs/db`）： +- **`ASTRO_DB_REMOTE_URL`** +- **`ASTRO_DB_APP_TOKEN`** + +#### 功能预览 + +- 工具栏应用 (收缩状态) + +![Astro 开发工具栏应用](~/assets/devapps/devapps-1-toolbar-app-closed.png) + +- 工具栏应用 (展开状态) + +![Astro 开发工具栏应用 (展开)](~/assets/devapps/devapps-1-toolbar-app-expanded.png) + +### WordPress 导入器 + +将 WordPress 文章和页面导入到 StudioCMS 数据库的开发工具。 + +#### 环境要求 + +- StudioCMS 集成 +- WordPress 安装 +- `@studiocms/blog` (可选：用于将文章导入到博客系统) + +#### 功能预览 + +- 工具栏应用 + +![Astro 导入器界面](~/assets/devapps/devapps-2-importer.png) \ No newline at end of file diff --git a/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-markdoc.mdx b/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-markdoc.mdx new file mode 100644 index 00000000..021b15ea --- /dev/null +++ b/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-markdoc.mdx @@ -0,0 +1,37 @@ +--- +i18nReady: true +title: "@studiocms/markdoc" +type: integration +catalogEntry: studiocms-markdoc +description: "StudioCMS MarkDoc 集成插件" +sidebar: + badge: + text: '插件' + variant: 'tip' +--- + +import { PackageManagers } from 'starlight-package-managers' +import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'; + +# 简介 + +此插件为 StudioCMS 添加 MarkDoc 文件格式支持。 + +## 安装步骤 + +1. 使用以下命令安装软件包： + + + +2. 您的 StudioCMS 配置文件中应当已集成 `@studiocms/markdoc` 模块。： + + ```ts twoslash title="studiocms.config.mjs" {2, 6} + import { defineStudioCMSConfig } from 'studiocms/config'; + import markdoc from '@studiocms/markdoc'; + + export default defineStudioCMSConfig({ + plugins: [ + markdoc(), + ], + }); + ``` diff --git a/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-mdx.mdx b/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-mdx.mdx new file mode 100644 index 00000000..12920072 --- /dev/null +++ b/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-mdx.mdx @@ -0,0 +1,37 @@ +--- +i18nReady: true +title: "@studiocms/mdx" +type: integration +catalogEntry: studiocms-mdx +description: "StudioCMS MDX 集成插件" +sidebar: + badge: + text: '插件' + variant: 'tip' +--- + +import { PackageManagers } from 'starlight-package-managers' +import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'; + +# 简介 + +此插件为 StudioCMS 添加 MDX 文件格式支持。 + +## 安装步骤 + +1. 使用以下命令安装软件包： + + + +2. 在 StudioCMS 配置中添加该插件： + + ```ts twoslash title="studiocms.config.mjs" {2, 6} + import { defineStudioCMSConfig } from 'studiocms/config'; + import mdx from '@studiocms/mdx'; + + export default defineStudioCMSConfig({ + plugins: [ + mdx(), + ], + }); + ``` \ No newline at end of file diff --git a/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-wysiwyg.mdx b/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-wysiwyg.mdx new file mode 100644 index 00000000..ba3d87c2 --- /dev/null +++ b/src/content/docs/zh-cn/package-catalog/studiocms-plugins/studiocms-wysiwyg.mdx @@ -0,0 +1,37 @@ +--- +i18nReady: true +title: "@studiocms/wysiwyg" +type: integration +catalogEntry: studiocms-wysiwyg +description: "轻松为 StudioCMS 项目添加所见即所得编辑器！" +sidebar: + badge: + text: '实验性' + variant: 'danger' +--- + +import { PackageManagers } from 'starlight-package-managers' +import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'; + +# 简介 + +此插件让您能够轻松地为 StudioCMS 项目添加所见即所得编辑器！ + +## 安装步骤 + +1. 使用以下命令安装软件包： + + + +2. 在 StudioCMS 配置中添加该插件： + + ```ts twoslash title="studiocms.config.mjs" {2, 6} + import { defineStudioCMSConfig } from 'studiocms/config'; + import wysiwyg from '@studiocms/wysiwyg'; + + export default defineStudioCMSConfig({ + plugins: [ + wysiwyg(), + ], + }); + ``` \ No newline at end of file diff --git a/src/content/docs/zh-cn/plugins/extended.mdx b/src/content/docs/zh-cn/plugins/extended.mdx new file mode 100644 index 00000000..dccd561b --- /dev/null +++ b/src/content/docs/zh-cn/plugins/extended.mdx @@ -0,0 +1,336 @@ +--- +i18nReady: true +title: 构建高效插件 +description: StudioCMS 插件开发指南 +sidebar: + order: 2 + badge: + text: 已更新 + variant: success +--- + +import ReadMore from '~/components/ReadMore.astro' +import { FileTree } from '@astrojs/starlight/components' + +# 插件开发指南 + +开发 StudioCMS 插件是扩展平台功能的关键方式，它提供了一种简单灵活的方法来增强项目能力。本文将通过基础示例演示如何创建和开发 StudioCMS 插件。 + +## 准备工作 + +要创建 StudioCMS 插件，需遵循以下基础文件结构示例： + + + +- package.json +- src + - index.ts + - routes + - [...slug].astro + - dashboard-grid-items + - MyPluginGridItem.astro + + + +## 创建插件 + +请在核心的 `src/index.ts` 文件中定义您的 StudioCMS 插件。以下示例演示如何创建包含 Astro 集成的插件，实现基础博客功能： + +```ts twoslash title="index.ts" +import { definePlugin } from 'studiocms/plugins'; +import { AstroIntegration } from 'astro'; +import { addVirtualImports, createResolver } from 'astro-integration-kit'; + +// 定义插件选项接口 +interface Options { + route: string; +} + +export function studioCMSPageInjector(options: Options) { + // 解析当前文件路径 + const { resolve } = createResolver(import.meta.url); + + // 定义 Astro 集成 + function myIntegration(options: Options): AstroIntegration { + const route = `/${options?.route || 'my-plugin'}`; + + return { + name: 'my-astro-integration', + hooks: { + "astro:config:setup": (params) => { + const { injectRoute } = params; + + // 注入插件路由 + injectRoute({ + entrypoint: resolve('./routes/[...slug].astro'), + pattern: `/${route}/[...slug]`, + prerender: false, + }) + + // 添加虚拟导入 + addVirtualImports(params, { + name: 'my-astro-integration', + imports: { + 'myplugin:config': ` + export const options = ${JSON.stringify({ route })}; + export default options; + `, + } + }) + } + } + } + } + + // 定义 StudioCMS 插件 + return definePlugin({ + identifier: 'my-plugin', // 唯一标识符 + name: 'My Plugin', // 插件名称 + studiocmsMinimumVersion: '0.1.0-beta.18', // 兼容最低版本 + hooks: { + // 添加 Astro 集成 + 'studiocms:astro:config': ({ addIntegrations }) => { + addIntegrations(myIntegration(options)); + }, + // 插件配置设置 + 'studiocms:config:setup': ({ setDashboard, setFrontend, setRendering }) => { + // 仪表板网格项配置 + setDashboard({ + dashboardGridItems: [ + { + name: 'example', // 组件名称 + span: 2, // 网格跨度 + variant: 'default', // 显示变体 + requiresPermission: 'editor', // 所需权限 + header: { title: '示例', icon: 'bolt' }, // 标题和图标 + body: { + html: '', // 占位HTML + components: { + // 实际渲染组件 + examplegriditem: resolve('./dashboard-grid-items/MyPluginGridItem.astro') + } + } + } + ], + }); + + // 前端导航配置 + setFrontend({ + frontendNavigationLinks: [{ label: '我的插件', href: options?.route || 'my-plugin' }], + }); + + // 页面类型配置 + setRendering({ + pageTypes: [{ identifier: 'my-plugin', label: '博客文章(我的插件)' }], + }) + } + } + }); +} +``` + +上述示例定义了一个包含 Astro 集成的 StudioCMS 插件，用于构建基础博客系统。该插件通过以下核心功能扩展 StudioCMS： + +深入了解 Astro 集成开发，请参阅 [Astro 集成套件](https://astro-integration-kit.netlify.app/) 和 [Astro 集成文档](https://docs.astro.build/zh-cn/reference/integrations-reference/) + +## 路由实现示例 + +在 `src/routes/[...slug].astro` 文件中定义插件路由时，需要使用特殊语法 `---` 划分两个功能区： + +- 第一组 `---` 标记的顶部区域称为 ​Frontmatter​ +- 第二组 `---` 之后的区域是 ​模板渲染区​ + +```ts twoslash title="​Frontmatter​" +// @noErrors +// @filename: plugin.d.ts +declare module 'myplugin:config' { + export const options: { route: string }; + export default options; +} +// ---cut--- +// @filename: Frontmatter.ts +/// +/// +import type { AstroGlobal } from 'astro'; +const Astro: AstroGlobal = {}; +// ---cut--- +import { StudioCMSRenderer } from 'studiocms:renderer'; +import sdk from 'studiocms:sdk'; +import config from 'myplugin:config'; + +// 生成完整路由路径 +const makeRoute = (slug: string) => { + return `/${config.route}/${slug}`; +} + +// 获取 'my-plugin' 类型的所有页面 +const pages = await sdk.GET.packagePages('my-plugin'); + +// 获取当前 URL slug +const { slug } = Astro.params; + +// 查找匹配页面 +const page = pages.find((page) => page.slug === slug || ''); +``` + +```astro title="模板层" +{ + slug && page ? ( +
+

{page.title}

+ +
+ ) : ( +
+

我的插件

+
    + {pages.length > 0 && pages.map((page) => ( +
  • + {page.title} +
    • + ))} +
+
+ ) +} +``` + +此[动态路由](https://docs.astro.build/zh-cn/guides/routing/#dynamic-routes)在没有 slug 参数时显示文章列表，有 slug 时显示具体文章内容。 + +## 仪表板组件示例 + +在 `src/dashboard-grid-items/MyPluginGridItem.astro` 中创建仪表板组件： + +```astro title="MyPluginGridItem.astro" +--- +import { StudioCMSRoutes } from 'studiocms:lib'; +import sdk from 'studiocms:sdk'; + +// 获取 'my-plugin' 类型的所有页面 +const pages = await sdk.GET.packagePages('my-plugin'); + +// 筛选最近30天更新的前5篇文章 +const recentlyUpdatedPages = pages + .filter((page) => { + const now = new Date(); + const thirtyDaysAgo = new Date(now.setDate(now.getDate() - 30)); + return new Date(page.updatedAt) > thirtyDaysAgo; + }) + .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()) + .slice(0, 5); +--- + +
+

最近更新

+
    + {recentlyUpdatedPages.length > 0 && recentlyUpdatedPages.map((page) => ( +
  • + + + {page.title} + +
    • + ))} +
+
+``` + +该示例为插件定义了一个网格项目，用于展示最近30天内更新的5个内容页面。该网格项目包含指向每条内容管理编辑页面的链接列表。 + +## FrontendNavigationLinks 导航组件集成 + +若需在项目中直接使用 StudioCMS 内置导航辅助工具（例如 `@studiocms/blog` 插件的实现方式），可通过创建自定义的 `Navigation.astro` 组件实现： + +```astro title="Navigation.astro" +--- +import { StudioCMSRoutes } from 'studiocms:lib'; +import studioCMS_SDK from 'studiocms:sdk/cache'; +import { frontendNavigation } from 'studiocms:plugin-helpers'; + +// 组件属性定义 +interface Props { + topLevelLinkCount?: number; +}; + +// 默认显示3个顶级导航项 +const { topLevelLinkCount = 3 } = Astro.props; + +// 获取站点标题 +const config = (await studioCMS_SDK.GET.siteConfig()).data; + +// 获取站点 URL +const { title } = config || { title: 'StudioCMS' }; + +// 基础URL +const { mainLinks: { baseSiteURL } } = StudioCMSRoutes; + +// 导航项类型 +type LinkProps = { + text: string; + href: string; +}; + +// 获取导航链接 +const links: LinkProps[] = await frontendNavigation(); +--- +{/* 无下拉菜单的导航模式 */} +{ ( links.length < topLevelLinkCount || links.length === topLevelLinkCount ) && ( +
+
{title}
+
+ +
+ { + links.map(({ text, href }) => ( + {text} + )) + } +
+
+ { + links.map(({ text, href }) => ( + {text} + )) + } +
+) } + +{/* 带下拉菜单的导航模式 */} +{ links.length > topLevelLinkCount && ( +
+
{title}
+ +
+ +
+ { + links.map(({ text, href }) => ( + {text} + )) + } +
+
+ { + links.slice(0, topLevelLinkCount).map(({ text, href }) => ( + {text} + )) + } +
+ +
+ { links.slice(topLevelLinkCount).map(({ text, href }) => ( + {text} + )) } +
+
+
+) } +``` + +上述示例定义了一个自定义的 `Navigation.astro` 组件，该组件利用 StudioCMS 内置的导航辅助工具为项目创建导航菜单。此组件包含： + +- 主站点URL链接 +- 首页导航项 +- 所有配置为在导航中显示的其他页面链接 + +您只需添加自定义样式，即可获得一个功能完备的导航菜单，完美集成 StudioCMS 的内置导航辅助系统。 \ No newline at end of file diff --git a/src/content/docs/zh-cn/plugins/index.mdx b/src/content/docs/zh-cn/plugins/index.mdx new file mode 100644 index 00000000..7c617811 --- /dev/null +++ b/src/content/docs/zh-cn/plugins/index.mdx @@ -0,0 +1,131 @@ +--- +i18nReady: true +title: 插件基础指南 +description: StudioCMS 插件工作原理详解 +sidebar: + order: 1 + badge: + text: 已更新 + variant: success +--- + +import ReadMore from '~/components/ReadMore.astro' + +# 核心概念解析 + +StudioCMS 插件是扩展平台功能的核心机制，提供了一种简单灵活的方式来增强项目能力。本文将深入解析 StudioCMS 插件的工作原理和基础结构。 + +## 什么是插件？ + +StudioCMS 插件类似于 Astro 集成，但在函数对象上附加了额外元数据。这些元数据用于确定插件的加载和使用方式。插件通过添加新功能或修改现有行为来扩展 StudioCMS 的能力。 + +### StudioCMS 插件接口定义 + +```ts +interface StudioCMSPlugin { + identifier: string; // 插件唯一标识符 + name: string; // 插件显示名称 + studiocmsMinimumVersion: string; // 要求的最低 StudioCMS 版本 + hooks: { + // Astro 配置钩子 + 'studiocms:astro:config': (params: { + logger: AstroIntegrationLogger; // 日志记录器 + addIntegrations: (args_0: AstroIntegration | AstroIntegration[]) => void; // 添加集成 + }) => void | Promise; + + // 配置初始化钩子 + 'studiocms:config:setup': (params: { + logger: AstroIntegrationLogger; + // 设置站点地图 + setSitemap: (params: { + triggerSitemap?: boolean | undefined; + sitemaps?: { + pluginName: string; + sitemapXMLEndpointPath: string | URL; + }[] | undefined; + }) => void; + // 设置仪表板 + setDashboard: (params: { + dashboardGridItems?: GridItemInput[] | undefined; + dashboardPages?: { + user?: (...)[] | undefined; + admin?: (...)[] | undefined; + } | undefined; + settingsPage?: { + fields: (...)[]; + endpoint: string; + } | undefined; + }) => void; + // 设置前端 + setFrontend: (params: { + frontendNavigationLinks?: { + label: string; // 导航标签 + href: string; // 链接地址 + }[] | undefined; + }) => void; + // 设置渲染 + setRendering: (params: { + pageTypes?: { + label: string; // 页面类型标签 + identifier: string; // 唯一标识符 + description?: string | undefined; // 描述 + fields?: (...)[] | undefined; // 字段定义 + pageContentComponent?: string | undefined; // 内容组件 + rendererComponent?: string | undefined; // 渲染组件 + apiEndpoint?: string | undefined; // API端点 + }[] | undefined; + }) => void; + }) => void | Promise; + } +} +``` + +### 插件定义规范 + +定义 StudioCMS 插件需创建符合上述接口的对象，必须包含以下属性： + +- `identifier`: 插件的唯一标识符（通常取自 package.json） +- `name`: 在 StudioCMS 仪表板中显示的插件名称 +- `studiocmsMinimumVersion`: 插件所需的最低 StudioCMS 版本 + +以下是一个完整的 StudioCMS 插件定义示例，包含所有必需属性并通过 Astro 集成实现自定义逻辑： + +```ts twoslash title="my-plugin.ts" +import { definePlugin } from 'studiocms/plugins'; +import { AstroIntegration } from 'astro'; + +// 定义插件和集成的选项接口 +interface Options { + foo: string; // 示例配置项 +} + +// 创建 Astro 集成 +const myIntegration = (options: Options): AstroIntegration => ({ + name: 'my-astro-integration', + hooks: { + "astro:config:setup": () => { + console.log('我的 Astro 集成已启动！'); + } + } +}); + +// 定义 StudioCMS 插件 +export const myPlugin = (options: Options) => definePlugin({ + identifier: 'my-plugin', // 插件标识符 + name: '我的插件', // 插件显示名称 + studiocmsMinimumVersion: '0.1.0-beta.18', // 最低兼容版本 + hooks: { + // Astro 配置钩子 + 'studiocms:astro:config': ({ addIntegrations }) => { + addIntegrations(myIntegration(options)) // 推荐添加集成 + } + } +}); +``` + +在以下示例中，我们定义了一个名为 `My Plugin` 的 StudioCMS 插件，该插件要求 StudioCMS 版本为 `0.1.0-beta.18` 或更高。该插件还提供了 Astro 集成功能，在触发 `astro:config:setup` 钩子时向控制台输出日志信息： + +深入了解插件开发实践，请参阅[高效插件开发指南][extended-plugins] + +{/* Links */} +[extended-plugins]: /zh-cn/plugins/extended/ \ No newline at end of file diff --git a/src/content/docs/zh-cn/start-here/configuration.mdx b/src/content/docs/zh-cn/start-here/configuration.mdx new file mode 100644 index 00000000..b471feb1 --- /dev/null +++ b/src/content/docs/zh-cn/start-here/configuration.mdx @@ -0,0 +1,87 @@ +--- +i18nReady: true +title: "StudioCMS 配置" +description: "定义 StudioCMS 配置的选项" +sidebar: + order: 3 +--- + +import { FileTree } from '@astrojs/starlight/components'; +import ReadMore from '~/components/ReadMore.astro'; + +# 可用配置选项 + +有两种方式配置 StudioCMS 集成。以下示例展示了如何在 `astro.config.mjs` 文件或专用的 `studiocms.config.mjs` 文件中进行配置。 + + +本页面展示如何定义 StudioCMS 配置及其位置。有关配置选项的完整参考，请查看[配置参考文档][reference-page]。 + + +## 使用 `astro.config.mjs` 文件 + +```ts twoslash title="astro.config.mjs" +import db from '@astrojs/db'; +import node from '@astrojs/node'; +import studioCMS from 'studiocms'; +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + site: 'https://demo.studiocms.dev/', + output: 'server', + adapter: node({ mode: "standalone" }), + integrations: [ + db(), + studioCMS({ + dbStartPage: false, + // 其他配置选项 + }), + ], +}); +``` + +## 使用 `studiocms.config.mjs` 文件（推荐） + +此文件将被自动识别，并覆盖 `astro.config.mjs` 中的任何配置选项。请将所有 StudioCMS 配置选项移至此文件，如下所示： + +### 文件结构示例 + + + +- .env +- astro.config.mjs +- **studiocms.config.mjs** +- studiocms-auth.config.json 自动生成 +- package.json +- src + - env.d.ts + - ... + + + +### 配置文件示例 + +```ts twoslash title="astro.config.mjs" +import db from '@astrojs/db'; +import node from '@astrojs/node'; +import studioCMS from 'studiocms'; +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + site: 'https://demo.studiocms.dev/', + output: 'server', + adapter: node({ mode: "standalone" }), + integrations: [ db(), studioCMS() ], +}); +``` + +```ts twoslash title="studiocms.config.mjs" +import { defineStudioCMSConfig } from "studiocms/config"; + +export default defineStudioCMSConfig({ + dbStartPage: false, + // 其他配置选项 +}) +``` + +{/* Links */} +[reference-page]: /zh-cn/config-reference/ \ No newline at end of file diff --git a/src/content/docs/zh-cn/start-here/environment-variables.mdx b/src/content/docs/zh-cn/start-here/environment-variables.mdx new file mode 100644 index 00000000..cd7db15e --- /dev/null +++ b/src/content/docs/zh-cn/start-here/environment-variables.mdx @@ -0,0 +1,110 @@ +--- +i18nReady: true +title: 环境变量配置 +description: StudioCMS 所需环境变量概览 +sidebar: + order: 2 +--- + +import { Aside } from '@astrojs/starlight/components'; +import ReadMore from '~/components/ReadMore.astro'; + +为使 StudioCMS 正常运行，必须正确配置相关环境变量。这些变量对于建立与 Astro DB 的安全连接以及 StudioCMS API 的认证至关重要。若未正确配置这些环境变量，应用程序将无法正常运行。 + +您可以在项目根目录下创建 `.env` 文件并添加所需的环境变量。`.env` 文件是一个包含键值对的环境变量文本文件，应用程序在运行时将读取这些变量。 + +有关在 Astro 中使用环境变量的更多信息，请参考 Astro 文档中的[环境变量指南](https://docs.astro.build/guides/environment-variables)。 + +## 必需环境变量 + +### `@astrojs/db` 数据库连接参数 + +- `ASTRO_DB_REMOTE_URL` - libSQL 服务器的连接 URL +- `ASTRO_DB_APP_TOKEN` - libSQL 服务器的应用令牌 + +```bash title=".env" +ASTRO_DB_REMOTE_URL=libsql://your.server.io +ASTRO_DB_APP_TOKEN=eyJh...RUCg +``` + +有关 `@astrojs/db` 的详细信息，请参阅 [Astro DB 文档](https://docs.astro.build/zh-CN/guides/astro-db/) + +### `@studiocms-auth` 加密密钥 + +`CMS_ENCRYPTION_KEY` - 用于加密敏感数据的安全密钥 + +```bash title=".env" +CMS_ENCRYPTION_KEY="wqR+w...sRcg==" +``` + + + +## 可选环境变量 + +### oAuth 认证环境变量 + + +有关 oAuth 认证的详细配置指南，请参阅[配置 oAuth 认证][config-oauth]文档。 + + +#### GitHub（可选） + +如需启用 GitHub 认证，请在 `.env` 文件中添加： + +```bash title=".env" +# GitHub OAuth 凭据 +CMS_GITHUB_CLIENT_ID= +CMS_GITHUB_CLIENT_SECRET= +CMS_GITHUB_REDIRECT_URI= +``` + + + +#### Discord（可选） + +```bash title=".env" +# Discord OAuth 凭据 +CMS_DISCORD_CLIENT_ID= +CMS_DISCORD_CLIENT_SECRET= +CMS_DISCORD_REDIRECT_URI= +``` + +#### Google（可选） + +```bash title=".env" +# Google OAuth 凭据 +CMS_GOOGLE_CLIENT_ID= +CMS_GOOGLE_CLIENT_SECRET= +CMS_GOOGLE_REDIRECT_URI= +``` + +#### Auth0（可选） + +```bash title=".env" +# Auth0 OAuth 凭据 +CMS_AUTH0_CLIENT_ID= +CMS_AUTH0_CLIENT_SECRET= +CMS_AUTH0_DOMAIN= +CMS_AUTH0_REDIRECT_URI= +``` + +### 图像服务环境变量 + +#### Cloudinary（可选） + +如需使用内置的 Cloudinary 插件，需配置以下变量： + +```bash title=".env" +## Cloudinary JavaScript SDK +CMS_CLOUDINARY_CLOUDNAME="demo" +``` + +{/* Links */} +[config-oauth]: /zh-cn/start-here/getting-started/#可选配置-oauth-认证 \ No newline at end of file diff --git a/src/content/docs/zh-cn/start-here/gallery.mdx b/src/content/docs/zh-cn/start-here/gallery.mdx new file mode 100644 index 00000000..6520c290 --- /dev/null +++ b/src/content/docs/zh-cn/start-here/gallery.mdx @@ -0,0 +1,15 @@ +--- +i18nReady: true +title: 图库展示 +description: 展示 StudioCMS 功能的图片画廊 +tableOfContents: false +sidebar: + order: 5 +--- + +import Gallery from '~/components/Gallery.astro' +import { mainDemoGalleryImages } from "~/assets/index.ts" + +这里展示了 StudioCMS 集成的功能截图： + + \ No newline at end of file diff --git a/src/content/docs/zh-cn/start-here/getting-started.mdx b/src/content/docs/zh-cn/start-here/getting-started.mdx new file mode 100644 index 00000000..e4a1a890 --- /dev/null +++ b/src/content/docs/zh-cn/start-here/getting-started.mdx @@ -0,0 +1,348 @@ +--- +i18nReady: true +title: 快速入门指南 +description: 开始使用 StudioCMS 进行开发 +sidebar: + order: 1 +--- + +import { PackageManagers } from 'starlight-package-managers' +import TursoCLI from '~/components/TursoCLI.astro'; +import { Aside, Steps, Tabs, TabItem, LinkCard } from '@astrojs/starlight/components'; +import ReadMore from '~/components/ReadMore.astro'; +import { sponsors, SponsorLink } from '~/share-link' + + + +## 开始前的准备工作 + +使用 StudioCMS 需要满足以下条件： + +- 支持 Astro 的 [Node.js 版本](https://docs.astro.build/zh-cn/install-and-setup/#prerequisites)（不支持 Bun 和 Deno） +- 一个 Astro 项目 +- libSQL 数据库提供商或[自托管 libSQL 服务器][self-hosted-libsql] +- StudioCMS 集成 + +## 准备数据库 + +StudioCMS 使用 `@astrojs/db` 连接您的 libSQL 数据库。您可以选择任何 libSQL 提供商或[自托管 libSQL 服务器][self-hosted-libsql]。 + +如果您使用 StudioCMS CLI，并且已安装 Turso CLI，可以跳过此步骤，直接使用 CLI 创建新数据库。 + +有关所需环境变量的详细信息，请参阅 [`@astrojs/db` 数据库连接参数][db-url-token] + +### 使用 Turso 快速入门 + + + + +1. 安装 +2. Turso 账号 +3. 创建新数据库 + +4. 获取并设置 `ASTRO_DB_REMOTE_URL` + + 4a. 运行 `show` 命令查看数据库信息： + + + 4b. 复制 URL 值并设置为 `ASTRO_DB_REMOTE_URL`： + ```bash title=".env" + ASTRO_DB_REMOTE_URL=libsql://studiocms-yourname.turso.io + ``` + +5. 获取并设置 `ASTRO_DB_APP_TOKEN` + + 5a. 创建新令牌用于数据库认证： + + + 5b. 复制命令输出并设置为 `ASTRO_DB_APP_TOKEN`： + ```bash title=".env" + ASTRO_DB_APP_TOKEN=eyJhbGciOiJF...3ahJpTkKDw + ``` + + + +现在可以继续设置您的 StudioCMS 项目了！ + +### 使用其他提供商或自托管 libSQL + +libSQL 同时支持 HTTP 和 WebSockets 作为远程服务器的传输协议，也支持本地文件或内存数据库。 + +有关所需环境变量的详细信息，请参阅[数据库连接参数][db-url-token] + +了解所有 libSQL 选项（包括本地文件），请参阅 [Astro 文档：远程 URL 配置选项](https://docs.astro.build/zh-cn/guides/astro-db/#remote-url-configuration-options) + +## 创建 StudioCMS 项目 + + + + + + 1. 使用 create 命令创建 StudioCMS 项目 + + 使用预置模板创建包含 StudioCMS 的 Astro 项目： + + + 运行命令后，将提示您回答几个项目相关问题。完成后，CLI 将在指定目录创建新的 Astro 项目。 + + 随后系统会提示您完成后续步骤，包括确保环境变量正确设置以及运行项目完成安装。 + + 2. 运行 CLI 后，请确保 `astro.config.mjs` 文件正确配置： + + ```ts twoslash title="astro.config.mjs" {2-4,11-12} + import { defineConfig } from 'astro/config'; + import db from '@astrojs/db'; + import node from '@astrojs/node'; + import studioCMS from 'studiocms'; + + export default defineConfig({ + site: 'https://demo.studiocms.dev/', + output: 'server', + adapter: node({ mode: "standalone" }), + integrations: [ + db(), + studioCMS(), + ], + }); + ``` + + + + + + 1. 创建新的 Astro 项目 + + 创建基本的 Astro 项目： + + + 运行命令后，将提示您回答几个项目相关问题。完成后，CLI 将在指定目录创建新的 Astro 项目。 + + 您将看到 "Liftoff confirmed. Explore your project!" 消息及后续步骤建议。 + + `cd` 进入新项目目录： + ```bash + cd my-project + ``` + + 如果在 CLI 向导中跳过了 npm 安装步骤，请确保在继续前安装依赖。 + + 2. 安装 StudioCMS 集成及其依赖： + + + 3. 更新 `astro.config.mjs` 文件： + ```ts twoslash title="astro.config.mjs" {2-4,11-12} + import { defineConfig } from 'astro/config'; + import db from '@astrojs/db'; + import node from '@astrojs/node'; + import studioCMS from 'studiocms'; + + export default defineConfig({ + site: 'https://demo.studiocms.dev/', + output: 'server', + adapter: node({ mode: "standalone" }), + integrations: [ + db(), + studioCMS(), + ], + }); + ``` + + + + + + 1. 创建新的 Astro 项目 + + 创建基本的 Astro 项目： + + + 运行命令后，将提示您回答几个项目相关问题。完成后，CLI 将在指定目录创建新的 Astro 项目。 + + 您将看到 "Liftoff confirmed. Explore your project!" 消息及后续步骤建议。 + + `cd` 进入新项目目录： + ```bash + cd my-project + ``` + + 如果在 CLI 向导中跳过了 npm 安装步骤，请确保在继续前安装依赖。 + + 2. 手动安装 StudioCMS 集成和依赖： + + + 3. 更新 `astro.config.mjs` 文件： + ```ts twoslash title="astro.config.mjs" {2-4,11-12} + import { defineConfig } from 'astro/config'; + import db from '@astrojs/db'; + import node from '@astrojs/node'; + import studioCMS from 'studiocms'; + + export default defineConfig({ + site: 'https://demo.studiocms.dev/', + output: 'server', + adapter: node({ mode: "standalone" }), + integrations: [ + db(), + studioCMS(), + ], + }); + ``` + + + + + +在配置 StudioCMS `时需特别注意：astro.config.mjs` 文件中的 ​`site` 配置项是必需参数，必须设置为您的站点实际 URL 或临时占位 URL 才能确保系统正常运行。（例如：`https://demo.studiocms.dev/` 或 `http://localhost:4321/`） + + + +## 配置认证 + +StudioCMS 认证需要至少在 `.env` 文件中设置[加密密钥][encryption-key]。 + +以下是 StudioCMS 认证所需的环境变量： + +```bash title=".env" +# 用于用户名密码认证的加密密钥 +CMS_ENCRYPTION_KEY="wqR+w...sRcg==" +``` + +使用以下命令生成安全加密密钥： +```bash +openssl rand --base64 16 +``` +并将输出设置为 `CMS_ENCRYPTION_KEY` 的值。 + + +了解所有可用的认证环境变量，请参阅[环境变量][environment-variables]页面。 + + +### 可选：配置 oAuth 认证 + +StudioCMS 支持 GitHub、Discord、Google 和 Auth0 的 oAuth 认证。要配置 oAuth，需要[在 `.env` 文件中设置必需的环境变量][oauth-environment-variables]，并确保[在配置中启用了相应的提供商][auth-config-ref]。 + +oAuth 提供商需要设置回调 URL（用户认证后的重定向路径）。 + +#### 设置回调 URL + +根据您的环境设置回调 URL： + +| 环境 | 回调 URL | +|------------|------------------------------------------| +| 生产环境 | `https://your-domain.tld/studiocms_api/auth//callback` | +| 测试开发 | `http://localhost:4321/studiocms_api/auth//callback` | + +#### 回调 URL 路径示例 + +不同提供商对应的回调 URL 路径： + +| 提供商 | 回调 PATH | +|----------|-----------------------------------| +| GitHub | `/studiocms_api/auth/github/callback` | +| Discord | `/studiocms_api/auth/discord/callback` | +| Google | `/studiocms_api/auth/google/callback` | +| Auth0 | `/studiocms_api/auth/auth0/callback` | + +## 配置 `package.json` 脚本 + +在 `package.json` 脚本中添加 `--remote` 参数： + +```json /--remote/ title="package.json" +{ + "name": "my-studiocms-project", + "scripts": { + "dev": "astro dev --remote", + "build": "astro check & astro build --remote", + "astro": "astro" + } +} +``` + +## 运行 StudioCMS 项目 + +得益于 Astro 的强大功能，StudioCMS 的运行非常简单。 + +### 首次设置（或数据表结构更新时） + +在终端运行以下命令： + + + + + + +运行命令后，您将看到项目在 `localhost:4321` 运行的消息。首次设置时，请访问 `http://localhost:4321/start` 完成 StudioCMS 配置。 + +### 本地 Astro 开发模式运行 + +在终端运行以下命令： + + + +运行后，访问 `http://localhost:4321` 查看您的项目。 + +**恭喜！** 🥳 您已成功在 Astro 项目中安装 StudioCMS。 + +### 为 StudioCMS 添加前端 + +StudioCMS 是无头 CMS，您需要自行创建前端展示内容。如果需要预构建的前端，请查看[包目录][package-catalog]中的插件。 + +#### 设置博客 + +如需搭建博客，可以使用 `@studiocms/blog` 插件： + + + +安装后，在 `studiocms.config.mjs` 文件中添加插件： + +```ts twoslash title="studiocms.config.mjs" +import { defineStudioCMSConfig } from 'studiocms/config'; +import blog from '@studiocms/blog'; + +export default defineStudioCMSConfig({ + dbStartPage: false, + plugins: [ + blog(), + ], +}); +``` + +### 构建和部署 StudioCMS 项目 + +完成[首次设置](#首次设置或数据表结构更新时)后，即可构建并部署项目到服务器。 + +默认情况下，StudioCMS 仪表板位于 `http://your-domain.tld/dashboard`。 + +该仪表板可用于在开发和生产环境中管理内容和设置。 + +> **建议**：在生产模式下使用 StudioCMS，开发模式下仪表板可能出现问题（如 Vite 依赖错误）。 + +## 后续步骤 + + +了解如何设置 StudioCMS 的[环境变量][environment-variables]。 + + + +查看[包目录][package-catalog]，寻找和使用 StudioCMS 插件。 + + + +通过 [StudioCMS 参考文档][config-reference] 了解配置选项。 + + +{/* Links */} +[package-catalog]: /zh-cn/package-catalog/ +[environment-variables]: /zh-cn/start-here/environment-variables/ +[config-reference]: /zh-cn/config-reference/ +[db-url-token]: /zh-cn/start-here/environment-variables/#astrojsdb-数据库连接参数 +[encryption-key]: /zh-cn/start-here/environment-variables/#studiocms-auth-加密密钥 +[oauth-environment-variables]: /zh-cn/start-here/environment-variables/#oauth-认证环境变量 +[auth-config-ref]: /zh-cn/config-reference/dashboard/#authconfig +[self-hosted-libsql]: /zh-cn/guides/database/sqld-server/ \ No newline at end of file diff --git a/src/content/docs/zh-cn/start-here/why-studioCMS.mdx b/src/content/docs/zh-cn/start-here/why-studioCMS.mdx new file mode 100644 index 00000000..85e65e72 --- /dev/null +++ b/src/content/docs/zh-cn/start-here/why-studioCMS.mdx @@ -0,0 +1,36 @@ +--- +i18nReady: true +title: 为什么选择 StudioCMS？ +description: StudioCMS 是传统 CMS 平台的创新替代方案，基于 Astro DB 和 Astro 的无头 CMS，提供无缝的内容管理体验。 +sidebar: + order: 4 +--- + +Astro 是一个以内容为核心的框架。其内容集合（content collections）和全新内容层等功能，使得管理任何规模或形式的内容变得极其简单。 + +然而，这种解决方案要求您必须具备开发者身份，或者至少对 Astro 如何处理内容目录中的文件有深入了解。这种体验并不适合客户或普通用户，他们只需要简单的内容管理界面。这正是您需要 CMS 的原因。 + +市面上存在各种满足不同需求的 CMS 解决方案，但没有一个能完全发挥 Astro 的全部潜力。这正是 StudioCMS 诞生的意义：它是一个完全专注于 Astro 的 CMS，能够深入整合 Astro 的每个功能特性，提供高度优化的开发者体验（DX）。 + +## 核心优势 + +- **`@astrojs/db`深度整合**： + 基于 Astro DB 构建，您可以选择数据存储位置和方式，无论是 Turso 云数据库还是本地文件。 + +- **可定制 Markdown 渲染器**： + 内置支持主题化提示框（callouts）和可自定义样式的 Markdown 渲染器。 + +- **开箱即用的认证系统**： + 完整的认证解决方案，内置密码加密、会话管理、速率限制和可自定义的权限等级。 + +- **WordPress 无缝迁移**： + 支持从任何标准 WordPress 安装轻松迁移到 StudioCMS！ + +- **插件化架构**： + 可扩展的插件系统，支持自定义页面类型、仪表板部件和设置页面。 + +- **智能内容渲染**： + 内置可定制的内容渲染能力，支持主题化提示框和 Markdown 样式控制。 + +- **持续创新**： + StudioCMS 正在积极开发中！我们将持续添加新功能，优化您的内容体验。欢迎[提交问题](https://github.com/withstudiocms/studiocms/issues/new/choose)提出建议或反馈！ \ No newline at end of file diff --git a/src/content/docs/zh-cn/utils/rendering.mdx b/src/content/docs/zh-cn/utils/rendering.mdx new file mode 100644 index 00000000..5fc39cfa --- /dev/null +++ b/src/content/docs/zh-cn/utils/rendering.mdx @@ -0,0 +1,39 @@ +--- +i18nReady: true +title: "内容渲染" +description: "内容渲染选项" +sidebar: + order: 1 +--- + +StudioCMS 的渲染系统根据当前页面类型（pageType）动态确定。 + +以下示例展示了一个通配路由（Catch-all route），其中通过 SDK 获取当前页面数据并传递给渲染器。在此示例中，我们使用页面设置中默认配置的 `studiocms/markdown` 页面类型，并将其包裹在布局组件中（如 `@studiocms/blog` 插件的实现方式）。某些页面构建器插件可能不包含标准布局，而是允许您像其他 CMS 系统一样完全在构建器中设计页面。 + +```astro title="src/pages/[...slug].astro" +--- +import { StudioCMSRenderer } from 'studiocms:renderer'; +import studioCMS_SDK from 'studiocms:sdk'; +import Layout from '../layouts/Layout.astro'; + +let { slug } = Astro.params; + +if (!slug) { + slug = 'index'; +} + +const page = await studioCMS_SDK.GET.databaseEntry.pages.bySlug(slug); + +if (!page) { + return Astro.redirect('/404'); +} + +const { title, description, heroImage } = page; +--- + + +
+ +
+ +``` \ No newline at end of file diff --git a/src/content/i18n/zh-CN.json b/src/content/i18n/zh-CN.json new file mode 100644 index 00000000..9ac52cfd --- /dev/null +++ b/src/content/i18n/zh-CN.json @@ -0,0 +1,49 @@ +{ + "site-title.labels.docs": "文档", + "site-title.labels.main-site": "主站点", + "site-title.labels.live-demo": "在线演示", + "sponsors.sponsoredby": "赞助商", + "package-catalog.readmore.start": "更多信息请查看", + "package-catalog.readmore.end": "文档页面", + "integration-labels.changelog": "更新日志", + "contributors.core-packages": "StudioCMS 核心包", + "contributors.ui-library": "StudioCMS UI 组件库", + "contributors.devapps": "StudioCMS 开发应用", + "contributors.plugins": "StudioCMS 插件", + "contributors.documentation": "StudioCMS 文档", + "contributors.website": "StudioCMS 网站", + "contributors.bots": "StudioCMS 机器人", + "docsearch.button": "搜索", + "docsearch.shortcutLabel": "按 / 键搜索", + "docsearch.placeholder": "搜索文档", + "docsearch.searchBox.resetButtonTitle": "清除查询", + "docsearch.searchBox.resetButtonAriaLabel": "清除查询", + "docsearch.searchBox.cancelButtonText": "取消", + "docsearch.searchBox.cancelButtonAriaLabel": "取消", + "docsearch.searchBox.searchInputLabel": "搜索", + + "docsearch.startScreen.recentSearchesTitle": "最近搜索", + "docsearch.startScreen.noRecentSearchesText": "无最近搜索记录", + "docsearch.startScreen.saveRecentSearchButtonTitle": "保存此搜索", + "docsearch.startScreen.removeRecentSearchButtonTitle": "从历史记录中移除", + "docsearch.startScreen.favoriteSearchesTitle": "收藏搜索", + "docsearch.startScreen.removeFavoriteSearchButtonTitle": "从收藏中移除", + + "docsearch.errorScreen.titleText": "无法获取结果", + "docsearch.errorScreen.helpText": "请检查您的网络连接", + + "docsearch.footer.selectText": "选择", + "docsearch.footer.selectKeyAriaLabel": "回车键", + "docsearch.footer.navigateText": "导航", + "docsearch.footer.navigateUpKeyAriaLabel": "上箭头", + "docsearch.footer.navigateDownKeyAriaLabel": "下箭头", + "docsearch.footer.closeText": "关闭", + "docsearch.footer.closeKeyAriaLabel": "Esc 键", + "docsearch.footer.searchByText": "搜索技术支持", + + "docsearch.noResultsScreen.noResultsText": "未找到相关结果", + "docsearch.noResultsScreen.suggestedQueryText": "建议尝试搜索", + "docsearch.noResultsScreen.reportMissingResultsText": "认为该查询应有结果？", + "docsearch.noResultsScreen.reportMissingResultsLinkText": "请告知我们", + "quick-update": "运行以下命令快速更新至最新版本：" +} diff --git a/src/starlight-sidebar/availTranslations.ts b/src/starlight-sidebar/availTranslations.ts index b4cb9dc2..69aafc24 100644 --- a/src/starlight-sidebar/availTranslations.ts +++ b/src/starlight-sidebar/availTranslations.ts @@ -1 +1 @@ -export const Translations = ['en', 'es', 'fr', 'ko', 'de'] as const; +export const Translations = ['en', 'es', 'fr', 'ko', 'de', 'zh-cn'] as const; diff --git a/src/starlight-sidebar/zh-cn.json b/src/starlight-sidebar/zh-cn.json new file mode 100644 index 00000000..d2c43a2b --- /dev/null +++ b/src/starlight-sidebar/zh-cn.json @@ -0,0 +1,21 @@ +{ + "topic-learn": "学习", + "topic-package-catalog": "包目录", + "topic-references": "参考文档", + "start-here": "入门指南", + "contributing": "贡献指南", + "how-it-works": "核心机制", + "utils": "工具与助手", + "plugins": "插件", + "catalog": "目录", + "studiocms-plugins": "StudioCMS 官方插件", + "community-plugins": "社区插件", + "config-reference": "配置参考", + "typedoc": "TypeDoc", + "auto-gen": "自动生成", + "topic-guides": "教程指南", + "database": "数据库指南", + "upgrade": "版本升级", + "version": "版本指南", + "latest": "最新升级指南" +}