From 2d714c345de4e56d592a99e0ca2350af3c9e7421 Mon Sep 17 00:00:00 2001 From: Adam Matthiesen Date: Thu, 20 Feb 2025 04:37:49 -0800 Subject: [PATCH] Refactor import paths for consistency and update documentation descriptions --- .../docs/config-reference/dashboard/index.mdx | 0 .../default-frontend-config/index.mdx | 0 .../config-reference/image-service/index.mdx | 0 .../included-integrations/index.mdx | 0 .../docs/config-reference/options-schema.mdx | 0 .../docs/config-reference/overrides/index.mdx | 0 .../renderer-config/index.mdx | 0 .../renderer-config/markdoc-config.mdx | 0 .../renderer-config/mdx-config.mdx | 0 .../customizing/studiocms-renderers/index.mdx | 0 .../studiocms-renderers/markdoc.mdx | 0 archive/docs/how-it-works/index.mdx | 116 ++++++++++ docs/astro.config.mts | 95 ++++---- docs/package.json | 26 +-- docs/src/components/DropdownScript.astro | 2 +- docs/src/components/ModalScript.astro | 2 +- docs/src/components/ThemeHelperScript.astro | 2 +- docs/src/components/ToasterScript.astro | 2 +- .../docs/contributing/translations.mdx | 4 +- docs/src/content/docs/how-it-works/index.mdx | 105 +-------- .../src/content/docs/how-it-works/restapi.mdx | 15 ++ docs/src/content/docs/how-it-works/sdk.mdx | 15 ++ docs/src/content/docs/index.mdx | 12 +- .../community-integrations/web-vitals.mdx | 4 +- .../content/docs/package-catalog/index.mdx | 2 +- .../studiocms-integrations/studiocms-blog.mdx | 4 +- .../studiocms-devapps.mdx | 6 +- .../content/docs/start-here/configuration.mdx | 2 +- .../docs/start-here/getting-started.mdx | 116 ++++++++-- .../package-catalog/studiocms-blog.json | 2 +- .../content/package-catalog/studiocms-ui.json | 4 +- docs/src/starlightOverrides/Head.astro | 3 +- docs/src/starlightOverrides/PageTitle.astro | 7 +- docs/src/starlightOverrides/Sidebar.astro | 5 +- docs/src/starlightOverrides/SiteTitle.astro | 6 +- packages/studiocms_blog/src/index.ts | 4 +- pnpm-lock.yaml | 202 +++++++++--------- pnpm-workspace.yaml | 6 +- 38 files changed, 442 insertions(+), 327 deletions(-) rename {docs/src/content => archive}/docs/config-reference/dashboard/index.mdx (100%) rename {docs/src/content => archive}/docs/config-reference/default-frontend-config/index.mdx (100%) rename {docs/src/content => archive}/docs/config-reference/image-service/index.mdx (100%) rename {docs/src/content => archive}/docs/config-reference/included-integrations/index.mdx (100%) rename {docs/src/content => archive}/docs/config-reference/options-schema.mdx (100%) rename {docs/src/content => archive}/docs/config-reference/overrides/index.mdx (100%) rename {docs/src/content => archive}/docs/config-reference/renderer-config/index.mdx (100%) rename {docs/src/content => archive}/docs/config-reference/renderer-config/markdoc-config.mdx (100%) rename {docs/src/content => archive}/docs/config-reference/renderer-config/mdx-config.mdx (100%) rename {docs/src/content => archive}/docs/customizing/studiocms-renderers/index.mdx (100%) rename {docs/src/content => archive}/docs/customizing/studiocms-renderers/markdoc.mdx (100%) create mode 100644 archive/docs/how-it-works/index.mdx create mode 100644 docs/src/content/docs/how-it-works/restapi.mdx create mode 100644 docs/src/content/docs/how-it-works/sdk.mdx diff --git a/docs/src/content/docs/config-reference/dashboard/index.mdx b/archive/docs/config-reference/dashboard/index.mdx similarity index 100% rename from docs/src/content/docs/config-reference/dashboard/index.mdx rename to archive/docs/config-reference/dashboard/index.mdx diff --git a/docs/src/content/docs/config-reference/default-frontend-config/index.mdx b/archive/docs/config-reference/default-frontend-config/index.mdx similarity index 100% rename from docs/src/content/docs/config-reference/default-frontend-config/index.mdx rename to archive/docs/config-reference/default-frontend-config/index.mdx diff --git a/docs/src/content/docs/config-reference/image-service/index.mdx b/archive/docs/config-reference/image-service/index.mdx similarity index 100% rename from docs/src/content/docs/config-reference/image-service/index.mdx rename to archive/docs/config-reference/image-service/index.mdx diff --git a/docs/src/content/docs/config-reference/included-integrations/index.mdx b/archive/docs/config-reference/included-integrations/index.mdx similarity index 100% rename from docs/src/content/docs/config-reference/included-integrations/index.mdx rename to archive/docs/config-reference/included-integrations/index.mdx diff --git a/docs/src/content/docs/config-reference/options-schema.mdx b/archive/docs/config-reference/options-schema.mdx similarity index 100% rename from docs/src/content/docs/config-reference/options-schema.mdx rename to archive/docs/config-reference/options-schema.mdx diff --git a/docs/src/content/docs/config-reference/overrides/index.mdx b/archive/docs/config-reference/overrides/index.mdx similarity index 100% rename from docs/src/content/docs/config-reference/overrides/index.mdx rename to archive/docs/config-reference/overrides/index.mdx diff --git a/docs/src/content/docs/config-reference/renderer-config/index.mdx b/archive/docs/config-reference/renderer-config/index.mdx similarity index 100% rename from docs/src/content/docs/config-reference/renderer-config/index.mdx rename to archive/docs/config-reference/renderer-config/index.mdx diff --git a/docs/src/content/docs/config-reference/renderer-config/markdoc-config.mdx b/archive/docs/config-reference/renderer-config/markdoc-config.mdx similarity index 100% rename from docs/src/content/docs/config-reference/renderer-config/markdoc-config.mdx rename to archive/docs/config-reference/renderer-config/markdoc-config.mdx diff --git a/docs/src/content/docs/config-reference/renderer-config/mdx-config.mdx b/archive/docs/config-reference/renderer-config/mdx-config.mdx similarity index 100% rename from docs/src/content/docs/config-reference/renderer-config/mdx-config.mdx rename to archive/docs/config-reference/renderer-config/mdx-config.mdx diff --git a/docs/src/content/docs/customizing/studiocms-renderers/index.mdx b/archive/docs/customizing/studiocms-renderers/index.mdx similarity index 100% rename from docs/src/content/docs/customizing/studiocms-renderers/index.mdx rename to archive/docs/customizing/studiocms-renderers/index.mdx diff --git a/docs/src/content/docs/customizing/studiocms-renderers/markdoc.mdx b/archive/docs/customizing/studiocms-renderers/markdoc.mdx similarity index 100% rename from docs/src/content/docs/customizing/studiocms-renderers/markdoc.mdx rename to archive/docs/customizing/studiocms-renderers/markdoc.mdx diff --git a/archive/docs/how-it-works/index.mdx b/archive/docs/how-it-works/index.mdx new file mode 100644 index 0000000000..1a2bfbe9f5 --- /dev/null +++ b/archive/docs/how-it-works/index.mdx @@ -0,0 +1,116 @@ +--- +i18nReady: true +title: "How it works" +description: "Learn how StudioCMS helps you manage and deliver your content by exploring a comprehensive breakdown of it's fundamental components." +sidebar: + order: 1 + badge: + text: "Updated" + variant: "success" +--- + +# Introduction + +StudioCMS is a powerful CMS built for Astro that allows you to manage and serve your content using [Astro DB](https://docs.astro.build/en/guides/astro-db/). It's designed to be easy-to-use and flexible enough to handle any type of content. + +Extending StudioCMS is easy too! You can create your own plugins to add new features to StudioCMS. + +## How does it work? + +StudioCMS is divided into multiple parts: + +- **studiocms**: The primary integration that hooks into your Astro project and provides the ability to interact with Astro DB (through the `@astrojs/db` integration). +- **@studiocms/core**: The core integration that provides the foundation for StudioCMS. It provides the database configurations, and adds various features including virtual imports, logging, etc. +- **@studiocms/auth**: An integration that provides authentication configuration options for the StudioCMS Dashboard. +- **@studiocms/assets**: An integration that provides the assets for the StudioCMS Dashboard. +- **@studiocms/frontend**: An integration that provides the frontend layouts and components for the StudioCMS ecosystem. +- **@studiocms/renderers**: An integration that provides the renderers for the StudioCMS ecosystem. +- **@studiocms/dashboard**: The primary web interface for managing your StudioCMS project. It provides a user-friendly interface for creating, editing, and deleting content. +- **@studiocms/imagehandler**: An integration that provides a `` component to handle remote images and optimize them for your project in an SSR environment. +- **@studiocms/robotstxt**: An integration that automates the creation of a `robots.txt` file for your StudioCMS project. +- **@studiocms/betaresources**: An integration that provides resources for the StudioCMS beta. + +## Breakdown + +### StudioCMS: Core + +StudioCMS Core is an Astro Integration which provides a comprehensive CMS solution out-of-the-box. This integration registers StudioCMS as the first plugin, sets up database configurations, watches for configuration changes, and adds various features including virtual imports, logging, and default frontend routes. + +#### Features + +- **@astrojs/db**: StudioCMS Core uses the `@astrojs/db` integration to connect to a libSQL database. +- **Virtual Imports**: StudioCMS Core adds several [virtual modules](https://vitejs.dev/guide/api-plugin#virtual-modules-convention) packed with features that give you full control over your dynamic content. +- **Logging**: StudioCMS Core logs all changes to Astro Studio. This can be enabled in your config file. +- **Default Frontend Routes**: The StudioCMS Core integration adds default frontend routes to your Astro project to allow for easy access to the StudioCMS dashboard. +- **Plugin System**: You can extend StudioCMS using plugins to add additional functionality. + +#### Core Virtual Modules + +:::tip +Modules prefixed with `virtual:` are virtual modules that are primarily used internally by StudioCMS, but can be used by developers to access StudioCMS data. To access these modules with proper typings, see the [project development `.d.ts` file](https://github.com/withstudiocms/studiocms/blob/main/packages/studiocms_core/virtuals.d.ts) for an example of how to configure your project to sense these types. + +Modules without the `virtual:` prefix have full typings defined and injected into your project's `.astro/` directory automatically, and can be accessed directly without any extra configuration. +::: + +- **`virtual:studiocms/config`**: Provides the resolved configuration for the StudioCMS integration ecosystem. +- **`virtual:studiocms/version`**: Provides the current version of the StudioCMS integration ecosystem. +- **`virtual:studiocms/pluginSystem`**: Provides the plugin system interfaces during runtime for StudioCMS. +- **`studiocms:components`**: Provides the front-end exported components for StudioCMS. +- **`studiocms:helpers`**: Provides the front-end exported helper functions for StudioCMS. +- **`studiocms:helpers/contentHelper`**: Provides the exported content helper functions for StudioCMS. +- **`studiocms:helpers/headDefaults`**: Provides the exported head defaults for StudioCMS. +- **`studiocms:helpers/routemap`**: Provides the exported route map for StudioCMS. +- **`studiocms:i18n`**: Provides the i18n utilities for StudioCMS. + +### StudioCMS: Auth + +The StudioCMS Auth integration provides authentication configuration options for the StudioCMS Dashboard. This integration is used to determine how users can authenticate with the StudioCMS Dashboard. + +#### Features +- **`@oslojs`**: The StudioCMS Auth integration uses the `@oslojs` utilities to handle local authentication options such as username and password. +- **`arctic`**: The StudioCMS Auth integration uses the `arctic` library to handle OAuth authentication options such as GitHub. +- **`three`**: The StudioCMS Auth integration uses the ThreeJS library to create a 3D logo animation for the login and signup pages. +- **`@studiocms/ui`**: The StudioCMS Auth integration uses the `@studiocms/ui` library to provide UI components for the login and signup pages. + +#### Auth Virtual Modules + +- **`studiocms:auth/lib/encryption`**: Provides encryption functions for the StudioCMS Auth integration. +- **`studiocms:auth/lib/password`**: Provides password functions for the StudioCMS Auth integration. +- **`studiocms:auth/lib/session`**: Provides session functions for the StudioCMS Auth integration. +- **`studiocms:auth/lib/types`**: Provides types for the StudioCMS Auth integration. +- **`studiocms:auth/lib/user`**: Provides user functions for the StudioCMS Auth integration. +- **`studiocms:auth/utils/authEnvCheck`**: Provides authentication environment check functions for the StudioCMS Auth integration. +- **`studiocms:auth/scripts/three`**: Provides ThreeJS scripts for the StudioCMS Auth integration. +- **`studiocms:auth/scripts/formListener`**: Provides form listener scripts for the StudioCMS Auth integration. + +### StudioCMS: Dashboard + +The StudioCMS Dashboard is a web interface that allows you to manage your StudioCMS project. It provides a user-friendly interface for creating, editing, and deleting content for your project. The StudioCMS Dashboard is built with [Astro](https://astro.build) and our [`@studiocms/ui](/customizing/studiocms-ui/) library. + +#### Tech Stack + +- **Dashboard**: The StudioCMS Dashboard provides a user-friendly interface for managing your StudioCMS project. +- **AuthConfig**: The StudioCMS Dashboard provides authentication configuration options. +- **DashboardRouteOverride**: The StudioCMS Dashboard provides a dashboard route override configuration option. Allowing you to change the default route for the StudioCMS Dashboard and API. + +### StudioCMS: ImageHandler + +The StudioCMS ImageHandler is an integration that provides a custom image component for your Astro project. This component is used to handle remote images and optimize them in a SSR environment. + +#### Features + +- **``**: The StudioCMS ImageHandler provides a custom image component for your Astro project. + +#### ImageHandler Virtual Modules + +- **`studiocms:imageHandler/components`**: The Virtual module that provides the exported image components for the StudioCMS ImageHandler. + +### StudioCMS: Renderers + +The StudioCMS Renderers integration provides the renderers for the StudioCMS ecosystem. This integration is used to determine how content should be rendered in StudioCMS. + +#### Renderers Virtual Modules + +- **`studiocms:renderer`**: Provides the main renderer component for the StudioCMS ecosystem. +- **`studiocms:renderer/config`**: Provides the configuration for the StudioCMS renderer. +- **`studiocms:renderer/astroMarkdownConfig`**: Provides the configuration for Astro Markdown support. \ No newline at end of file diff --git a/docs/astro.config.mts b/docs/astro.config.mts index 76b0f26726..3a66a92012 100644 --- a/docs/astro.config.mts +++ b/docs/astro.config.mts @@ -1,10 +1,11 @@ import starlight from '@astrojs/starlight'; -import starlightUtils from '@lorenzo_lewis/starlight-utils'; +// import starlightUtils from '@lorenzo_lewis/starlight-utils'; +// import { typeDocPlugins, typeDocSideBarEntry } from './typedoc.config.ts'; +import ui from '@studiocms/ui'; import { defineConfig } from 'astro/config'; import starlightImageZoom from 'starlight-image-zoom'; import getCoolifyURL from './hostUtils.ts'; import rehypePluginKit from './src/plugins/rehypePluginKit.ts'; -import { typeDocPlugins, typeDocSideBarEntry } from './typedoc.config.ts'; // Define the Site URL const site = getCoolifyURL(true) || 'https://docs.studiocms.dev/'; @@ -37,6 +38,7 @@ export default defineConfig({ rehypePlugins: rehypePluginKit, }, integrations: [ + ui(), starlight({ title: 'StudioCMS', description: 'A dedicated CMS for Astro DB. Built from the ground up by the Astro community.', @@ -98,69 +100,54 @@ export default defineConfig({ ], sidebar: [ { - label: 'Learn', + label: 'Start Here', + autogenerate: { directory: 'start-here' }, + }, + { + label: 'Contributing Guides', + autogenerate: { directory: 'contributing' }, + }, + { + label: 'Understanding StudioCMS', + autogenerate: { directory: 'how-it-works' }, + }, + { + label: 'Package Catalog', items: [ { - label: 'Start Here', - autogenerate: { directory: 'start-here' }, - }, - { - label: 'Contributing Guides', - autogenerate: { directory: 'contributing' }, - }, - { - label: 'Understanding StudioCMS', - autogenerate: { directory: 'how-it-works' }, + label: 'Package List', + link: '/package-catalog', + badge: { text: 'New', variant: 'success' }, }, { - label: 'Package Catalog', - items: [ - { - label: 'Package List', - link: '/package-catalog', - badge: { text: 'New', variant: 'success' }, - }, - { - label: 'StudioCMS Integrations', - autogenerate: { directory: 'package-catalog/studiocms-integrations' }, - collapsed: true, - }, - { - label: 'Community Integrations', - autogenerate: { directory: 'package-catalog/community-integrations' }, - collapsed: true, - }, - ], + label: 'StudioCMS Integrations', + autogenerate: { directory: 'package-catalog/studiocms-integrations' }, + collapsed: true, }, { - label: 'Customizing StudioCMS', - items: [ - { - label: '@studiocms/renderers', - autogenerate: { directory: 'customizing/studiocms-renderers' }, - collapsed: true, - }, - ], + label: 'Community Integrations', + autogenerate: { directory: 'package-catalog/community-integrations' }, + collapsed: true, }, ], }, - { - label: 'References', - items: [ - { - label: 'Configuration Reference', - autogenerate: { directory: 'config-reference' }, - collapsed: false, - }, - typeDocSideBarEntry, - ], - }, + // { + // label: 'References', + // items: [ + // { + // label: 'Configuration Reference', + // autogenerate: { directory: 'config-reference' }, + // collapsed: false, + // }, + // // typeDocSideBarEntry, + // ], + // }, ], plugins: [ - starlightUtils({ - multiSidebar: { switcherStyle: 'horizontalList' }, - }), - ...typeDocPlugins, + // starlightUtils({ + // multiSidebar: { switcherStyle: 'horizontalList' }, + // }), + // ...typeDocPlugins, starlightImageZoom(), ], }), diff --git a/docs/package.json b/docs/package.json index 0d11265bcf..a4e3d13268 100644 --- a/docs/package.json +++ b/docs/package.json @@ -29,33 +29,33 @@ "tsm": "2.3.0", "@lunariajs/core": "https://pkg.pr.new/lunariajs/lunaria/@lunariajs/core@4c8b9b0", - "expressive-code-twoslash": "^0.3.0", + "expressive-code-twoslash": "^0.4.0", "@shikijs/colorized-brackets": "^1.24.2", - "starlight-package-managers": "^0.8.0", - "@11ty/eleventy-fetch": "^5.0.1", + "starlight-package-managers": "^0.10.0", + "@11ty/eleventy-fetch": "^5.0.2", "@lorenzo_lewis/starlight-utils": "^0.2.0", "@types/hast": "^3.0.4", - "p-retry": "^6.2.0", + "p-retry": "^6.2.1", "astro-embed": "^0.9.0", "hast": "^1.0.0", - "hast-util-select": "^6.0.3", + "hast-util-select": "^6.0.4", "rehype": "^13.0.2", - "starlight-typedoc": "^0.17.0", - "typedoc": "^0.27", - "typedoc-plugin-markdown": "^4.3.2", - "starlight-image-zoom": "^0.9.0", - "hastscript": "^9.0.0", + "starlight-typedoc": "^0.19.0", + "typedoc": "^0.27.7", + "typedoc-plugin-markdown": "^4.4.2", + "starlight-image-zoom": "^0.11.1", + "hastscript": "^9.0.1", "hast-util-to-string": "^3.0.1", "mdast-util-from-markdown": "^2.0.2", - "mdast-util-gfm": "^3.0.0", + "mdast-util-gfm": "^3.1.0", "mdast-util-to-hast": "^13.2.0", "rehype-slug": "^6.0.0", "rehype-autolink-headings": "^7.1.0", "rehype-external-links": "^3.0.0", - "@types/html-escaper": "^3.0.2", + "@types/html-escaper": "^3.0.4", "html-escaper": "^3.0.3", - "@fontsource-variable/onest": "5.1.0", + "@fontsource-variable/onest": "5.1.1", "unified": "^11.0.5" } } diff --git a/docs/src/components/DropdownScript.astro b/docs/src/components/DropdownScript.astro index b3a1cb53c3..b866c517a9 100644 --- a/docs/src/components/DropdownScript.astro +++ b/docs/src/components/DropdownScript.astro @@ -1,5 +1,5 @@