├── .changeset ├── README.md └── config.json ├── .github └── workflows │ ├── autofix.yml │ ├── integration.yml │ └── release.yml ├── .gitignore ├── .npmignore ├── .prettierignore ├── .vscode ├── extensions.json └── settings.json ├── CHANGELOG.md ├── LICENSE ├── README.md ├── eslint.config.mjs ├── package.json ├── pnpm-lock.yaml ├── src ├── index.ts └── libs │ ├── fs.ts │ ├── npm.ts │ ├── prompt.ts │ └── validator.ts ├── templates ├── LICENSE ├── README.md ├── docs │ ├── README.md │ ├── astro.config.ts │ ├── package.json │ ├── public │ │ └── favicon.svg │ ├── src │ │ ├── content.config.ts │ │ └── content │ │ │ └── docs │ │ │ ├── getting-started.mdx │ │ │ └── index.mdx │ └── tsconfig.json ├── gitignore ├── npmignore ├── package.json ├── packages │ └── plugin │ │ ├── README.md │ │ ├── index.ts │ │ ├── package.json │ │ └── tsconfig.json ├── pnpm-workspace.yaml ├── styles.css ├── theme │ ├── assets │ │ └── hero.webp │ ├── customization.md │ └── examples │ │ ├── asides.mdx │ │ ├── badges.mdx │ │ ├── banner-splash.md │ │ ├── banner.md │ │ ├── cards.mdx │ │ ├── code-blocks.mdx │ │ ├── draft.md │ │ ├── file-tree.mdx │ │ ├── hero.md │ │ ├── kitchen-sink.mdx │ │ ├── link-buttons.mdx │ │ ├── markdown.md │ │ ├── steps.mdx │ │ └── tabs.mdx └── vscode │ ├── extensions.json │ └── launch.json └── tsconfig.json /.changeset/README.md: -------------------------------------------------------------------------------- 1 | # Changesets 2 | 3 | Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works 4 | with multi-package repos, or single-package repos to help you version and publish your code. You can 5 | find the full documentation for it [in our repository](https://github.com/changesets/changesets) 6 | 7 | We have a quick list of common questions to get you started engaging with this project in 8 | [our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md) 9 | -------------------------------------------------------------------------------- /.changeset/config.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://unpkg.com/@changesets/config@3.0.4/schema.json", 3 | "changelog": [ 4 | "@changesets/changelog-github", 5 | { "repo": "HiDeoo/generator-starlight-plugin" } 6 | ], 7 | "commit": false, 8 | "access": "public", 9 | "baseBranch": "main", 10 | "updateInternalDependencies": "patch" 11 | } 12 | -------------------------------------------------------------------------------- /.github/workflows/autofix.yml: -------------------------------------------------------------------------------- 1 | name: autofix.ci 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | pull_request: 8 | branches: 9 | - main 10 | workflow_call: 11 | 12 | permissions: 13 | contents: read 14 | 15 | concurrency: 16 | cancel-in-progress: true 17 | group: ${{ github.workflow }}-${{ github.event_name == 'pull_request_target' && github.head_ref || github.ref }} 18 | 19 | jobs: 20 | autofix: 21 | name: Format code 22 | runs-on: ubuntu-latest 23 | steps: 24 | - name: Checkout 25 | uses: actions/checkout@v4 26 | 27 | - name: Install pnpm 28 | uses: pnpm/action-setup@v4 29 | 30 | - name: Install Node.js 31 | uses: actions/setup-node@v4 32 | with: 33 | cache: pnpm 34 | node-version: 18 35 | 36 | - name: Install dependencies 37 | run: pnpm install 38 | 39 | - name: Format code 40 | run: pnpm format 41 | 42 | - name: Run autofix 43 | uses: autofix-ci/action@ff86a557419858bb967097bfc916833f5647fa8c 44 | with: 45 | fail-fast: false 46 | -------------------------------------------------------------------------------- /.github/workflows/integration.yml: -------------------------------------------------------------------------------- 1 | name: integration 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | pull_request: 8 | branches: 9 | - main 10 | workflow_call: 11 | 12 | concurrency: 13 | cancel-in-progress: true 14 | group: ${{ github.workflow }}-${{ github.event_name == 'pull_request_target' && github.head_ref || github.ref }} 15 | 16 | jobs: 17 | lint_test: 18 | name: Lint & Test 19 | runs-on: ubuntu-latest 20 | steps: 21 | - name: Checkout 22 | uses: actions/checkout@v4 23 | 24 | - name: Install pnpm 25 | uses: pnpm/action-setup@v4 26 | 27 | - name: Install Node.js 28 | uses: actions/setup-node@v4 29 | with: 30 | cache: pnpm 31 | node-version: 18 32 | 33 | - name: Install dependencies 34 | run: pnpm install 35 | 36 | - name: Lint 37 | run: pnpm lint 38 | -------------------------------------------------------------------------------- /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: release 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | 8 | jobs: 9 | changeset: 10 | name: Changeset 11 | if: ${{ github.repository_owner == 'hideoo' }} 12 | runs-on: ubuntu-latest 13 | permissions: 14 | contents: write 15 | id-token: write 16 | pull-requests: write 17 | steps: 18 | - name: Checkout 19 | uses: actions/checkout@v4 20 | with: 21 | fetch-depth: 0 22 | 23 | - name: Install pnpm 24 | uses: pnpm/action-setup@v4 25 | 26 | - name: Install Node.js 27 | uses: actions/setup-node@v4 28 | with: 29 | cache: pnpm 30 | node-version: 18 31 | 32 | - name: Install dependencies 33 | run: pnpm install 34 | 35 | - name: Create Release Pull Request or Publish 36 | uses: changesets/action@v1 37 | with: 38 | version: pnpm run version 39 | publish: pnpm changeset publish 40 | commit: 'ci: release' 41 | title: 'ci: release' 42 | env: 43 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 44 | NPM_TOKEN: ${{ secrets.NPM_TOKEN }} 45 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .astro 2 | .DS_Store 3 | .eslintcache 4 | .idea 5 | .next 6 | .turbo 7 | .vercel 8 | .vscode/* 9 | !.vscode/extensions.json 10 | !.vscode/launch.json 11 | !.vscode/settings.json 12 | !.vscode/tasks.json 13 | .vscode-test 14 | .vscode-test-web 15 | *.local 16 | *.log 17 | *.pem 18 | *.tsbuildinfo 19 | app 20 | build 21 | coverage 22 | dist 23 | dist-ssr 24 | lerna-debug.log* 25 | logs 26 | next-env.d.ts 27 | node_modules 28 | npm-debug.log* 29 | out 30 | pnpm-debug.log* 31 | releases 32 | test-results 33 | yarn-debug.log* 34 | yarn-error.log* 35 | -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- 1 | .eslintcache 2 | .github 3 | .husky 4 | .prettierignore 5 | .vscode 6 | eslint.config.mjs 7 | /src 8 | /tsconfig.json 9 | tsconfig.tsbuildinfo 10 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | .astro 2 | .changeset 3 | .github/blocks 4 | .next 5 | .vercel 6 | .vscode-test 7 | .vscode-test-web 8 | build 9 | coverage 10 | dist 11 | dist-ssr 12 | out 13 | pnpm-lock.yaml 14 | templates 15 | -------------------------------------------------------------------------------- /.vscode/extensions.json: -------------------------------------------------------------------------------- 1 | { 2 | "recommendations": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"] 3 | } 4 | -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "eslint.useFlatConfig": true, 3 | "eslint.validate": [ 4 | "javascript", 5 | "javascriptreact", 6 | "typescript", 7 | "typescriptreact", 8 | "html", 9 | "vue", 10 | "markdown", 11 | "astro" 12 | ] 13 | } 14 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # @hideoo/generator-starlight-plugin 2 | 3 | ## 0.7.0 4 | 5 | ### Minor Changes 6 | 7 | - [#17](https://github.com/HiDeoo/generator-starlight-plugin/pull/17) [`6ad5097`](https://github.com/HiDeoo/generator-starlight-plugin/commit/6ad50973240bdc30201d71f217497eb3f28a864a) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Improves the overall experience by asking first if the generated plugin is a theme or not. 8 | 9 | - [#17](https://github.com/HiDeoo/generator-starlight-plugin/pull/17) [`6ad5097`](https://github.com/HiDeoo/generator-starlight-plugin/commit/6ad50973240bdc30201d71f217497eb3f28a864a) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Improves the generated documentation for themes: 10 | 11 | - Adds a kitchen sink page and many other example pages to easily preview and test themes. 12 | - Adds a new documentation page on how users can customize themes with or without using cascade layers. 13 | 14 | ## 0.6.0 15 | 16 | ### Minor Changes 17 | 18 | - [#15](https://github.com/HiDeoo/generator-starlight-plugin/pull/15) [`a3941f8`](https://github.com/HiDeoo/generator-starlight-plugin/commit/a3941f80de6c64e9084c0351a3208c1b438c9d46) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for scaffolding themes. 19 | 20 | ## 0.5.1 21 | 22 | ### Patch Changes 23 | 24 | - [#13](https://github.com/HiDeoo/generator-starlight-plugin/pull/13) [`25eb69c`](https://github.com/HiDeoo/generator-starlight-plugin/commit/25eb69c006dec3bf96571f6eca1be155cb6993fd) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes an invalid Starlight plugin hook name in a comment of the generated plugin. 25 | 26 | ## 0.5.0 27 | 28 | ### Minor Changes 29 | 30 | - [#11](https://github.com/HiDeoo/generator-starlight-plugin/pull/11) [`6d17a1c`](https://github.com/HiDeoo/generator-starlight-plugin/commit/6d17a1ccb3f8b968d5496aee8f80195cacc75e29) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for Starlight v0.33.0. 31 | 32 | ## 0.4.0 33 | 34 | ### Minor Changes 35 | 36 | - [#9](https://github.com/HiDeoo/generator-starlight-plugin/pull/9) [`491ff8c`](https://github.com/HiDeoo/generator-starlight-plugin/commit/491ff8ce583b650cb0668efbd12306401bdb88bf) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds a new prompt asking for a single emoji representing the generated Starlight plugin. 37 | 38 | The emoji will be used in the generated documentation and README files. 39 | 40 | ## 0.3.0 41 | 42 | ### Minor Changes 43 | 44 | - [#7](https://github.com/HiDeoo/generator-starlight-plugin/pull/7) [`410f8de`](https://github.com/HiDeoo/generator-starlight-plugin/commit/410f8dedcafdc26522a095879f56b81b9d498f37) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for Starlight v0.32.0 and generates plugin using the new [`config:setup`](https://starlight.astro.build/reference/plugins/#configsetup) configuration setup hook. 45 | 46 | ## 0.2.0 47 | 48 | ### Minor Changes 49 | 50 | - [#5](https://github.com/HiDeoo/generator-starlight-plugin/pull/5) [`3e497ee`](https://github.com/HiDeoo/generator-starlight-plugin/commit/3e497ee69fbbdf9f8c9a4ef277f6ee45cb456b70) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for Starlight v0.30.0 and generates plugin documentation using Astro's new Content Layer API. 51 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024-present, HiDeoo 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |
2 |

generator-starlight-plugin 🔋

3 |

Yeoman generator for Starlight plugins.

4 |
5 | 6 |
7 | 8 | Integration Status 9 | 10 | 11 | License 12 | 13 |
14 |
15 | 16 | ## Features 17 | 18 | An **opinionated** but still **lightweight** Yeoman generator to help create Starlight plugins. 19 | 20 | - **opinionated**: [Git](https://git-scm.com/) and [pnpm](https://pnpm.io/) are required to generate a monorepo containing a Starlight plugin package and a Starlight documentation project acting at the same time as a playground to test your plugin. The plugin is expected to be written in TypeScript, hosted on GitHub, and licensed under the MIT license. 21 | - **lightweight**: Formatting, linting, testing, bundling, publishing, deploying the documentation, which are all optional for a Starlight plugin, are not enforced by the generator. You are free to add them to your project as you see fit using the tools and services you prefer. 22 | 23 | ## Usage 24 | 25 | To use the generator, run the following command in your terminal from the directory where you want to work on your plugin: 26 | 27 | ```shell 28 | npx -p yo -p @hideoo/generator-starlight-plugin -- yo @hideoo/starlight-plugin 29 | ``` 30 | 31 | To start creating your Starlight plugin, edit the `packages/plugin-name/index.ts` file which will be the entry point of your plugin. 32 | 33 | To test your plugin, run the following command from the `docs/` directory: 34 | 35 | ```shell 36 | pnpm dev 37 | ``` 38 | 39 | To learn more about plugin development, check the [Starlight documentation](https://starlight.astro.build/reference/plugins/). 40 | 41 | ## Project Structure 42 | 43 | The generated project uses a monorepo structure with different pnpm workspaces: 44 | 45 | - `docs/`: A Starlight documentation project to document your plugin that also acts as a playground to test it. 46 | - `packages/plugin-name/`: A package containing your Starlight plugin. 47 | 48 | ## Resources 49 | 50 | The generated project contains the bare minimum to get started with a Starlight plugin. Here are some additional resources to help you develop and release your plugin: 51 | 52 | - [Starlight Documentation](https://starlight.astro.build/) 53 | - [Starlight Plugins Reference](https://starlight.astro.build/reference/plugins/) 54 | - [Starlight Plugins Showcase](https://starlight.astro.build/resources/plugins/) 55 | - [Astro Documentation](https://docs.astro.build/) 56 | - [Astro Integration API](https://docs.astro.build/en/reference/integrations-reference/) 57 | - [Astro “Deploy your site” guide](https://docs.astro.build/en/guides/deploy/) 58 | - [Astro Discord](https://astro.build/chat/) 59 | - [npm Registry Publishing Guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry) 60 | 61 | > [!TIP] 62 | > After [deploying](https://docs.astro.build/en/guides/deploy/) your documentation, add a link to it in the `packages/plugin-name/README.md` file to help users find it. 63 | 64 | ## License 65 | 66 | Licensed under the MIT License, Copyright © HiDeoo. 67 | 68 | See [LICENSE](https://github.com/HiDeoo/generator-starlight-plugin/blob/main/LICENSE) for more information. 69 | -------------------------------------------------------------------------------- /eslint.config.mjs: -------------------------------------------------------------------------------- 1 | import hideoo from '@hideoo/eslint-config' 2 | 3 | export default hideoo([ 4 | { 5 | ignores: ['templates/'], 6 | }, 7 | ]) 8 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@hideoo/generator-starlight-plugin", 3 | "version": "0.7.0", 4 | "license": "MIT", 5 | "description": "Yeoman generator for Starlight plugins.", 6 | "author": "HiDeoo (https://hideoo.dev)", 7 | "type": "module", 8 | "scripts": { 9 | "dev": "tsc --watch", 10 | "build": "tsc", 11 | "lint": "eslint . --cache --max-warnings=0 && tsc --noEmit", 12 | "format": "prettier -w --cache --ignore-unknown .", 13 | "version": "pnpm changeset version && pnpm i --no-frozen-lockfile", 14 | "prepublishOnly": "pnpm build" 15 | }, 16 | "dependencies": { 17 | "camelcase": "^8.0.0", 18 | "latest-version": "^9.0.0", 19 | "yeoman-generator": "^7.4.0" 20 | }, 21 | "devDependencies": { 22 | "@changesets/changelog-github": "^0.5.0", 23 | "@changesets/cli": "^2.27.10", 24 | "@hideoo/eslint-config": "^4.0.0", 25 | "@hideoo/prettier-config": "^2.0.0", 26 | "@hideoo/tsconfig": "^2.0.1", 27 | "eslint": "^9.17.0", 28 | "prettier": "^3.4.2", 29 | "typescript": "^5.7.2" 30 | }, 31 | "engines": { 32 | "node": ">=18" 33 | }, 34 | "packageManager": "pnpm@9.9.0", 35 | "publishConfig": { 36 | "access": "public", 37 | "provenance": true 38 | }, 39 | "sideEffects": false, 40 | "keywords": [ 41 | "yeoman-generator", 42 | "starlight", 43 | "plugin", 44 | "documentation", 45 | "astro" 46 | ], 47 | "homepage": "https://github.com/HiDeoo/generator-starlight-plugin", 48 | "repository": { 49 | "type": "git", 50 | "url": "https://github.com/HiDeoo/generator-starlight-plugin.git" 51 | }, 52 | "bugs": "https://github.com/HiDeoo/generator-starlight-plugin/issues", 53 | "prettier": "@hideoo/prettier-config" 54 | } 55 | -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- 1 | import path from 'node:path' 2 | 3 | import Generator, { type BaseOptions } from 'yeoman-generator' 4 | 5 | import { copy, copyTpl } from './libs/fs.js' 6 | import { fetchDependencyVersions } from './libs/npm.js' 7 | import { 8 | getPluginOrThemeStr, 9 | promptForEmoji, 10 | promptForLayer, 11 | promptForName, 12 | promptForText, 13 | promptForTheme, 14 | } from './libs/prompt.js' 15 | 16 | export default class StarlightPluginGenerator extends Generator { 17 | configuration: Configuration 18 | 19 | constructor(...args: unknown[]) { 20 | super(...args) 21 | 22 | this.description = 'Generates a Starlight plugin ready for development.' 23 | this.sourceRoot(path.join(this.sourceRoot(), '../../templates')) 24 | 25 | this.configuration = { 26 | year: new Date().getFullYear().toString(), 27 | } 28 | 29 | this.option('theme', { type: Boolean, description: 'Define if the plugin is a theme' }) 30 | this.option('name', { type: String, description: 'Name of the Starlight plugin/theme' }) 31 | this.option('description', { type: String, description: 'Description of the Starlight plugin/theme' }) 32 | this.option('emoji', { 33 | type: String, 34 | description: 'Single emoji representing the Starlight plugin/theme (used in the documentation)', 35 | }) 36 | this.option('layer', { type: String, description: 'Name of the theme CSS cascade layer (only used for themes)' }) 37 | this.option('ghUsername', { type: String, description: 'GitHub username' }) 38 | } 39 | 40 | initializing() { 41 | this.log('Welcome to the Starlight plugin generator!\n') 42 | } 43 | 44 | async prompting() { 45 | await promptForTheme(this) 46 | await promptForName(this) 47 | await promptForText( 48 | this, 49 | 'description', 50 | `What is the description of your Starlight ${getPluginOrThemeStr(this)}?`, 51 | `My awesome Starlight ${getPluginOrThemeStr(this)}`, 52 | ) 53 | await promptForEmoji(this) 54 | if (this.configuration.theme) await promptForLayer(this) 55 | await promptForText(this, 'ghUsername', 'What is your GitHub username?', 'ghost') 56 | } 57 | 58 | async configuring() { 59 | this.log.info('Preparing dependencies…') 60 | await fetchDependencyVersions() 61 | } 62 | 63 | writing() { 64 | // root 65 | copy(this, 'vscode', '.vscode') 66 | copy(this, 'gitignore', '.gitignore') 67 | copyTpl(this, 'LICENSE') 68 | copyTpl(this, 'README.md') 69 | copyTpl(this, 'package.json') 70 | copy(this, 'pnpm-workspace.yaml') 71 | 72 | // docs 73 | copyTpl(this, 'docs') 74 | 75 | // packages/plugin 76 | const pluginPath = `packages/${this.configuration.name}` 77 | 78 | copyTpl(this, 'packages/plugin', pluginPath) 79 | copy(this, 'npmignore', `${pluginPath}/.npmignore`) 80 | 81 | // theme-specific content 82 | if (this.configuration.theme) { 83 | copyTpl(this, 'styles.css', `${pluginPath}/styles.css`) 84 | copy(this, 'theme/assets', 'docs/src/assets') 85 | copyTpl(this, 'theme/examples', 'docs/src/content/docs/examples') 86 | copyTpl(this, 'theme/customization.md', 'docs/src/content/docs/customization.md') 87 | } 88 | } 89 | 90 | install() { 91 | // @ts-expect-error - Environment options are not typed. 92 | // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access 93 | this.env.options.nodePackageManager = 'pnpm' 94 | } 95 | 96 | async end() { 97 | this.log.info('Initializing Git repository…') 98 | await this.spawn('git', ['init', '--quiet']) 99 | 100 | this.log(`\nYour Starlight ${getPluginOrThemeStr(this)} has been successfully created!\n`) 101 | this.log( 102 | `Edit the 'packages/${this.configuration.name}/index.ts' file to start developing your ${getPluginOrThemeStr(this)}.`, 103 | ) 104 | this.log('For more information, also visit https://starlight.astro.build/') 105 | } 106 | } 107 | 108 | export interface Configuration { 109 | name?: string 110 | description?: string 111 | emoji?: string 112 | ghUsername?: string 113 | layer?: string 114 | theme?: boolean 115 | year: string 116 | } 117 | -------------------------------------------------------------------------------- /src/libs/fs.ts: -------------------------------------------------------------------------------- 1 | import camelCase from 'camelcase' 2 | 3 | import type StarlightPluginGenerator from '../index.js' 4 | 5 | import { getLatestMinorVersion, getLatestVersion } from './npm.js' 6 | 7 | export function copyTpl(generator: StarlightPluginGenerator, from: string, to?: string) { 8 | generator.fs.copyTpl( 9 | generator.templatePath(from), 10 | generator.destinationPath(to ?? from), 11 | getTemplateContext(generator), 12 | ) 13 | } 14 | 15 | export function copy(generator: StarlightPluginGenerator, from: string, to?: string) { 16 | generator.fs.copy(generator.templatePath(from), generator.destinationPath(to ?? from)) 17 | } 18 | 19 | function getTemplateContext(generator: StarlightPluginGenerator) { 20 | return { 21 | ...generator.configuration, 22 | importName: generator.configuration.name ? camelCase(generator.configuration.name) : generator.configuration.name, 23 | dep(pkg: string) { 24 | return `"${pkg}": "^${getLatestVersion(pkg)}"` 25 | }, 26 | peerDep(pkg: string) { 27 | return `"${pkg}": ">=${getLatestMinorVersion(pkg)}"` 28 | }, 29 | } 30 | } 31 | -------------------------------------------------------------------------------- /src/libs/npm.ts: -------------------------------------------------------------------------------- 1 | import latestVersion from 'latest-version' 2 | 3 | // A list of dependencies to fetch versions for and can be used synchronously in templates. 4 | const dependencies = new Set(['@astrojs/starlight', 'astro', 'sharp']) 5 | 6 | // A map of dependencies and their latest versions. 7 | const versions = new Map() 8 | 9 | export async function fetchDependencyVersions() { 10 | for (const pkg of dependencies) { 11 | versions.set(pkg, await latestVersion(pkg)) 12 | } 13 | } 14 | 15 | export function getLatestVersion(pkg: string) { 16 | const version = versions.get(pkg) 17 | 18 | if (version) return version 19 | 20 | throw new Error(`Latest version for '${pkg}' not found.`) 21 | } 22 | 23 | export function getLatestMinorVersion(pkg: string) { 24 | const version = versions.get(pkg) 25 | 26 | if (version) return version.split('.').slice(0, 2).join('.') 27 | 28 | throw new Error(`Latest minor version for '${pkg}' not found.`) 29 | } 30 | -------------------------------------------------------------------------------- /src/libs/prompt.ts: -------------------------------------------------------------------------------- 1 | import type StarlightPluginGenerator from '../index.js' 2 | import type { Configuration } from '../index.js' 3 | 4 | import { validateEmoji, validateLayer, validateName, validateNonEmptyString } from './validator.js' 5 | 6 | export function getPluginOrThemeStr(generator: StarlightPluginGenerator) { 7 | return generator.configuration.theme ? 'theme' : 'plugin' 8 | } 9 | 10 | export async function promptForName(generator: StarlightPluginGenerator) { 11 | const name = generator.options.name 12 | 13 | if (name && validateName(name) === true) { 14 | generator.configuration.name = name 15 | return 16 | } 17 | 18 | const answers = await generator.prompt<{ name: string }>({ 19 | type: 'input', 20 | name: 'name', 21 | message: `What is the name of your Starlight ${getPluginOrThemeStr(generator)}?`, 22 | default: `starlight-${getPluginOrThemeStr(generator)}-name`, 23 | validate: validateName, 24 | }) 25 | 26 | generator.configuration.name = answers.name 27 | } 28 | 29 | export async function promptForTheme(generator: StarlightPluginGenerator) { 30 | const theme = generator.options.theme 31 | 32 | if (theme !== undefined) { 33 | generator.configuration.theme = theme 34 | return 35 | } 36 | 37 | const answers = await generator.prompt<{ theme: boolean }>({ 38 | type: 'list', 39 | name: 'theme', 40 | message: 'Is your plugin a theme?', 41 | choices: [ 42 | { name: 'Yes', value: true }, 43 | { name: 'No', value: false }, 44 | ], 45 | default: false, 46 | }) 47 | 48 | generator.configuration.theme = answers.theme 49 | } 50 | 51 | export async function promptForText( 52 | generator: StarlightPluginGenerator, 53 | key: TextConfigurationKeys, 54 | message: string, 55 | defaultValue: string, 56 | ) { 57 | const text = generator.options[key] 58 | 59 | if (text) { 60 | generator.configuration[key] = text 61 | return 62 | } 63 | 64 | const answers = await generator.prompt>({ 65 | type: 'input', 66 | name: key, 67 | message, 68 | default: defaultValue, 69 | validate: validateNonEmptyString, 70 | }) 71 | 72 | generator.configuration[key] = answers[key] 73 | } 74 | 75 | export async function promptForEmoji(generator: StarlightPluginGenerator) { 76 | const emoji = generator.options.emoji 77 | 78 | if (emoji && validateEmoji(emoji) === true) { 79 | generator.configuration.emoji = emoji 80 | return 81 | } 82 | 83 | const answers = await generator.prompt<{ emoji: string }>({ 84 | type: 'input', 85 | name: 'emoji', 86 | message: `What single emoji represents your Starlight ${getPluginOrThemeStr(generator)}?`, 87 | default: generator.configuration.theme ? '🎨' : '🔋', 88 | suffix: ' (used in the documentation)', 89 | validate: validateEmoji, 90 | }) 91 | 92 | generator.configuration.emoji = answers.emoji 93 | } 94 | 95 | export async function promptForLayer(generator: StarlightPluginGenerator) { 96 | const layer = generator.options.layer 97 | 98 | if (layer && validateLayer(layer) === true) { 99 | generator.configuration.layer = layer 100 | return 101 | } 102 | 103 | const answers = await generator.prompt<{ layer: string }>({ 104 | type: 'input', 105 | name: 'layer', 106 | message: 'What is the name of your theme CSS cascade layer?', 107 | default: `my-theme`, 108 | validate: validateLayer, 109 | }) 110 | 111 | generator.configuration.layer = answers.layer 112 | } 113 | 114 | type TextConfigurationKeys = NonNullable< 115 | { 116 | [K in keyof Configuration]: Configuration[K] extends string | undefined ? K : never 117 | }[keyof Configuration] 118 | > 119 | -------------------------------------------------------------------------------- /src/libs/validator.ts: -------------------------------------------------------------------------------- 1 | const nameValidationRegex = /^(?:@[\da-z~-][\d._a-z~-]*\/)?[\da-z~-][\d._a-z~-]*$/ 2 | const emojiValidationRegex = /^\p{Emoji_Presentation}\p{Emoji_Modifier}*$/u 3 | const layerValidationRegex = /^[a-zA-Z][_a-zA-Z0-9-]*$/ 4 | 5 | export function validateName(name: string) { 6 | return nameValidationRegex.test(name) ? true : 'Invalid plugin name' 7 | } 8 | 9 | export function validateNonEmptyString(value: string) { 10 | return value.trim().length > 0 ? true : 'Value cannot be empty' 11 | } 12 | 13 | export function validateEmoji(emoji: string) { 14 | return emojiValidationRegex.test(emoji) ? true : 'Invalid emoji' 15 | } 16 | 17 | export function validateLayer(name: string) { 18 | return layerValidationRegex.test(name) ? true : 'Invalid theme CSS cascade layer name' 19 | } 20 | -------------------------------------------------------------------------------- /templates/LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) <%= year %>-present, <%= ghUsername %> 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /templates/README.md: -------------------------------------------------------------------------------- 1 | # `<%= name %>` <%= emoji %> 2 | 3 | <%= description %> 4 | 5 | ## Package 6 | 7 | If you are looking for the Starlight plugin package, you can find it in the [`packages/<%= name %>/`](/packages/<%= name %>/) directory. 8 | 9 | ## Project structure 10 | 11 | This project uses pnpm workspaces to develop a single Starlight plugin from the `packages/<%= name %>/` directory. A Starlight documentation site is also available in the `docs/` directory that is also used for testing and demonstrating the Starlight plugin. 12 | 13 | ## License 14 | 15 | Licensed under the MIT License, Copyright © <%= ghUsername %>. 16 | 17 | See [LICENSE](/LICENSE) for more information. 18 | -------------------------------------------------------------------------------- /templates/docs/README.md: -------------------------------------------------------------------------------- 1 | # `<%= name %>` 2 | 3 | <%= description %> 4 | 5 | ## Documentation 6 | 7 | Run the documentation locally by running the following command in your terminal: 8 | 9 | ```shell 10 | pnpm run dev 11 | ``` 12 | 13 | Content can be found in the [`src/content/docs/`](./src/content/docs/) directory. 14 | 15 | ## License 16 | 17 | Licensed under the MIT License, Copyright © <%= ghUsername %>. 18 | 19 | See [LICENSE](/LICENSE) for more information. 20 | -------------------------------------------------------------------------------- /templates/docs/astro.config.ts: -------------------------------------------------------------------------------- 1 | import starlight from '@astrojs/starlight' 2 | import { defineConfig } from 'astro/config' 3 | import <%= importName %> from '<%= name %>' 4 | 5 | export default defineConfig({ 6 | integrations: [ 7 | starlight({ 8 | editLink: { 9 | baseUrl: 'https://github.com/<%= ghUsername %>/<%= name %>/edit/main/docs/', 10 | }, 11 | plugins: [<%= importName %>()], 12 | sidebar: [ 13 | { 14 | label: 'Start Here', 15 | items: ['getting-started'<% if (theme) { %>, 'customization'<% } %>], 16 | }, 17 | <% if (theme) { %> { label: 'Examples', autogenerate: { directory: 'examples' } }, 18 | <% } -%> 19 | ], 20 | social: [ 21 | { href: 'https://github.com/<%= ghUsername %>/<%= name %>', icon: 'github', label: 'GitHub' }, 22 | ], 23 | title: '<%= name %>', 24 | }), 25 | ], 26 | }) 27 | -------------------------------------------------------------------------------- /templates/docs/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "<%= name %>-docs", 3 | "version": "0.0.1", 4 | "license": "MIT", 5 | "description": "<%= description %>", 6 | "author": "<%= ghUsername %>", 7 | "type": "module", 8 | "scripts": { 9 | "dev": "astro dev", 10 | "start": "astro dev", 11 | "build": "astro build", 12 | "preview": "astro preview", 13 | "astro": "astro" 14 | }, 15 | "dependencies": { 16 | <%- dep("@astrojs/starlight") %>, 17 | <%- dep("astro") %>, 18 | <%- dep("sharp") %>, 19 | "<%= name %>": "workspace:*" 20 | }, 21 | "engines": { 22 | "node": "^18.17.1 || ^20.3.0 || >=21.0.0" 23 | }, 24 | "private": true, 25 | "homepage": "https://github.com/<%= ghUsername %>/<%= name %>", 26 | "repository": { 27 | "type": "git", 28 | "url": "https://github.com/<%= ghUsername %>/<%= name %>.git", 29 | "directory": "docs" 30 | }, 31 | "bugs": "https://github.com/<%= ghUsername %>/<%= name %>/issues" 32 | } 33 | -------------------------------------------------------------------------------- /templates/docs/public/favicon.svg: -------------------------------------------------------------------------------- 1 | <%= emoji %> 2 | -------------------------------------------------------------------------------- /templates/docs/src/content.config.ts: -------------------------------------------------------------------------------- 1 | import { defineCollection } from 'astro:content' 2 | import { docsLoader } from '@astrojs/starlight/loaders'; 3 | import { docsSchema } from '@astrojs/starlight/schema' 4 | 5 | export const collections = { 6 | docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }), 7 | } 8 | -------------------------------------------------------------------------------- /templates/docs/src/content/docs/getting-started.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting Started 3 | --- 4 | 5 | <%= description %> 6 | 7 | ## Prerequisites 8 | 9 | You will need to have a Starlight website set up. 10 | If you don't have one yet, you can follow the ["Getting Started"](https://starlight.astro.build/getting-started) guide in the Starlight docs to create one. 11 | 12 | ## Installation 13 | 14 | import { Steps, Tabs, TabItem } from '@astrojs/starlight/components' 15 | 16 | 17 | 18 | 1. `<%= name %>` is a Starlight [plugin](https://starlight.astro.build/reference/plugins/). Install it by running the following command in your terminal: 19 | 20 | 21 | 22 | 23 | 24 | ```sh 25 | npm install <%= name %> 26 | ``` 27 | 28 | 29 | 30 | 31 | 32 | ```sh 33 | pnpm add <%= name %> 34 | ``` 35 | 36 | 37 | 38 | 39 | 40 | ```sh 41 | yarn add <%= name %> 42 | ``` 43 | 44 | 45 | 46 | 47 | 48 | 2. Configure the plugin in your Starlight [configuration](https://starlight.astro.build/reference/configuration/#plugins) in the `astro.config.mjs` file. 49 | 50 | ```diff lang="js" 51 | // astro.config.mjs 52 | import starlight from '@astrojs/starlight' 53 | import { defineConfig } from 'astro/config' 54 | +import <%= importName %> from '<%= name %>' 55 | 56 | export default defineConfig({ 57 | integrations: [ 58 | starlight({ 59 | + plugins: [<%= importName %>()], 60 | title: 'My Docs', 61 | }), 62 | ], 63 | }) 64 | ``` 65 | 66 | 3. [Start the development server](https://starlight.astro.build/getting-started/#start-the-development-server) to preview the <% if(theme){ %>theme<% } else{ %>plugin<% } %> in action. 67 | 68 | 69 | -------------------------------------------------------------------------------- /templates/docs/src/content/docs/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: <%= name %> 3 | description: <%= description %> 4 | head: 5 | - tag: title 6 | content: <%= name %> 7 | - tag: style 8 | content: | 9 | .hero-html { 10 | --size: 12rem; 11 | font-size: var(--size); 12 | justify-content: center; 13 | line-height: var(--size); 14 | } 15 | template: splash 16 | editUrl: false 17 | hero: 18 | tagline: <%= description %> 19 | image: 20 | html: '<%= emoji %>' 21 | actions: 22 | - text: Get Started 23 | link: /getting-started/ 24 | icon: right-arrow 25 | <% if (theme) { %> - text: Examples 26 | link: /examples/kitchen-sink/ 27 | icon: right-arrow 28 | variant: minimal 29 | <% } -%> 30 | --- 31 | 32 | import { Card, CardGrid } from '@astrojs/starlight/components' 33 | 34 | ## Next steps 35 | 36 | 37 | 38 | Check the [getting started guide](/getting-started/) for installation instructions. 39 | 40 | 41 | Edit your config in the `astro.config.mjs` file. 42 | 43 | <% if (theme) { %> 44 | Check out the [example pages](/examples/kitchen-sink/) to see the theme in action. 45 | 46 | 47 | Learn more in the [`<%= name %>` documentation](/getting-started/). 48 | 49 | <% } -%> 50 | 51 | -------------------------------------------------------------------------------- /templates/docs/tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "astro/tsconfigs/strictest" 3 | } 4 | -------------------------------------------------------------------------------- /templates/gitignore: -------------------------------------------------------------------------------- 1 | # build output 2 | dist/ 3 | # generated types 4 | .astro/ 5 | 6 | # dependencies 7 | node_modules/ 8 | 9 | # logs 10 | npm-debug.log* 11 | yarn-debug.log* 12 | yarn-error.log* 13 | pnpm-debug.log* 14 | 15 | 16 | # environment variables 17 | .env 18 | .env.production 19 | 20 | # macOS-specific files 21 | .DS_Store 22 | -------------------------------------------------------------------------------- /templates/npmignore: -------------------------------------------------------------------------------- 1 | tsconfig.json 2 | -------------------------------------------------------------------------------- /templates/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "<%= name %>-monorepo", 3 | "version": "0.0.1", 4 | "license": "MIT", 5 | "description": "<%= description %>", 6 | "author": "<%= ghUsername %>", 7 | "type": "module", 8 | "engines": { 9 | "node": "^18.17.1 || ^20.3.0 || >=21.0.0" 10 | }, 11 | "packageManager": "pnpm@9.6.0", 12 | "private": true, 13 | "homepage": "https://github.com/<%= ghUsername %>/<%= name %>", 14 | "repository": { 15 | "type": "git", 16 | "url": "https://github.com/<%= ghUsername %>/<%= name %>.git" 17 | }, 18 | "bugs": "https://github.com/<%= ghUsername %>/<%= name %>/issues" 19 | } 20 | -------------------------------------------------------------------------------- /templates/packages/plugin/README.md: -------------------------------------------------------------------------------- 1 | # `<%= name %>` 2 | 3 | <%= description %> 4 | 5 | ## Documentation 6 | 7 | Want to get started immediately? 8 | 9 | Check out the `<%= name %>` getting started guide. 10 | 11 | ## License 12 | 13 | Licensed under the MIT License, Copyright © <%= ghUsername %>. 14 | 15 | See [LICENSE](https://github.com/<%= ghUsername %>/<%= name %>/blob/main/LICENSE) for more information. 16 | -------------------------------------------------------------------------------- /templates/packages/plugin/index.ts: -------------------------------------------------------------------------------- 1 | import type { StarlightPlugin } from '@astrojs/starlight/types' 2 | 3 | export default function <%= importName %>(): StarlightPlugin { 4 | return { 5 | name: '<%= name %>', 6 | hooks: { 7 | 'config:setup'({ <% if(theme){ %>config, logger, updateConfig<% } else{ %>logger<% } %> }) { 8 | /** 9 | * This is the entry point of your Starlight plugin. 10 | * The `config:setup` hook is called when Starlight is initialized (during the Astro `astro:config:setup` 11 | * integration hook). 12 | * To learn more about the Starlight plugin API and all available options in this hook, check the Starlight 13 | * plugins reference. 14 | * 15 | * @see https://starlight.astro.build/reference/plugins/ 16 | */ 17 | logger.info('Hello from the <%= name %> plugin!') 18 | <% if (theme) { %> 19 | /** 20 | * Update the provided Starlight user configuration by appending the theme CSS file to the `customCss` array. 21 | * To start customizing your theme, edit the `packages/<%= name %>/styles.css` file. 22 | * 23 | * @see https://starlight.astro.build/reference/plugins/#updateconfig 24 | * @see https://starlight.astro.build/reference/configuration/#customcss 25 | */ 26 | updateConfig({ 27 | customCss: [...(config.customCss ?? []), '<%= name %>/styles'], 28 | }) 29 | <% } -%> }, 30 | }, 31 | } 32 | } 33 | -------------------------------------------------------------------------------- /templates/packages/plugin/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "<%= name %>", 3 | "version": "0.0.1", 4 | "license": "MIT", 5 | "description": "<%= description %>", 6 | "author": "<%= ghUsername %>", 7 | "type": "module", 8 | "exports": { 9 | ".": "./index.ts"<% if (theme) { %>, 10 | "./styles": "./styles.css"<% } %> 11 | }, 12 | "devDependencies": { 13 | <%- dep("@astrojs/starlight") %>, 14 | <%- dep("astro") %> 15 | }, 16 | "peerDependencies": { 17 | <%- peerDep("@astrojs/starlight") %> 18 | }, 19 | "engines": { 20 | "node": "^18.17.1 || ^20.3.0 || >=21.0.0" 21 | }, 22 | "publishConfig": { 23 | "access": "public" 24 | }, 25 | "homepage": "https://github.com/<%= ghUsername %>/<%= name %>", 26 | "repository": { 27 | "type": "git", 28 | "url": "https://github.com/<%= ghUsername %>/<%= name %>.git", 29 | "directory": "packages/<%= name %>" 30 | }, 31 | "bugs": "https://github.com/<%= ghUsername %>/<%= name %>/issues" 32 | } 33 | -------------------------------------------------------------------------------- /templates/packages/plugin/tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "astro/tsconfigs/strictest" 3 | } 4 | -------------------------------------------------------------------------------- /templates/pnpm-workspace.yaml: -------------------------------------------------------------------------------- 1 | packages: 2 | - 'docs' 3 | - 'packages/*' 4 | -------------------------------------------------------------------------------- /templates/styles.css: -------------------------------------------------------------------------------- 1 | /** 2 | * Just like Starlight uses cascade layers to manage the order of its styles, the theme will also use its own layer. 3 | * We first define a default, but still overridable, layer order for the theme relative to Starlight's layers. 4 | * 5 | * @see https://starlight.astro.build/guides/css-and-tailwind/#cascade-layers 6 | * @see https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers 7 | */ 8 | @layer starlight, <%= layer %>; 9 | 10 | /** 11 | * Scope the theme styles to its own layer so that user styles can override them easily. 12 | * 13 | * This is where any custom CSS related to the theme should go and the current content is only 14 | * provided for demonstration and documentation purposes. 15 | * 16 | * Feel free to remove it and add your own customizations. 17 | */ 18 | @layer <%= layer %> { 19 | :root, 20 | ::backdrop { 21 | /** 22 | * Override some CSS custom properties used by Starlight for the dark theme. 23 | * 24 | * @see https://github.com/withastro/starlight/blob/main/packages/starlight/style/props.css 25 | */ 26 | --sl-color-accent-low: #002b27; 27 | --sl-color-accent: #007a72; 28 | --sl-color-accent-high: #8cdad0; 29 | --sl-color-white: #ffffff; 30 | --sl-color-gray-1: #ffe6ec; 31 | --sl-color-gray-2: #edadbf; 32 | --sl-color-gray-3: #d45d86; 33 | --sl-color-gray-4: #982353; 34 | --sl-color-gray-5: #6b0034; 35 | --sl-color-gray-6: #4d0024; 36 | --sl-color-black: #320316; 37 | } 38 | 39 | :root[data-theme='light'], 40 | [data-theme='light'] ::backdrop { 41 | /** 42 | * Override some CSS custom properties used by Starlight for the light theme. 43 | */ 44 | --sl-color-accent-low: #abe4dc; 45 | --sl-color-accent: #007169; 46 | --sl-color-accent-high: #003b36; 47 | --sl-color-white: #320316; 48 | --sl-color-gray-1: #4d0024; 49 | --sl-color-gray-2: #6b0034; 50 | --sl-color-gray-3: #982353; 51 | --sl-color-gray-4: #d45d86; 52 | --sl-color-gray-5: #edadbf; 53 | --sl-color-gray-6: #ffe6ec; 54 | --sl-color-gray-7: #fff3f6; 55 | --sl-color-black: #ffffff; 56 | } 57 | 58 | /** 59 | * Add rounded corners to cards. 60 | */ 61 | .card { 62 | border-radius: 0.75rem; 63 | } 64 | } 65 | -------------------------------------------------------------------------------- /templates/theme/assets/hero.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/HiDeoo/generator-starlight-plugin/2e2aad75b2c4f7fd4e242d16ce052c838c9a7fe7/templates/theme/assets/hero.webp -------------------------------------------------------------------------------- /templates/theme/customization.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Customization 3 | --- 4 | 5 | ## Custom CSS 6 | 7 | To customize the styles applied to your Starlight site when using `<%= name %>`, you can provide additional CSS files to modify or extend Starlight and `<%= name %>` default styles. 8 | 9 | [Learn more about custom CSS in the Starlight documentation.](https://starlight.astro.build/guides/css-and-tailwind/#custom-css-styles) 10 | 11 | ## Cascade layers 12 | 13 | Like Starlight, `<%= name %>` uses [cascade layers](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers) internally to manage the order of its styles. 14 | This ensures a predictable CSS order and allows for simpler overrides. 15 | Any custom unlayered CSS will override the default styles from Starlight and `<%= name %>`. 16 | 17 | If you are using cascade layers, you can use [`@layer`](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) in your [custom CSS](https://starlight.astro.build/guides/css-and-tailwind/#custom-css-styles) to define the order of precedence for different layers relative to styles from the `starlight` and `<%= layer %>` layers: 18 | 19 | ```css "starlight" "<%= layer %>" 20 | /* src/styles/custom.css */ 21 | @layer my-reset, starlight, <%= layer %>, my-overrides; 22 | ``` 23 | 24 | The example above defines a custom layer named `my-reset`, applied before all Starlight and `<%= name %>` layers, and another named `my-overrides`, applied after all Starlight and `<%= name %>` layers. 25 | Any styles in the `my-overrides` layer would take precedence over Starlight and `<%= name %>` styles, but Starlight or `<%= name %>` could still change styles set in the `my-reset` layer. 26 | -------------------------------------------------------------------------------- /templates/theme/examples/asides.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Asides 3 | pagefind: false 4 | --- 5 | 6 | ## Markdown asides 7 | 8 | Asides rendered with the [custom Markdown syntax](https://starlight.astro.build/guides/authoring-content/#asides) using a pair of triple colons `:::` to wrap your content. 9 | 10 | :::note 11 | 12 | A `note` aside with a [link](#_) in the content. 13 | 14 | ::: 15 | 16 | :::tip 17 | 18 | A `tip` aside with a [link](#_) in the content. 19 | 20 | ::: 21 | 22 | :::caution 23 | 24 | A `caution` aside with a [link](#_) in the content. 25 | 26 | ::: 27 | 28 | :::danger 29 | 30 | A `danger` aside with a [link](#_) in the content. 31 | 32 | ::: 33 | 34 | ## Component asides 35 | 36 | Asides rendered with the [`