From 412a577362ffd0b50fca5c2ed7425ad27f8d7eda Mon Sep 17 00:00:00 2001 From: Simon Vrachliotis Date: Fri, 18 Aug 2023 14:26:03 +1000 Subject: [PATCH] Proposal to move path configuration to dedicated page (#540) --- docs/src/content/navigation.yaml | 4 + docs/src/content/pages/collections.mdoc | 2 +- .../how-keystatic-organises-your-content.mdoc | 90 +----------------- .../src/content/pages/path-configuration.mdoc | 92 +++++++++++++++++++ docs/src/content/pages/singletons.mdoc | 2 +- 5 files changed, 101 insertions(+), 89 deletions(-) create mode 100644 docs/src/content/pages/path-configuration.mdoc diff --git a/docs/src/content/navigation.yaml b/docs/src/content/navigation.yaml index 432cd824a..337212e0c 100644 --- a/docs/src/content/navigation.yaml +++ b/docs/src/content/navigation.yaml @@ -50,6 +50,10 @@ navGroups: link: discriminant: page value: singletons + - label: Path configuration + link: + discriminant: page + value: path-configuration - label: Reader API link: discriminant: page diff --git a/docs/src/content/pages/collections.mdoc b/docs/src/content/pages/collections.mdoc index fb3316b8d..f05aa6439 100644 --- a/docs/src/content/pages/collections.mdoc +++ b/docs/src/content/pages/collections.mdoc @@ -60,7 +60,7 @@ testimonials: collection({ By default, Keystatic will store entries at the root of your project, in a directory that matches the collection key. -You can learn more about the `path` option on the [Organised content page](/docs/how-keystatic-organises-your-content#collections). +You can learn more about the `path` option on the [Path configuration page](/docs/path-configuration). ## Type signature diff --git a/docs/src/content/pages/how-keystatic-organises-your-content.mdoc b/docs/src/content/pages/how-keystatic-organises-your-content.mdoc index 326130edc..deb79aa45 100644 --- a/docs/src/content/pages/how-keystatic-organises-your-content.mdoc +++ b/docs/src/content/pages/how-keystatic-organises-your-content.mdoc @@ -8,95 +8,11 @@ Those are defined in the [Keystatic configuration](/docs/configuration). You get a lot of control and flexibility with *where* your content gets generated, both at the `collection` or `singleton` level, and at the `field` level for certain field types, like images. -## Content path +### Path configuration -You can define *where* Keystatic should store collection entries and singletons via the `path` property in the collection/singleton top-level options. +You can define _where_ Keystatic should store collection entries and singletons via the `path` property in the collection/singleton top-level options. -```javascript -// Keystatic config -export default config({ - collections: { - posts: collection({ - label: 'Posts', - path: 'content/posts/*/', - // ... - }) - }, - singletons: { - settings: singleton({ - label: 'Settings', - path: 'content/posts/', - // ... - }) - } -}) - -``` - -The optional trailing slash `/` on that path has an impact on the content structure - read below for more details on `collection paths` and `singleton paths`. - -### Path wildcard for collections - -The `path` property for `collections` must contain a `*` wildcard. - -It represents the `slug` of an entry. - -This wildcard gives you flexibility and control over your where your content is being output. - -### Nested folder output example - -{% aside icon="👉" %} - `path: 'packages/design-system/*/docs/'` -{% /aside %} - -Imagine a Design System inside a monorepo: - -```sh -root -├── packages - ├── design-system - ├── button - └── src - ├── dropdown - └── src -└── apps - └── docs(keystatic) -``` - -Your Keystatic site lives in `apps/docs`, but you want your documentation entries in `packages/design-system/{component-name}/docs/`, to collocate them with each component. - -The following path will let you do exactly that: - -``` -path: 'packages/design-system/*/docs/' -``` - -### Nested slug example - -{% aside icon="👉" %} - `path: 'content/posts/**'` -{% /aside %} - -There may be situations where you need the `slug` of an entry to be following a multi-folder structure. - -Say you want the **same collection** to support this following tree structure: - -```sh -content -├── posts - ├── en - └── post-1.mdoc - ├── fr - └── post-1.mdoc -``` - -You can enable this by using the `**` wildcard in your `path`: - -``` -path: 'content/posts/**' -``` - -Since Keystatic `slugs` can contain `/` characters, you construct a multi-folder structure with `slug` field values like: `en/post-1` and `fr/post-1`. +We will go over core concepts here, but check out the [Path configuration page](/docs/path-configuration) for more details and examples. --- diff --git a/docs/src/content/pages/path-configuration.mdoc b/docs/src/content/pages/path-configuration.mdoc new file mode 100644 index 000000000..e9d886c74 --- /dev/null +++ b/docs/src/content/pages/path-configuration.mdoc @@ -0,0 +1,92 @@ +--- +title: Path configuration +summary: Granular control over where Keystatic stores content. +--- + +You can define *where* Keystatic should store collection entries and singletons via the `path` property in the collection/singleton top-level options. + +```javascript +// Keystatic config +export default config({ + collections: { + posts: collection({ + label: 'Posts', + path: 'content/posts/*/', + // ... + }) + }, + singletons: { + settings: singleton({ + label: 'Settings', + path: 'content/posts/', + // ... + }) + } +}) + +``` + +The optional trailing slash `/` on that path has an impact on the content structure - read below for more details on `collection paths` and `singleton paths`. + +## Path wildcard for collections + +The `path` property for [collections](/docs/collections) must contain a `*` wildcard. + +It represents the `slug` of an entry. + +This wildcard gives you flexibility and control over your where your content is being output. + +## Nested folder output example + +{% aside icon="👉" %} + `path: 'packages/design-system/*/docs/'` +{% /aside %} + +Imagine a Design System inside a monorepo: + +```sh +root +├── packages + ├── design-system + ├── button + └── src + ├── dropdown + └── src +└── apps + └── docs(keystatic) +``` + +Your Keystatic site lives in `apps/docs`, but you want your documentation entries in `packages/design-system/{component-name}/docs/`, to collocate them with each component. + +The following path will let you do exactly that: + +``` +path: 'packages/design-system/*/docs/' +``` + +## Nested slug example + +{% aside icon="👉" %} + `path: 'content/posts/**'` +{% /aside %} + +There may be situations where you need the `slug` of an entry to be following a multi-folder structure. + +Say you want the **same collection** to support this following tree structure: + +```sh +content +├── posts + ├── en + └── post-1.mdoc + ├── fr + └── post-1.mdoc +``` + +You can enable this by using the `**` wildcard in your `path`: + +``` +path: 'content/posts/**' +``` + +Since Keystatic `slugs` can contain `/` characters, you construct a multi-folder structure with `slug` field values like: `en/post-1` and `fr/post-1`. \ No newline at end of file diff --git a/docs/src/content/pages/singletons.mdoc b/docs/src/content/pages/singletons.mdoc index b5b417879..2265ff99c 100644 --- a/docs/src/content/pages/singletons.mdoc +++ b/docs/src/content/pages/singletons.mdoc @@ -40,7 +40,7 @@ settings: singleton({ By default, Keystatic will store a singleton at the root of your project, in a directory that matches the singleton key. -You can learn more about the `path` option on the [Organised content page](/docs/how-keystatic-organises-your-content#singletons). +You can learn more about the `path` option on the [Path configuration page](/docs/path-configuration). ## Type signature