refactor: migrate documentation to Starlight

.github/pull_request_template.md

@@ -16,8 +16,8 @@
   - Add section with overloads, if have
   - Add `Motivation`, `Formulae`, `Arguments` and `Return` sections for each overload
   - Add useful examples in `Example` section for each overload
-- [ ] Add section to `README.md` in the repository root
-  - Add method to the table of contents into correct category `- [MethodName](#methodname) - description.`
-  - Add section `## MethodName`
-  - Add `[Method documentation & API](/src/method-name)` into section
-  - Add simple example
+- [ ] Fill frontmatter in `src/method-name/readme.md`
+  - Add `title`. Make sure it uses camelCase syntax just like the method itself
+  - Add `slug`. Use param-case to write it. In most cases it will be just like `title`
+  - Add `desription` with one short sentence describing what method useful for
+  - Add `group`. To categorize method on `/operators` page. Full list of available groups, you can see in [documentation/src/content/config.ts](../documentation/src/content/config.ts)

.github/workflows/docs.yml

@@ -12,15 +12,15 @@ jobs:
 
     steps:
       - name: 🛎️ Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: 📦 Setup pnpm
-        uses: pnpm/action-setup@v2
+        uses: pnpm/action-setup@v4
 
-      - name: 🐧 Use Node.js v18.x
+      - name: 🐧 Use Node.js v20.x
         uses: actions/setup-node@v4
         with:
-          node-version: v18.x
+          node-version: v20.x
           cache: 'pnpm'
           cache-dependency-path: pnpm-lock.yaml
 
@@ -29,11 +29,11 @@ jobs:
         working-directory: ./
 
       - name: 🔧 Build
-        run: pnpm build
-        working-directory: ./website
+        run: pnpm doc build
+        working-directory: ./
 
       - name: 🚀 Deploy
         uses: JamesIves/[email protected]
         with:
           branch: gh-pages
-          folder: ./website/build
+          folder: ./documentation/dist

README.md

@@ -16,7 +16,7 @@
 [codesandbox]: https://codesandbox.io/s/effector-patronum-playground-zuqjx
 [try-patronum-share]: https://share.effector.dev/Neewtbz3
 [jsdelivr]: https://www.jsdelivr.com/package/npm/patronum
-[unpkg]: https://unpkg.com/browse/patronum@1.7.0/
+[unpkg]: https://unpkg.com/browse/patronum@2/
 [npm]: https://www.npmjs.com/package/patronum
 [github]: https://github.com/effector/patronum
 [twitter-share]: https://twitter.com/intent/tweet?text=I%20used%20patronum!%0AGoing%20to%20Mars%20with%20%40effectorjs%20-%20data-flow%20powered%20tool%20to%20implement%20business%20logic.%0A%0Ahttps%3A%2F%2Fgithub.com%2Feffector%2Fpatronum%0A
@@ -44,13 +44,13 @@ const userLoadFx = createEffect();
 const $status = status({ effect: userLoadFx });
 ```
 
-You can read more at [documentation](https://patronum.effector.dev/docs/installation).
+You can read more at [documentation](https://patronum.effector.dev/guides/installation/).
 
 ## Migration guide
 
 Patronum had 3 breaking changes: 1) from `0.14` to `0.100`, 2) from `0.100` to `0.110`, 3) from `0.110` to `1.0`
 
-We have [migration guide](https://patronum.effector.dev/docs/migration-guide).
+We have [migration guide](https://patronum.effector.dev/guides/migration).
 
 # Development
 

documentation/.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

documentation/.prettierrc.mjs

@@ -0,0 +1,12 @@
+/** @type {import("prettier").Config} */
+export default {
+  plugins: ['prettier-plugin-astro'],
+  overrides: [
+    {
+      files: '*.astro',
+      options: {
+        parser: 'astro',
+      },
+    },
+  ],
+};

documentation/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

documentation/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

documentation/README.md

@@ -0,0 +1,55 @@
+# 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/
+│   │   └── config.ts
+│   └── env.d.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).

documentation/astro.config.mjs

@@ -0,0 +1,50 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+// https://astro.build/config
+export default defineConfig({
+  site: 'https://patronum.effector.dev',
+  integrations: [
+    starlight({
+      title: 'effector patronum ✨',
+      description: 'Operators library delivering modularity and convenience.',
+      logo: {
+        src: './src/assets/comet.png',
+      },
+      editLink: {
+        baseUrl: 'https://github.com/effector/patronum/edit/main/documentation',
+      },
+      social: {
+        github: 'https://github.com/effector/patronum',
+        telegram: 'https://t.me/effector_en',
+        'x.com': 'https://x.com/effectorjs',
+        reddit: 'https://www.reddit.com/r/effectorjs/',
+        discord: 'https://discord.gg/yHcMcuRWeC',
+        youtube: 'https://youtube.com/@effectorjs',
+      },
+      defaultLocale: 'en',
+      locales: {
+        root: { label: 'English', lang: 'en' },
+        // 'ru-RU': { label: 'Russian' },
+      },
+      sidebar: [
+        {
+          label: 'Guides',
+          autogenerate: { directory: 'guides' },
+        },
+        {
+          label: 'Reference',
+          items: [
+            {
+              label: 'Operators',
+              link: '/operators',
+            },
+          ],
+        },
+      ],
+    }),
+  ],
+  experimental: {
+    contentLayer: true,
+  },
+});

documentation/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "documentation",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "sync": "astro sync",
+    "preview": "astro preview",
+    "build": "astro check && astro build",
+    "astro": "astro",
+    "format": "prettier --write ."
+  },
+  "dependencies": {
+    "@astrojs/check": "^0.9.3",
+    "@astrojs/starlight": "^0.26.1",
+    "astro": "^4.15.1",
+    "sharp": "^0.32.5",
+    "starlight-package-managers": "^0.6.0",
+    "typescript": "^5.5.4"
+  },
+  "devDependencies": {
+    "prettier": "^3.3.3",
+    "prettier-plugin-astro": "^0.14.1"
+  }
+}

documentation/public/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://effector.patronum.dev/sitemap-index.xml

documentation/src/content/config.ts

@@ -0,0 +1,27 @@
+import { defineCollection, z } from 'astro:content';
+import { docsSchema } from '@astrojs/starlight/schema';
+import { glob } from 'astro/loaders';
+
+const operators = defineCollection({
+  type: 'content_layer',
+  loader: glob({ pattern: '*/*.md', base: '../src' }),
+  schema: z.object({
+    title: z.string(),
+    description: z.string().optional(),
+    slug: z.string(),
+    group: z.enum(['predicate', 'effect', 'timeouts', 'combination', 'debug']),
+    badge: z
+      .object({
+        variant: z
+          .enum(['note', 'danger', 'success', 'caution', 'tip', 'default'])
+          .default('default'),
+        text: z.string(),
+      })
+      .optional(),
+  }),
+});
+
+export const collections = {
+  docs: defineCollection({ schema: docsSchema() }),
+  operators,
+};

documentation/src/content/docs/guides/installation.mdx

@@ -0,0 +1,65 @@
+---
+title: Installation
+description: A guide how to use effector with patronum.
+---
+
+import { PackageManagers } from 'starlight-package-managers';
+
+<PackageManagers pkg="patronum" frame="none" />
+
+## Usage
+
+Just import method from the root module:
+
+```js
+import { throttle, splitMap } from 'patronum';
+```
+
+Or from the personal module:
+
+```js
+import { throttle } from 'patronum/throttle';
+import { splitMap } from 'patronum/split-map';
+```
+
+> Except `patronum/debug`. It is only available by personal module import.
+
+Be careful in the module naming:
+
+- Method export always exports as named export in camelCase
+- Module with the operator always named in param-case
+
+## Helpful reading
+
+[Prefer Operators over Methods](https://withease.effector.dev/magazine/no_methods.html)
+
+## Tests and SSR support
+
+For SSR it is very useful to automatically identify each store, so it is recommended to read article about [Stable Identifiers in Effector](https://effector.dev/en/explanation/sids/).
+
+Tests can be written without SWC or Babel-plugins, but it is recommended to use them to simplify debug and development.
+
+### SWC
+
+Install [`@effector/swc-plugin`](https://effector.dev/en/api/effector/swc-plugin/) to your project then add it to `.swcrc`:
+
+```json
+{
+  "$schema": "https://json.schemastore.org/swcrc",
+  "jsc": {
+    "experimental": {
+      "plugins": [["@effector/swc-plugin", {}]]
+    }
+  }
+}
+```
+
+### Babel
+
+Just add `effector/babel-plugin` to your `.babelrc` or `babel.config.js` at the `"plugins"` section:
+
+```json
+{
+  "plugins": ["effector/babel-plugin"]
+}
+```

website/src/pages/docs/migration-guide.md → documentation/src/content/docs/guides/migration.mdx

@@ -1,4 +1,12 @@
-# Migration guide
+---
+title: Migration guide
+description: Guides how to migrate from previous versions.
+---
+
+### v2.0.0
+
+Minimal supported version of effector is `v23.0.0`.
+No breaking changes.
 
 ### v1.0.0