From 7a6ccd0e38d1c645da18bfbe167ad96756bb63b8 Mon Sep 17 00:00:00 2001 From: Jeff Dairiki Date: Wed, 27 Jul 2022 09:01:03 -0700 Subject: [PATCH] Clarify documentation on hidden records This clarifies the documentation regarding the default value for a records _hidden field. --- .../docs/api/db/system-fields/hidden/contents.lr | 15 +++++++++++---- content/docs/models/attachments/contents.lr | 6 +++--- content/docs/models/children/contents.lr | 5 ++++- 3 files changed, 18 insertions(+), 8 deletions(-) diff --git a/content/docs/api/db/system-fields/hidden/contents.lr b/content/docs/api/db/system-fields/hidden/contents.lr index 330e6bc8..73aba008 100644 --- a/content/docs/api/db/system-fields/hidden/contents.lr +++ b/content/docs/api/db/system-fields/hidden/contents.lr @@ -7,11 +7,18 @@ type: sysfield body: This field controls if Lektor should process the page into a build artifact. -By default each page is built into a build artifact (HTML page) and each -attachment is processed. This can be prevented by setting `_hidden` to `yes`. +By default, each page is built into a build artifact (HTML page) and each +attachment is copied to the output directory. +This can be prevented for a particular page or attachment by setting its `_hidden` to `yes`. -This also automatically applies to all children of a page unless they -forcefully override this setting. +If an explicit value for the `_hidden` field is not set, the value of the `hidden` option in the +[child configuration] — or, for attachments, [attachment configuration] — section +of the parent's datamodel is checked. +If that, too, is not set, then pages, but not attachments, inherit the hidden status of their parent — +that is, by default, children of hidden pages will not be built, though attachments of hidden pages will. + +[child configuration]: https://www.getlektor.com/docs/models/children/#child-configuration (The [children] section of the datamodel) +[attachment configuration]: https://www.getlektor.com/docs/models/attachments/ (The [attachments] section of the datamodel) This is useful for more advanced setups like [Single Page Applications :ref](../../../../guides/single-page/). diff --git a/content/docs/models/attachments/contents.lr b/content/docs/models/attachments/contents.lr index 31fec50e..854a2de3 100644 --- a/content/docs/models/attachments/contents.lr +++ b/content/docs/models/attachments/contents.lr @@ -13,9 +13,9 @@ There are a few settings to control these in the `[attachments]` section: * `model`: an optional default model that is used for all attachments. * `order_by`: controls the ordering of attachments, similar to how this works for child pages. -* `hidden`: if this is set it can override the hidden flag for all - attachments at once. The default as of Lektor 2 is that attachments are - not hidden by default. +* `hidden`: if this is set, attachments will not be built. + (Note that any setting here may be overridden on a per attachment basis by + setting that attachment's [`_hidden` field](https://www.getlektor.com/docs/models/attachments/).) !! The `hidden` flag was added in Lektor 2.0 and the default was changed so that attachments are not hidden by default, even if the parent is. diff --git a/content/docs/models/children/contents.lr b/content/docs/models/children/contents.lr index 73cd4239..49a96399 100644 --- a/content/docs/models/children/contents.lr +++ b/content/docs/models/children/contents.lr @@ -40,7 +40,10 @@ Here are the most important options below `[children]`: - `hidden`: if this is set it can override the parent's hidden flag for all children. This is particularly useful if you want to have a folder for error pages or other special pages where the parent itself should not - be rendered but all children are. The default is not set. + be rendered but all children should. The default is not set. + (Note that an explicit value for a + [child's `_hidden` field](/docs/api/db/system-fields/hidden/) will + override any value set here.) !! The `hidden` flag was added in Lektor 2.0