NXT-15365: Replaced Gatsby with Astro Docs

.github/workflows/ci-reusable.yml

@@ -46,7 +46,10 @@ jobs:
         run: npm run lint -- --report-unused-disable-directives --max-warnings 0 .
 
       - name: Parsing docs
-        run: npm run parse
+        run: npm run parse-docs
+
+      - name: Parsing pages
+        run: npm run parse-pages
 
       - name: Building sample runner
         run: npm run make-runner

.gitignore

@@ -1,11 +1,32 @@
-node_modules/
-src/pages/docs/modules
-src/pages/docs/developer-guide
-src/pages/docs/developer-tools
+# build output
+dist/
+# generated types
+.astro/
+.idea/
+.vscode/
+
+#documentation related
+data/
+raw/
+src/content/docs/developer-guide
+src/content/docs/developer-tools
+src/content/docs/modules
+src/data
+src/pages/
 static/
-public/
-.gatsby-context.js
-.cache/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
 .DS_Store
-src/data/
-raw/

CHANGELOG.md

@@ -4,6 +4,7 @@ The following is a curated list of changes in the Enact docs-utils module, newes
 
 ## [unreleased]
 
+- Migrated from `Gatsby` to `Astro/Starlight`.
 - Changed to require node `^20.19.0` or later.
 - Updated dependencies versions to the latest.
 - Updated docs and `sample-runner` to support react19.

README.md

@@ -1,26 +1,36 @@
 # Enact Documentation
 
-This package generates the docs for Enact and its libraries.  Docs are generated from static doc
+This package generates the docs for Enact and its libraries. Docs are generated from static doc
 files and in-line documentation in JSDoc-style format.
 
 ## Building
 
-> Note: Requires Node 18.12.0+
-
-Before serving or building documentation, you must first run the `parse` command to generate the
+Before serving or building documentation, you must first run the `parse-docs` command to generate the
 documentation from the Enact source:
 
 ```
-npm run parse
+npm run parse-docs
+```
+
+The `parse-pages` command will convert documentation to `.mdx` and will use `.astro` components.
+
+```
+npm run parse-pages
+```
+
+The `make-runner` command will generate source for the components live preview.
+
+```
+npm run make-runner
 ```
 
 Additional repos can be pulled into the docs using the `extra-repos` command line argument:
 
 ```
-e.g. npm run parse -- --extra-repos enactjs/agate#develop,enactjs/moonstone#3.2.5
+e.g. npm run parse-docs -- --extra-repos enactjs/agate#develop,enactjs/moonstone#3.2.5
 ```
 
-Then, the docs site can be built in a 'debug' server mode or as a standalone static site.  For testing,
+Then, the docs site can be built in a 'debug' server mode or as a standalone static site. For testing,
 use the `serve` command:
 
 ```
@@ -37,14 +47,11 @@ npm run build
 
 Copies of the source of Enact and other related libraries are placed into the `raw/` directory. If you need to link local copies, link them into that directory.  E.g.:
 
-```bash
-ln -s ~/enact raw/enact
-ln -s ~/cli raw/cli
-ln -s ~/eslint-config-enact raw/eslint-config-enact
-```
-
-For linking built Enact runtime libraries, use the `enact link` command.
+## Check Broken Links
 
-## Known Issue
+To check the broken links, follow the steps below:
 
-* Gatsby produces a site that is tied specifically to a particular path.  It expects to be installed into the root.  If you want to serve from elsewhere, you must change the `linkPrefix` in `/config.toml` and use `npm run deploy`.
+1. `npm run parse-docs`
+2. `npm run parse-pages`
+3. `npm run build`
+4. `npm run check-links`

astro.config.mjs

@@ -0,0 +1,67 @@
+// @ts-check
+import react from '@astrojs/react';
+import starlight from '@astrojs/starlight';
+import {defineConfig} from 'astro/config';
+import path from 'path';
+
+// https://astro.build/config
+export default defineConfig({
+	base: '/',
+	vite: {
+		resolve: {
+			alias: {
+				'@livePreview': path.resolve('./src/components/LivePreview/LivePreview.jsx'),
+				'@moduleData': path.resolve('./src/pages/docs/modules'),
+				'@modulePage': path.resolve('./src/components/Page/[...data].astro'),
+				'@utils': path.resolve('./src/utils/utils.jsx')
+			}
+		}
+	},
+	integrations: [starlight({
+		tableOfContents: false,
+		components: {
+			Footer: './src/components/Footer/Footer.astro',
+			Header: './src/components/Header/Header.astro',
+			Hero: './src/components/Hero/Hero.astro',
+			PageTitle: './src/components/PageTitle/PageTitle.astro',
+			Sidebar: './src/components/Sidebar/Sidebar.astro',
+			TwoColumnContent: './src/components/TwoColumnContent/TwoColumnContent.astro'
+		},
+		title: 'Enact',
+		logo: {
+			src: './src/assets/enact.svg'
+		},
+		social: [{icon: 'github', label: 'GitHub', href: 'https://github.com/enactjs/enact'}],
+		sidebar: [
+			{
+				label: 'API Libraries',
+				items: [{autogenerate: {directory: 'modules', collapsed: true}}]
+			},
+			{
+				label: 'Developer Guide',
+				items: [{autogenerate: {directory: 'developer-guide', collapsed: true}}]
+			},
+			{
+				label: 'Developer Tools',
+				items: [{autogenerate: {directory: 'developer-tools', collapsed: true}}]
+			},
+			{
+				label: 'Tutorials',
+				items: [{autogenerate: {directory: 'tutorials/intro', collapsed: true}}]
+			},
+			{
+				label: 'Hello Enact!',
+				items: [{autogenerate: {directory: 'tutorials/tutorial-hello-enact', collapsed: true}}]
+			},
+			{
+				label: 'Kitten Browser',
+				items: [{autogenerate: {directory: 'tutorials/tutorial-kitten-browser', collapsed: true}}]
+			},
+			{
+				label: 'TypeScript with Enact',
+				items: [{autogenerate: {directory: 'tutorials/tutorial-typescript', collapsed: true}}]
+			}
+		]
+	}),
+	react()]
+});

eslint.config.mjs

@@ -0,0 +1,17 @@
+import enactConfig from 'eslint-config-enact/strict.js';
+
+export default [
+	...enactConfig,
+	{
+		ignores: [
+			'.astro/*',
+			'.idea/*',
+			'dist/*',
+			'node_modules/*',
+			'public/*',
+			'raw/*',
+			'src/data',
+			'static/*'
+		]
+	}
+];