Merge pull request #10843 from marmelab/headless-doc

[Doc] Bootstrap headless documentation

Author: Madeorsk

.github/workflows/deploy-doc-headless.yml

@@ -0,0 +1,55 @@
+name: 📕 Deploy headless docs
+on:
+    push:
+        branches:
+            - master
+            - next # TODO remove
+    pull_request: # TODO remove
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+    cancel-in-progress: true
+
+permissions:
+    pages: write
+    contents: write
+
+jobs:
+    deploy:
+        name: 📕 Deploy headless docs
+        runs-on: ubuntu-latest
+
+        env:
+            PRODUCTION_REMOTE: https://git:${{ secrets.DEPLOY_TOKEN }}@github.com/${{ vars.DEPLOY_REPOSITORY }}
+
+        steps:
+            - name: 📥 Checkout repo
+              uses: actions/checkout@v4
+
+            - name: ⚙️ Setup node
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 20
+                  cache: yarn
+
+            - name: ⚙️ Setup git
+              run: |
+                  echo Deploying to pages to $PRODUCTION_REMOTE
+                  git remote set-url origin https://git:${{ secrets.GITHUB_TOKEN }}@github.com/${GITHUB_REPOSITORY}
+                  git remote add production $PRODUCTION_REMOTE
+                  git config --global user.email [email protected]
+                  git config --global user.name github-actions-bot
+
+            - name: 📥 Download deps
+              run: yarn install --frozen-lockfile
+
+            - name: 🔨 Build
+              run: |
+                  cd docs_headless
+                  yarn build
+                  cd ..
+
+            - name: 📡 Deploy GitHub pages
+              run: yarn gh-pages --remote production -d docs_headless/dist -b ${{ vars.DEPLOY_BRANCH || 'gh-pages' }}
+              env:
+                  GITHUB_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

.prettierignore

@@ -23,4 +23,5 @@ cypress/screenshots
 !.yarn/plugins
 !.yarn/releases
 !.yarn/sdks
-!.yarn/versions
+!.yarn/versions
+.astro

Makefile

@@ -117,6 +117,9 @@ build: build-ra-core build-ra-data-fakerest build-ra-ui-materialui build-ra-data
 doc: ## compile doc as html and launch doc web server
 	@yarn doc
 
+doc-headless: ## launch headless doc web server
+	@cd docs_headless && yarn dev
+
 docker-doc: ## run the doc website in a docker container
 	@docker run -it --rm \
 		-p 4000:4000 \

docs_headless/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# 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

docs_headless/README.md

@@ -0,0 +1,54 @@
+# Starlight Starter Kit: Basics
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+```
+npm create astro@latest -- --template starlight
+```
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)
+[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics)
+[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/withastro/starlight&create_from_path=examples/basics)
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fbasics&project-name=my-starlight-docs&repository-name=my-starlight-docs)
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Astro + Starlight project, you'll see the following folders and files:
+
+```
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── content/
+│   │   └── docs/
+│   └── content.config.ts
+├── astro.config.mjs
+├── package.json
+└── tsconfig.json
+```
+
+Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+
+Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+
+Static assets, like favicons, can be placed in the `public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `npm install`             | Installs dependencies                            |
+| `npm run dev`             | Starts local dev server at `localhost:4321`      |
+| `npm run build`           | Build your production site to `./dist/`          |
+| `npm run preview`         | Preview your build locally, before deploying     |
+| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `npm run astro -- --help` | Get help using the Astro CLI                     |
+
+## 👀 Want to learn more?
+
+Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).

docs_headless/astro.config.mjs

@@ -0,0 +1,91 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import react from '@astrojs/react';
+import mdx from '@astrojs/mdx';
+import tailwindcss from '@tailwindcss/vite';
+import rehypeCodeGroup from 'rehype-code-group';
+import expressiveCode from 'astro-expressive-code';
+import { pluginFullscreen } from 'expressive-code-fullscreen';
+import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections';
+import rehypeAstroRelativeMarkdownLinks from 'astro-rehype-relative-markdown-links';
+
+// https://astro.build/config
+export default defineConfig({
+    integrations: [
+        starlight({
+            title: 'React Admin Headless',
+            customCss: ['./src/styles/global.css'],
+            favicon: '/favicon.ico',
+            social: [
+                {
+                    icon: 'github',
+                    label: 'GitHub',
+                    href: 'https://github.com/marmelab/react-admin',
+                },
+            ],
+            sidebar: [
+                {
+                    label: 'Guides & Concepts',
+                    items: [
+                        // Each item here is one entry in the navigation menu.
+                        {
+                            label: 'General Concepts',
+                            slug: 'guides/architecture',
+                        },
+                        {
+                            label: 'Data Fetching',
+                            slug: 'guides/datafetchingguide',
+                        },
+                        {
+                            label: 'CRUD pages',
+                            slug: 'guides/crud',
+                            attrs: {
+                                class: 'flex items-center',
+                            },
+                            badge: {
+                                text: '',
+                                variant: 'default',
+                                class: 'ee-badge',
+                            },
+                        },
+                    ],
+                },
+                {
+                    label: 'Reference',
+                    autogenerate: {
+                        directory: 'reference',
+                    },
+                },
+            ],
+            components: {
+                Sidebar: './src/components/CustomSidebar.astro',
+            },
+        }),
+        expressiveCode({
+            plugins: [pluginFullscreen(), pluginCollapsibleSections()],
+        }),
+        react(),
+        mdx(),
+    ],
+    markdown: {
+        rehypePlugins: [
+            rehypeCodeGroup,
+            [
+                rehypeAstroRelativeMarkdownLinks,
+                {
+                    base: '/ra-core/',
+                    collectionBase: false,
+                },
+            ],
+        ],
+    },
+    vite: {
+        plugins: [tailwindcss()],
+    },
+    base: '/ra-core/',
+    site: 'https://marmelab.com',
+    build: {
+        assets: 'assets',
+    },
+});

docs_headless/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "ra-core-doc",
+    "type": "module",
+    "version": "0.0.1",
+    "scripts": {
+        "dev": "astro dev",
+        "start": "astro dev",
+        "build": "astro build",
+        "preview": "astro preview",
+        "astro": "astro"
+    },
+    "dependencies": {
+        "@astrojs/mdx": "^4.3.1",
+        "@astrojs/react": "^4.3.0",
+        "@astrojs/starlight": "0.35.2",
+        "@astrojs/starlight-tailwind": "^4.0.1",
+        "@expressive-code/plugin-collapsible-sections": "^0.41.3",
+        "@tailwindcss/vite": "^4.1.11",
+        "@types/react": "^19.1.8",
+        "@types/react-dom": "^19.1.6",
+        "astro": "5.12.6",
+        "astro-expressive-code": "^0.41.3",
+        "astro-rehype-relative-markdown-links": "^0.18.1",
+        "expressive-code-fullscreen": "^1.0.0",
+        "react": "^18.3.1",
+        "react-dom": "^18.3.1",
+        "rehype-code-group": "^0.2.4",
+        "sharp": "^0.34.2",
+        "starlight-package-managers": "^0.11.0",
+        "tailwindcss": "^4.1.11"
+    },
+    "devDependencies": {
+        "prettier": "^3.2.5",
+        "prettier-plugin-astro": "^0.14.1"
+    }
+}