docs: refactor routing docs

vikejs · Oct 31, 2024 · 440d095 · 440d095
1 parent 5553d0f
commit 440d095
Show file tree

Hide file tree

Showing 15 changed files with 97 additions and 139 deletions.
diff --git a/docs/components/RouteDomainDriven.mdx b/docs/components/RouteDomainDriven.mdx
diff --git a/docs/headings.ts b/docs/headings.ts
@@ -89,7 +89,8 @@ const headings = [
   {
     level: 2,
     title: 'Routing',
-    url: '/routing'
+    url: '/routing',
+    sectionTitles: ['Filesystem Routing']
   },
   {
     level: 2,
@@ -126,11 +127,6 @@ const headings = [
     title: 'Internationalization (i18n)',
     url: '/i18n'
   },
-  {
-    level: 2,
-    title: 'File Structure',
-    url: '/file-structure'
-  },
   {
     level: 2,
     title: 'Paths Aliases',

diff --git a/docs/headingsDetached.ts b/docs/headingsDetached.ts
@@ -3,6 +3,10 @@ export { headingsDetached }
 import type { HeadingDetachedDefinition } from '@brillout/docpress'
 
 const headingsDetached: HeadingDetachedDefinition[] = [
+  {
+    title: 'File Structure',
+    url: '/file-structure'
+  },
   {
     title: 'Redux',
     url: '/redux'

diff --git a/docs/pages/config/+Page.mdx b/docs/pages/config/+Page.mdx
@@ -119,7 +119,7 @@ export default {
 
 ### Domain-driven File Structure
 
-You can use a <Link href="/file-structure#domain-driven">domain-driven file structure</Link> for better organization and for improved configuration inheritance.
+You can use a <Link href="/routing#domain-driven-file-structure">domain-driven file structure</Link> for better organization and for improved configuration inheritance.
 
 
 ## Pointer imports
@@ -273,4 +273,4 @@ console.log(ssr) // Prints: import:./ssr:default
 ## See also
 
 - <Link href="/filesystem-routing" />
-- <Link href="/file-structure#domain-driven" />
+- <Link href="/routing#domain-driven-file-structure" />
diff --git a/docs/pages/file-structure/+Page.mdx b/docs/pages/file-structure/+Page.mdx
@@ -1,21 +1,20 @@
 import { Link } from '@brillout/docpress'
-import { UiFrameworkExtension } from '../../components'
 
-For advanced apps we recommend a domain-driven file structure using multiple `pages/` directories.
+For simple apps, you can define a basic file structure with a single `pages/` directory.
 
-For basic apps we recommend using a single `pages/` directory.
+For advanced apps, you may want to define several `pages/` directories for what we call a *domain-driven file structure*.
 
 
 ## Basic
 
 ```yaml
 # Landing page
 /pages/index/+Page.js
-/pages/index/SomeComponentForLandingPage.js
+/pages/index/components/SomeComponentForLandingPage.js
 /pages/index/**/* # More files specific to the landing page
 # About page
 /pages/about/+Page.js
-/pages/about/SomeComponentForAboutPage.js
+/pages/about/components/SomeComponentForAboutPage.js
 /pages/about/**/* # More files specific to the about page
 # Other pages
 /pages/**/+Page.js
@@ -33,8 +32,6 @@ For basic apps we recommend using a single `pages/` directory.
 
 ## Domain-driven
 
-You can have what we call a *domain-driven file structure*.
-
 ```yaml
 # ===========================
 # ======= Marketing =========
@@ -75,8 +72,12 @@ products/pages/+ssr.js
 products/database/fetchProduct.js
 products/database/fetchProductList.js
 
-# Shared across all domains
+# =============================
+# ======= Shared/Misc =========
+# =============================
+# Components shared across all domains
 components/
+# Server code
 server/
 ```
 
@@ -86,51 +87,8 @@ server/
 export default '/product/@id'
 ```
 
-> The directory `(marketing)/` is used for <Link href="/routing#groups">grouping</Link> and is ignored by <Link href="/filesystem-routing">Filesystem Routing</Link>.
->
-> Alternatively, you can have `marketing/` (without parentheses) and <Link href="/filesystemRoutingRoot">set `marketing/+filesystemRoutingRoot.js`</Link> to change the Filesystem Routing URL from `/marketing` to `/`.
-
-> See <Link href="/config#inheritance" />.
-
-Example: <Link href='/examples/file-structure-domain-driven/' />.
-
-
-## `src/pages/`
-
-You can embed `pages/` in `src/`:
-
-```yaml
-/src/pages/index/+Page.js # => URL /
-/src/pages/about/+Page.js # => URL /about
-```
-
-
-## `renderer/`
-
-If you don't use a <UiFrameworkExtension /> then we recommend placing your UI framework integration in a `renderer/` directory.
-
-```yaml
-# Same as above
-/pages/
-/components/
-/server/
-
-# Code that specifies how pages are rendered
-/renderer/+onRenderHtml.js
-/renderer/+onRenderClient.js
-/renderer/Layout.{jsx,vue}  # React/Vue/... component that wraps the `Page` component
-/renderer/Layout.css
-/renderer/Header.{jsx,vue} # Website header used for every page
-/renderer/Footer.{jsx,vue} # Website footer used for every page
-/renderer/logo.svg # Website logo (favicon and used by <Header>)
-```
-
-The hooks `/renderer/+onRender{Html,Client}.js` apply as default to all pages `/pages/**/+Page.js`.
-
-The `renderer/` directory doesn't add any functionality: defining the hooks `+onRender{Html,Client}.js` at `/renderer/` is equivalent to defining them at `/pages/` or `/`. It's just an optional convenience for moving rendering logic outside of `pages/`: in order to avoid cluttering the `pages/` directory and to organize and put all rendering code in one place.
-
 
 ## See also
- - <Link href="/routing" />
+
+ - <Link href="/routing#filesystem-routing" />
  - <Link href="/filesystem-routing" />
- - <Link href="/config#inheritance" />
diff --git a/docs/pages/filesystem-routing/+Page.mdx b/docs/pages/filesystem-routing/+Page.mdx
@@ -1,39 +1,17 @@
-import { Link } from '@brillout/docpress'
+import { Link, Warning } from '@brillout/docpress'
+import { UiFrameworkExtension } from '../../components'
 
-Vike supports *Filesystem Routing*: the URL of a page is determined by where the page is located on your filesystem.
-
-```bash
-FILESYSTEM                     URL
-====================           ======
-pages/about/+Page.js           /about
-pages/faq/+Page.js             /faq
-```
-
-> Alternatively, you can use a [Route String](/route-string) or a [Route Function](route-function) instead of Filesystem Routing.
-
-> `+` files are explained at <Link href="/config#files" doNotInferSectionTitle />.
-
-
-## Parameterized routes
-
-You can define parameterized routes:
-
-```bash
-FILESYSTEM                     URL
-========================       ===========================
-pages/movie/@id/+Page.js       /movie/123, /movie/abc, ...
-```
-
-> The parameter `id` is available at <Link href="/pageContext">`pageContext.routeParams.id`</Link>.
+Detailed information about Vike's Filesystem Routing.
 
+For an overview, see instead: <Link href="/routing#filesystem-routing" doNotInferSectionTitle />.
 
 ## Ignored directories
 
-Following directories are ignored:
+Following directories are ignored by Filesystem Routing:
  - `index/`
  - `pages/`
  - `src/`
- - `(someDir)/` (any directory wrapped with parentheses)
+ - `(someDir)/` (any directory inside parentheses)
 
 ```
 FILESYSTEM                                                     URL
@@ -45,11 +23,13 @@ contact/+Page.js                                               /contact
 pages/pages/src/(some-dir)/src/index/pages/about/+Page.js      /about
 ```
 
-This enables you to set up a domain-driven file structure: <Link href='/file-structure#domain-driven' />.
+This enables you to set up a <Link href='#domain-driven'>domain-driven file structure</Link>.
 
 Instead of `(someDir)` you can also use the <Link href="/filesystemRoutingRoot">`filesystemRoutingRoot` setting</Link>.
 
 
+
+
 ## Case sensitive
 
 Filesystem Routing is case sensitive:
@@ -61,7 +41,7 @@ pages/HELLO/+Page.js           /HELLO
 ```
 
 
-## Crawl
+## Crawl space
 
 Vike crawls files inside [Vite's `root` directory](https://vitejs.dev/config/shared-options.html#root). Consequently, all your <Link href="/config#files">`+` files</Link> need to live inside `root`.
 
@@ -70,9 +50,39 @@ Vike crawls files inside [Vite's `root` directory](https://vitejs.dev/config/sha
 If you use Git then Vike skips `.gitignore` files.
 
 
+## `renderer/`
+
+If you don't use a <UiFrameworkExtension /> then we recommend placing your UI framework integration in a `renderer/` directory.
+
+```yaml
+# Usual Vike file structure
+/pages/
+/components/
+/server/
+
+# Code that specifies how pages are rendered
+/renderer/+onRenderHtml.js
+/renderer/+onRenderClient.js
+/renderer/Layout.{jsx,vue}  # React/Vue/... component that wraps the `Page` component
+/renderer/Layout.css
+/renderer/Header.{jsx,vue} # Website header used for every page
+/renderer/Footer.{jsx,vue} # Website footer used for every page
+/renderer/logo.svg # Website logo (favicon and used by <Header>)
+```
+
+The hooks `/renderer/+onRender{Html,Client}.js` apply as default to all pages `/pages/**/+Page.js`.
+
+The `renderer/` directory doesn't add any functionality: defining the hooks `+onRender{Html,Client}.js` at `/renderer/` is equivalent to defining them at `/pages/` or `/`. It's just an optional convenience for moving rendering logic outside of `pages/`: in order to avoid cluttering the `pages/` directory and to organize and put all rendering code in one place.
+
+> The `renderer/` directory isn't like the <Link href="#ignored-directories">list of ignored directories</Link> because not only is it ignored by Filesystem Routing but it's also ignored by <Link href="/config#inheritance">config inheritance</Link>.
+
+<Warning>
+We recommend defining a `renderer/` directory only if you are implementing a custom UI framework (React/Vue/Solid/...) integration.
+</Warning>
+
+
 ## See also
 
- - <Link href="/config#files" doNotInferSectionTitle />
- - <Link href="/routing" />
+ - <Link href="/routing#filesystem-routing" />
  - <Link href="/file-structure" />
  - <Link href="/filesystemRoutingRoot" />
diff --git a/docs/pages/filesystemRoutingRoot/+Page.mdx b/docs/pages/filesystemRoutingRoot/+Page.mdx
@@ -1,6 +1,6 @@
 import { Link, Warning } from '@brillout/docpress'
 
-The `filesystemRoutingRoot` setting allows you to change the <Link href="/filesystem-routing">Filesystem Routing</Link> URL. It's usually used for <Link href="/file-structure#domain-driven">domain-driven file structure</Link>.
+The `filesystemRoutingRoot` setting allows you to change the <Link href="/filesystem-routing">Filesystem Routing</Link> URL. It's usually used for <Link href="/routing#domain-driven-file-structure">domain-driven file structure</Link>.
 
 <Warning>Don't use `filesystemRoutingRoot` to change the Base URL, see <Link href="/base-url" /> instead.</Warning>
 
@@ -22,6 +22,6 @@ PROJECT FILES                               URL
 
 ## See also
 
- - <Link href="/file-structure#domain-driven" />
+ - <Link href="/routing#domain-driven-file-structure" />
  - <Link href="/filesystem-routing" />
  - <Link href="/base-url" />
diff --git a/docs/pages/multiple-renderer/+Page.mdx b/docs/pages/multiple-renderer/+Page.mdx
@@ -25,7 +25,7 @@ admin-panel/renderer/+onRenderHtml.js
 admin-panel/renderer/+onRenderClient.js
 ```
 
-> We call such structure a <Link text="domain-driven file structure" href='/file-structure#domain-driven' />.
+> We call such structure a <Link text="domain-driven file structure" href='/routing#domain-driven-file-structure' />.
 
 ## Partial
 

diff --git a/docs/pages/nextjs/+Page.mdx b/docs/pages/nextjs/+Page.mdx
@@ -31,7 +31,7 @@ Finally, Vike is a community project: instead of leaning on a framework with bus
 | RSC (React Server Components)                                   | Yes, <Link href="/react#react-server-components">partially</Link> | Yes, experimental       |
 | <p align="center">**Routing**</p>                                                        |                                                            |                               |
 | Filesystem Routing                                              | Yes                                                        | Yes                           |
-| <Link text="Domain-driven Filesystem Routing" href="/file-structure#domain-driven" />                                        | Yes                                                        | No                            |
+| <Link text="Domain-driven Filesystem Routing" href="/routing#domain-driven-file-structure" />                                        | Yes                                                        | No                            |
 | <Link text="Client Routing" href="/client-routing" />           | Yes                                                        | Yes, but [limited](https://github.com/vercel/next.js/discussions/64660) in SPA-only mode ***                           |
 | <Link text="Server Routing" href="/server-routing" />           | Yes                                                        | No                            |
 | <Link text="Base URL" href="/base-url" />                       | Yes                                                        | Limited                       |

diff --git a/docs/pages/prerender/+Page.mdx b/docs/pages/prerender/+Page.mdx
@@ -48,7 +48,7 @@ export default {
 
 You can define `prerender` in <Link href="/config#inheritance">higher levels so it applies to more/all pages</Link>.
 
-This is especially handy with <Link text="Domain-Driven File Structure" href='/file-structure#domain-driven' />:
+This is especially handy with <Link text="Domain-Driven File Structure" href='/routing#domain-driven-file-structure' />:
 
 ```js
 // /pages/marketing/+prerender.js

diff --git a/docs/pages/route-function/+Page.mdx b/docs/pages/route-function/+Page.mdx
@@ -1,5 +1,4 @@
 import { Link } from '@brillout/docpress'
-import RouteDomainDriven from '../../components/RouteDomainDriven.mdx'
 
 Route Functions provide full programmatic flexibility to define routes.
 
@@ -169,10 +168,6 @@ async <Link text={<code>onBeforeRender()</code>} href="/onBeforeRender" /> hook.
 
 See <Link href="/redirect" />.
 
-## Domain-driven file structure
-
-<RouteDomainDriven />
-
 ## Cannot provide `pageContext`
 
 Using Route Functions to provide `pageContext` values is forbidden.

diff --git a/docs/pages/route-string/+Page.mdx b/docs/pages/route-string/+Page.mdx
@@ -1,5 +1,4 @@
 import { Link } from '@brillout/docpress'
-import RouteDomainDriven from '../../components/RouteDomainDriven.mdx'
 
 For a page `/pages/movie/+Page.js`, you can define its Route String in an adjacent file `/pages/movie/+route.js`.
 
@@ -98,10 +97,6 @@ See <Link href="/routing-precedence" />.
 
 The special character `@` cannot be escaped, use a [Route Function](/route-function) instead.
 
-## Domain-driven file structure
-
-<RouteDomainDriven />
-
 ## See also
 
  - <Link href="/routing" />