@chassis-ui/docs 0.5.0 → 0.6.0-next.0

package/UPGRADING.md

@@ -0,0 +1,243 @@
+# Upgrading @chassis-ui/docs
+
+## From 0.5 to 0.6
+
+0.6.0 is a breaking release. In 0.5 a site had to supply five modules behind a `@libs/*`
+path alias, and every site carried its own copy of them. In 0.6 the package owns that code.
+A site adds one integration and deletes its copies.
+
+Do the steps in order. The build fails with a message that names the step you missed.
+
+### 1. Update the dependency
+
+```sh
+pnpm add -D @chassis-ui/docs@^0.6.0
+```
+
+The package now brings these itself. Remove each one that your own code does not import:
+`js-yaml`, `zod`, `clipboard`, `unified`, `unist-util-visit`, `mdast-util-mdx-jsx`,
+`@types/mdast` and `astro-auto-import`.
+
+### 2. Rename the keys of `config.yml`
+
+| 0.5                   | 0.6                                         |
+| --------------------- | ------------------------------------------- |
+| `current_version`     | `currentVersion`                            |
+| `github_org`          | `githubOrg`                                 |
+| `figma_handle`        | `figmaHandle`                               |
+| `x_username`          | `xUsername`                                 |
+| `analytics.google_id` | `analytics.googleId`                        |
+| `docsDir`             | Delete it. The site root is the Astro root. |
+
+- `githubOrg` is the name of the organisation, such as `chassis-ui`. A URL is rejected.
+- `sourceDir` is now relative to the site's root, not to the working directory of the
+  build. For a site that is built from its own directory, the value stays the same.
+- The schema is strict. A key that the package does not know fails the build. See step 4
+  for the keys of your own, such as `blog`, `download` or `cdn`.
+
+Write your own keys in camelCase too, for example `docsVersion` and `exampleIcon`.
+
+Replace the old names in the content as well:
+
+```sh
+grep -rl '\[\[config:current_version\]\]' content src \
+  | xargs sed -i '' 's/\[\[config:current_version\]\]/[[config:currentVersion]]/g'
+```
+
+Three keys outside `config.yml` were renamed as well. An old name fails the build.
+
+| File                       | 0.5                | 0.6               |
+| -------------------------- | ------------------ | ----------------- |
+| `data/sidebar.yml`         | `icon_color`       | `iconColor`       |
+| Frontmatter of a docs page | `added.show_badge` | `added.showBadge` |
+| Frontmatter of a docs page | `extra_js`         | `extraJs`         |
+
+```sh
+sed -i '' 's/icon_color:/iconColor:/' data/sidebar.yml
+grep -rlE '^ *(show_badge|extra_js):' content \
+  | xargs sed -i '' -E 's/^( *)show_badge:/\1showBadge:/; s/^( *)extra_js:/\1extraJs:/'
+```
+
+Rename them in your own components and collection schemas too, where they read
+`icon_color`, `show_badge` or `extra_js`.
+
+### 3. Replace the Astro configuration
+
+Before:
+
+```ts
+import { chassis } from './src/libs/astro'
+import { getConfig } from './src/libs/config'
+import { remarkCxConfig, remarkCxDocsref } from './src/libs/remark'
+import { chassisAutoImportPlugin } from './src/libs/shortcode'
+import { getSiteUrl, getDocsMarkdownConfig } from '@chassis-ui/docs'
+
+export default defineConfig({
+  site: getSiteUrl(getConfig()),
+  integrations: [chassis()],
+  markdown: getDocsMarkdownConfig({
+    anchors: getConfig().anchors,
+    remarkPlugins: [chassisAutoImportPlugin(), remarkCxConfig, remarkCxDocsref, myPlugin]
+  })
+  // ...
+})
+```
+
+After:
+
+```ts
+import { loadConfig } from '@chassis-ui/docs'
+import { chassisDocs } from '@chassis-ui/docs/integration'
+import { chassis } from './src/libs/astro'
+import { siteConfigSchema } from './src/libs/config'
+
+const root = import.meta.dirname
+const config = loadConfig({ root, schema: siteConfigSchema })
+
+export default defineConfig({
+  integrations: [
+    chassisDocs({ config, markdown: { remarkPlugins: [myPlugin] } }),
+    chassis({ config, root })
+  ]
+  // ...
+})
+```
+
+- Remove `site` and `markdown`. The integration sets both.
+- Pass only your own remark and rehype plugins. `rehypeCxTable` is already included.
+- A site that does not need the config in `astro.config.ts` calls `chassisDocs()` with
+  `configSchema` and does not call `loadConfig()`.
+- Remove the Sass load path that points to `@chassis-ui/css/scss/vendor`, the folder of the
+  default `_chassis-tokens.scss`. The integration adds it, after the site's own load paths.
+  Keep a load path that points to tokens of your own.
+
+### 4. Replace the files in `src/libs`
+
+| File            | What to do                                                                                                                                                  |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `config.ts`     | Replace the content with the schema of your own keys. See below. Delete the file if you have none.                                                          |
+| `validation.ts` | Delete. `zVersionSemver`, `zVersionMajorMinor`, `zPrefixedVersionSemver` and `zLanguageCode` are in `@chassis-ui/docs/schema`. Keep validators of your own. |
+| `clipboard.ts`  | Delete. Import `initCopyButtons` from `@chassis-ui/docs/js/clipboard.ts` if your own code calls it.                                                         |
+| `shortcode.ts`  | Delete. See step 6.                                                                                                                                         |
+| `path.ts`       | Delete. See step 5 for the replacements.                                                                                                                    |
+| `remark.ts`     | Delete `remarkCxConfig`, `remarkCxDocsref` and their helpers. Keep plugins of your own.                                                                     |
+| `data.ts`       | Delete if `sidebar` was the only data you read. Otherwise replace the loader with `createDataLoader()`. See below.                                          |
+| `content.ts`    | Delete `callouts`, `getCalloutByName` and `CalloutName`. Keep the collections that your own pages read.                                                     |
+| `astro.ts`      | Keep. It copies the static files and adds `mdx()` and `sitemap()`. Change it as described below.                                                            |
+
+`src/libs/config.ts`:
+
+```ts
+import { configSchema, z } from '@chassis-ui/docs/schema'
+
+export const siteConfigSchema = configSchema.extend({
+  blog: z.url()
+})
+
+export type SiteConfig = z.infer<typeof siteConfigSchema>
+```
+
+`src/libs/data.ts`, for a site with data files of its own:
+
+```ts
+import { createDataLoader } from '@chassis-ui/docs/site'
+import { z } from '@chassis-ui/docs/schema'
+
+export const getData = createDataLoader({
+  breakpoints: z.object({ name: z.string() }).array()
+})
+```
+
+`src/libs/astro.ts`:
+
+- Take `{ config, root }` as the argument of `chassis()`, and stop calling `getConfig()`.
+- Remove `chassisAutoImportIntegration()` from the list of integrations.
+- Remove the `astro:build:done` hook that calls `validateChassisDocsPaths()`.
+- Import `getChassisAssetsFsPath`, `getChassisCSSFsPath`, `getChassisIconsFsPath` and
+  `getChassisTokensFsPath` from `@chassis-ui/docs` and call them with `{ root }`. Pass
+  `dir` when the folder is not the installed package, as in `chassis-css`, which copies
+  from `../css/dist`.
+- Replace `getDocsFsPath()` with `root`, `getDocsPublicFsPath()` with
+  `path.join(root, 'public')`, and `getDocsStaticFsPath()` with
+  `path.join(root, 'static')`.
+- Remove the Vite alias for `@chassis-ui/css` and `optimizeDeps: { exclude:
+['@chassis-ui/docs'] }`. The integration now makes every script use one copy of
+  `@chassis-ui/css`, in the dev server and in the build. It needs no alias.
+
+### 5. Replace the imports in pages and components
+
+| 0.5                                                 | 0.6                                                |
+| --------------------------------------------------- | -------------------------------------------------- |
+| `getConfig` from `@libs/config`                     | `getConfig` from `@chassis-ui/docs/site`           |
+| `getData('sidebar')` from `@libs/data`              | `getSidebar()` from `@chassis-ui/docs/site`        |
+| `getChassisDocsPath` from `@libs/path`              | `getDocsPath` from `@chassis-ui/docs/site`         |
+| `getDocsFsPath` from `@libs/path`                   | `getSiteRoot` from `@chassis-ui/docs/site`         |
+| `getDocsPublicFsPath` from `@libs/path`             | `getPublicFsPath` from `@chassis-ui/docs/site`     |
+| `getDocsRelativePath(file)` from `@libs/path`       | `getSiteFsPath(file)` from `@chassis-ui/docs/site` |
+| `replaceConfigInText` from `@libs/remark`           | `resolveConfigRefs` from `@chassis-ui/docs/site`   |
+| `replaceDocsrefInText` from `@libs/remark`          | `resolveDocsrefs` from `@chassis-ui/docs/site`     |
+| `getCalloutByName` from `@libs/content`             | `getCallout` from `@chassis-ui/docs/site`          |
+| A path into `node_modules/@chassis-ui/docs/src/`    | `getPackageFilePath('js/color-modes.js')`          |
+| `@chassis-ui/docs/components/shortcodes/Icon.astro` | `@chassis-ui/docs/shortcodes/Icon.astro`           |
+
+Only the paths that the README lists under "Exports" resolve. `@chassis-ui/docs/libs/*`, the
+folders inside `layouts/` and `components/`, and the partials under `scss/` other than `main`
+and `vars` fail with "not exported". Import a layout or component by its name, such as
+`@chassis-ui/docs/layouts/DocsLayout.astro`.
+
+`getConfig()` returns the keys of the package. For the keys of your own, name your type:
+`getConfig<SiteConfig>()`.
+
+Use the schemas of the package in `src/content.config.ts`:
+
+```ts
+import { calloutsSchema, docsSchema } from '@chassis-ui/docs/schema'
+
+const docsCollection = defineCollection({
+  loader: glob({ pattern: '**/*.{md,mdx}', base: './content/docs' }),
+  schema: docsSchema
+})
+```
+
+`docsSchema` is already partial. Do not call `.partial()` on it.
+
+### 6. Shortcodes
+
+- Delete `src/types/auto-import.d.ts`. The integration writes the declarations into
+  `.astro/`.
+- A shortcode in `src/components/shortcodes/` replaces the package's shortcode of the same
+  name. No configuration is needed.
+- To leave out a shortcode of the package, pass
+  `chassisDocs({ shortcodes: { exclude: ['Icon'] } })`.
+
+### 7. Path aliases
+
+The package no longer needs `@libs/*`, `@scss/*` or `@shortcodes/*` in `tsconfig.json`.
+Keep the ones that your own code imports.
+
+The stylesheet that every page loads was `@scss/docs.scss`. It is now `src/scss/docs.scss`
+in the site's root, which is the same file. Pass `styles` to the integration to name
+another one.
+
+### What changes in behaviour
+
+- **Broken `[[docsref:]]` links fail the build.** Five sites only logged them. Fix the
+  links, or pass `brokenDocsrefs: 'warn'` until they are fixed.
+- **A page of the sidebar may have no `title`.** The schema of `data/sidebar.yml` now
+  allows groups, so the type of `title` is `string | undefined`. Code of your own that
+  reads the sidebar has to handle that.
+- **The header shows the Figma and GitHub links only when `figmaHandle` and `githubOrg`
+  are set.** The same holds for the X meta tags and `xUsername`, and for Google Analytics
+  and `analytics.googleId`.
+- **`@chassis-ui/docs` and `@chassis-ui/css` are not pre-bundled in the dev server.** Both
+  are served from source, so a script of the site and a script of the package import the
+  same copy of `@chassis-ui/css`. The dependency `clipboard` is still pre-bundled.
+- **The working directory of the build does not matter.** `config.yml`, `data/` and the
+  `file` props are found from the Astro root. A site that is built with
+  `astro build --root site` no longer names `./site/` in its paths.
+
+### Check the result
+
+Build the site before and after the upgrade and compare the output. An upgrade from 0.5.1
+changes nothing in the output. An upgrade from 0.5.0 or 0.5.0-0 changes the "View on
+GitHub" links, as the changelog describes for 0.5.1.

package/index.ts

@@ -1,11 +1,17 @@
-// Shared libraries for documentation sites
+// Library functions. They are safe to import anywhere: in `astro.config.ts`, in a site's own
+// integrations, and in pages. What pages read from the site is in `@chassis-ui/docs/site`.
+export * from './src/libs/config'
+export * from './src/libs/docs-path'
 export * from './src/libs/highlight'
 export * from './src/libs/image'
 export * from './src/libs/layout'
 export * from './src/libs/markdown'
+export * from './src/libs/paths'
 export * from './src/libs/placeholder'
 export * from './src/libs/rehype'
+export * from './src/libs/remark'
 export * from './src/libs/shortcodes'
 export * from './src/libs/site'
+export * from './src/libs/source'
 export * from './src/libs/toc'
 export * from './src/libs/utils'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chassis-ui/docs",
   "description": "Shared Astro components and layouts for Chassis documentation sites.",
-  "version": "0.5.0",
+  "version": "0.6.0-next.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -25,21 +25,42 @@
   "files": [
     "src",
     "index.ts",
-    "README.md"
+    "virtual.d.ts",
+    "README.md",
+    "UPGRADING.md",
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "main": "index.ts",
   "exports": {
     ".": "./index.ts",
-    "./components/*": "./src/components/*",
+    "./integration": "./src/integration.ts",
+    "./schema": "./src/libs/schema.ts",
+    "./site": "./src/site.ts",
+    "./layouts/BaseLayout.astro": "./src/layouts/BaseLayout.astro",
+    "./layouts/DocsLayout.astro": "./src/layouts/DocsLayout.astro",
+    "./layouts/RedirectLayout.astro": "./src/layouts/RedirectLayout.astro",
+    "./layouts/SingleLayout.astro": "./src/layouts/SingleLayout.astro",
+    "./components/DocsSidebar.astro": "./src/components/DocsSidebar.astro",
+    "./components/FeatureCard.astro": "./src/components/FeatureCard.astro",
+    "./components/NavLink.astro": "./src/components/NavLink.astro",
+    "./components/ResponsiveImage.astro": "./src/components/ResponsiveImage.astro",
+    "./components/TableOfContents.astro": "./src/components/TableOfContents.astro",
+    "./components/ThemeToggler.astro": "./src/components/ThemeToggler.astro",
     "./shortcodes/*": "./src/components/shortcodes/*",
-    "./layouts/*": "./src/layouts/*",
-    "./libs/*": "./src/libs/*",
     "./js/*": "./src/js/*",
-    "./scss/*": "./src/scss/*"
+    "./scss/main": "./src/scss/main.scss",
+    "./scss/main.scss": "./src/scss/main.scss",
+    "./scss/vars": "./src/scss/_vars.scss",
+    "./scss/_vars.scss": "./src/scss/_vars.scss",
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "scripts": {
     "astro": "astro"
   },
@@ -55,18 +76,24 @@
     "shiki": "^4.3.1"
   },
   "dependencies": {
+    "@types/hast": "^3.0.5",
+    "@types/mdast": "^4.0.4",
+    "clipboard": "^2.0.11",
     "github-slugger": "^2.0.0",
-    "image-size": "^2.0.2",
+    "image-size": "^2.0.4",
+    "js-yaml": "^5.4.2",
     "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-mdx-jsx": "^3.2.0",
     "mdast-util-to-string": "^4.0.0",
     "medium-zoom": "^1.1.0",
     "remark": "^15.0.1",
     "remark-html": "^16.0.1",
+    "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
-    "@types/hast": "^3.0.4",
-    "astro": "^7.0.6",
-    "unified": "^11.0.5"
+    "astro": "^7.3.5",
+    "remark-mdx": "^3.1.1",
+    "vfile": "^6.0.3"
   }
 }

package/src/components/DocsSidebar.astro

@@ -5,13 +5,13 @@
  * Navigation sidebar for documentation pages with hierarchical menu structure.
  */
 
-import { getData, type SidebarItem, type SidebarSubItem } from '@libs/data'
-import { getConfig } from '@libs/config'
-import { docsPages } from '@libs/content'
+import type { SidebarItem, SidebarSubItem } from '../libs/schema'
 import { getSlug } from '../libs/utils'
+import { getDocsPages, getDocsPath, getSidebar } from '../site'
 import Icon from './shortcodes/Icon.astro'
 
-const sidebar = getData('sidebar')
+const sidebar = getSidebar()
+const docsPages = await getDocsPages()
 ---
 
 <nav class="cxd-links w-100" id="cxd-docs-nav" aria-label="Docs navigation">
@@ -32,7 +32,7 @@ const sidebar = getData('sidebar')
                 {group.icon && (
                   <Icon
                     name={group.icon}
-                    style={group.icon_color && `color: var(--cx-${group.icon_color});`}
+                    style={group.iconColor && `color: var(--cx-${group.iconColor});`}
                   />
                 )}
                 {group.title}
@@ -48,7 +48,7 @@ const sidebar = getData('sidebar')
                           const docSlug = getSlug(page.title)
                           const unversionedPageSlug = `${groupSlug}/${docSlug}`
 
-                          const url = `${getConfig().docsPath}/${unversionedPageSlug}`
+                          const url = getDocsPath(unversionedPageSlug)
                           const active = Astro.params.slug === unversionedPageSlug
 
                           const generatedPage = docsPages.find(
@@ -58,7 +58,7 @@ const sidebar = getData('sidebar')
                           // This test should not be necessary, see comments for `getSlug()` in `src/libs/utils.ts`.
                           if (!generatedPage) {
                             throw new Error(
-                              `The page '${page.title}' referenced in 'site/data/sidebar.yml' does not exist at '${url}'.`
+                              `The page '${page.title}' referenced in 'data/sidebar.yml' does not exist at '${url}'.`
                             )
                           }
 
@@ -86,7 +86,7 @@ const sidebar = getData('sidebar')
                   const docSlug = getSlug(item.title)
                   const unversionedPageSlug = `${groupSlug}/${docSlug}`
 
-                  const url = `${getConfig().docsPath}/${unversionedPageSlug}`
+                  const url = getDocsPath(unversionedPageSlug)
                   const active = Astro.params.slug === unversionedPageSlug
 
                   const generatedPage = docsPages.find((page) => page.id === unversionedPageSlug)
@@ -120,7 +120,7 @@ const sidebar = getData('sidebar')
             <>
               <li class="cxd-links-span-all mt-2xs mb-md mx-lg border-top" />
               <a
-                href={`${getConfig().docsPath}/${groupSlug}/`}
+                href={getDocsPath(`${groupSlug}/`)}
                 class:list={['cxd-links-link cxd-links-span-all', { active }]}
                 aria-current={active ? 'page' : undefined}
               >

package/src/components/ThemeToggler.astro

@@ -26,9 +26,8 @@ const { layout } = Astro.props
   data-cx-placement="bottom-end"
 >
   <Icon name="circle-half-solid" class="theme-icon-active" />
-  <span
-    class=`${layout === 'examples' ? 'visually-hidden' : 'lg:d-none ms-xs'}`
-    id="cxd-theme-text">Toggle theme</span
+  <span class=`${layout === 'examples' ? 'visually-hidden' : 'lg:d-none ms-xs'}` id="cxd-theme-text"
+    >Toggle theme</span
   >
 </button>
 <ul class="menu" role="menu" aria-label="Theme options">

package/src/components/shortcodes/CSSOnly.astro

@@ -15,8 +15,6 @@ const { tooltip = 'This feature is only available in CSS and not in Figma compon
   Astro.props
 ---
 
-<span
-  class="badge lg info smooth mb-md rounded-md"
-  data-cx-toggle="tooltip"
-  title={tooltip}>CSS Only</span
+<span class="badge lg info smooth mb-md rounded-md" data-cx-toggle="tooltip" title={tooltip}
+  >CSS Only</span
 >

package/src/components/shortcodes/Callout.astro

@@ -5,16 +5,16 @@
  * Display informational callout boxes with different types (info, danger, warning).
  */
 
-import { getCalloutByName, type CalloutName } from '@libs/content'
 import { render } from 'astro:content'
+import { getCallout } from '../../site'
 import type { MarkdownInstance } from 'astro'
 
 interface Props {
   /**
-   * The name of an existing callout to display located in `src/content/callouts`.
+   * The name of an entry of the site's `callouts` collection to display.
    * This will override any content passed in via the default slot.
    */
-  name?: CalloutName
+  name?: string
   /**
    * The type of callout to display. One of `info`, `danger`, or `warning`.
    * @default 'info'
@@ -31,7 +31,7 @@ const { name, type = 'info', class: className } = Astro.props
 let Content: MarkdownInstance<{}>['Content'] | undefined
 
 if (name) {
-  const callout = await getCalloutByName(name)
+  const callout = await getCallout(name)
 
   if (!callout) {
     throw new Error(`Could not find callout with name '${name}'.`)

package/src/components/shortcodes/Code.astro

@@ -1,9 +1,8 @@
 ---
 import fs from 'node:fs'
-import path from 'node:path'
 import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers'
-import { getConfig } from '@libs/config'
 import { highlightCode } from '../../libs/highlight'
+import { getSourceFsPath, getSourceUrl } from '../../site'
 import Icon from './Icon.astro'
 
 interface Props {
@@ -41,7 +40,8 @@ interface Props {
    */
   fileMatch?: string
   /**
-   * A path to the file containing the code to highlight relative to the root of the repository.
+   * A path to the file containing the code to highlight, relative to the `sourceDir` of the
+   * site's `config.yml` (the site's root when it is not set).
    * This takes precedence over the `code` prop.
    */
   filePath?: string
@@ -87,9 +87,7 @@ const {
   hasPreview = false
 } = Astro.props
 
-const fileUrl = file
-  ? `${getConfig().repo}/blob/v${getConfig().current_version}/${file}`.replaceAll('\\', '/')
-  : null
+const fileUrl = file ? getSourceUrl(file) : null
 
 // Extract language from multiple possible sources (for markdown code blocks)
 // Priority: lang prop > data-language attribute > className pattern
@@ -121,7 +119,7 @@ const displayLang = detectedLang
   : ''
 
 let codeToDisplay = filePath
-  ? fs.readFileSync(path.join(process.cwd(), filePath), 'utf8')
+  ? fs.readFileSync(getSourceFsPath(filePath), 'utf8')
   : Array.isArray(code)
     ? code.join('\n')
     : code
@@ -149,7 +147,7 @@ if (codeToDisplay && detectedLang) {
 
 <script>
   import { Tooltip } from '@chassis-ui/css'
-  import { initCopyButtons } from '@libs/clipboard'
+  import { initCopyButtons } from '../../js/clipboard'
 
   document.querySelectorAll('.button-edit').forEach((button) => {
     Tooltip.getOrCreateInstance(button, { title: 'Edit on StackBlitz' })

package/src/components/shortcodes/InFigma.astro

@@ -19,8 +19,6 @@ const tooltipText =
   `This variant${plural ? 's' : ''} exist${plural ? '' : 's'} in the Figma component library with bound design tokens.`
 ---
 
-<span
-  class="badge lg primary smooth mb-md rounded-md"
-  data-cx-toggle="tooltip"
-  title={tooltipText}>In Figma</span
+<span class="badge lg primary smooth mb-md rounded-md" data-cx-toggle="tooltip" title={tooltipText}
+  >In Figma</span
 >

package/src/components/shortcodes/JsDocs.astro

@@ -1,5 +1,7 @@
 ---
 import fs from 'node:fs'
+import { getSourceFsPath } from '../../site'
+import { extractDocsSnippet } from '../../libs/snippet'
 import Code from './Code.astro'
 
 // Prints everything between `// js-docs-start "name"` and `// js-docs-end "name"`
@@ -11,7 +13,8 @@ interface Props {
    */
   name: string
   /**
-   * File path that contains the content to display relative to the root of the repository.
+   * File path that contains the content to display, relative to the `sourceDir` of the site's
+   * `config.yml` (the site's root when it is not set).
    */
   file: string
 }
@@ -27,19 +30,17 @@ if (!name || !file) {
 let content: string
 
 try {
-  const fileContent = fs.readFileSync(file, 'utf8')
+  const fileContent = fs.readFileSync(getSourceFsPath(file), 'utf8')
 
-  const matches = fileContent.match(
-    new RegExp(`// js-docs-start ${name}\n((?:.|\n)*)// js-docs-end ${name}`, 'm')
-  )
+  const snippet = extractDocsSnippet(fileContent, 'js', name)
 
-  if (!matches || !matches[1]) {
+  if (!snippet) {
     throw new Error(
       `Failed to find the content named '${name}', make sure that '// js-docs-start ${name}' and '// js-docs-end ${name}' are defined.`
     )
   }
 
-  content = matches[1]
+  content = snippet
 
   // Fix the identation by removing extra spaces at the beginning of each line
   const lines = content.split('\n')

package/src/components/shortcodes/ScssDocs.astro

@@ -1,7 +1,8 @@
 ---
 import fs from 'node:fs'
-import path from 'node:path'
 import * as sass from 'sass'
+import { getNodeModulesPaths, getSourceFsPath } from '../../site'
+import { extractDocsSnippet } from '../../libs/snippet'
 import Code from './Code.astro'
 
 // Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"`
@@ -14,7 +15,8 @@ interface Props {
    */
   name: string
   /**
-   * File path that contains the content to display relative to the root of the repository.
+   * File path that contains the content to display, relative to the `sourceDir` of the site's
+   * `config.yml` (the site's root when it is not set).
    */
   file: string
   /**
@@ -74,23 +76,21 @@ let content: string
 let lang: string = 'scss'
 
 try {
-  const fileContent = fs.readFileSync(file, 'utf8')
+  const fileContent = fs.readFileSync(getSourceFsPath(file), 'utf8')
 
-  const matches = fileContent.match(
-    new RegExp(`// scss-docs-start ${name}\n((?:.|\n)*)// scss-docs-end ${name}`, 'm')
-  )
+  const snippet = extractDocsSnippet(fileContent, 'scss', name)
 
-  if (!matches || !matches[1]) {
+  if (!snippet) {
     throw new Error(
       `Failed to find the content named '${name}', make sure that '// scss-docs-start ${name}' and '// scss-docs-end ${name}' are defined.`
     )
   }
 
-  const rawContent = matches[1]
+  const rawContent = snippet
 
   if (compile) {
     // Derive the SCSS load path from the file argument (e.g. "scss/_foo.scss" → "scss/")
-    const scssLoadPath = path.resolve(process.cwd(), file.split('/')[0])
+    const scssLoadPath = getSourceFsPath(file.split('/')[0])
 
     const scssInput = [
       '@use "config" as *;',
@@ -107,11 +107,11 @@ try {
     const result = await sass.compileStringAsync(scssInput, {
       loadPaths: [
         scssLoadPath,
-        path.resolve(process.cwd(), 'scss/vendor'),
+        getSourceFsPath('scss/vendor'),
         // Vite's own Sass importer resolves bare npm specifiers (e.g. `@chassis-ui/tokens/...`)
         // through its module resolver, independent of `loadPaths`. This raw Sass JS API call
         // bypasses Vite, so `node_modules` must be added here explicitly.
-        path.resolve(process.cwd(), 'node_modules')
+        ...getNodeModulesPaths()
       ],
       // Match the same deprecation silencing used in astro.config.ts / vite scss options
       silenceDeprecations: ['import', 'global-builtin', 'color-functions', 'if-function'] as any