From e1fb29894698f10a1c4359e2c6d420aa131cf37d Mon Sep 17 00:00:00 2001
From: Armin Ronacher <armin.ronacher@active-4.com>
Date: Sat, 26 Dec 2015 00:35:25 +0100
Subject: [PATCH] Added discoverable docs

---
 .../api/db/obj/is-discoverable/contents.lr    | 32 +++++++++++++++++++
 .../api/db/obj/is-undiscoverable/contents.lr  | 13 ++++++++
 .../api/db/query/include-hidden/contents.lr   |  5 +--
 .../query/include-undiscoverable/contents.lr  | 31 ++++++++++++++++++
 4 files changed, 79 insertions(+), 2 deletions(-)
 create mode 100644 content/docs/api/db/obj/is-discoverable/contents.lr
 create mode 100644 content/docs/api/db/obj/is-undiscoverable/contents.lr
 create mode 100644 content/docs/api/db/query/include-undiscoverable/contents.lr

diff --git a/content/docs/api/db/obj/is-discoverable/contents.lr b/content/docs/api/db/obj/is-discoverable/contents.lr
new file mode 100644
index 00000000..9847e4c4
--- /dev/null
+++ b/content/docs/api/db/obj/is-discoverable/contents.lr
@@ -0,0 +1,32 @@
+title: is_discoverable
+---
+summary: Indicates that a record can be discovered via .children
+---
+type: property
+---
+version_added: 2.0
+---
+body:
+
+Records can be discoverable or non discoverable.  This is controlled by the
+`_discoverable` system field which defaults to `yes.  This property can quickly
+check if a record is considered non-discoverable by Lektor or not.  In
+particular a hidden record is also considered undiscoverable.
+
+Undiscoverable records can be queried and final pages will be built but they
+are excempt from queries of the record.  This is useful for pages that should
+be built but not show up yet on overview pages.  For instance this can be used
+to implement drafts of blog posts or similar things.
+
+This property is implemented on the level of source objects to make it
+possible to use this API in all cases.  The default implementation of
+source objects will always return `true` for discoverability checks.
+
+## Example
+
+```html+jinja
+{% set downloads = site.get('/downloads') %}
+{% if downloads.is_discoverable %}
+  <p><a href="{{ downloads|url }}">Go to downloads</a>
+{% endif %}
+```
diff --git a/content/docs/api/db/obj/is-undiscoverable/contents.lr b/content/docs/api/db/obj/is-undiscoverable/contents.lr
new file mode 100644
index 00000000..5e4ac8a6
--- /dev/null
+++ b/content/docs/api/db/obj/is-undiscoverable/contents.lr
@@ -0,0 +1,13 @@
+title: is_undiscoverable
+---
+summary: The inverse of is_discoverable.
+---
+type: property
+---
+version_added: 2.0
+---
+body:
+
+This works like [is_discoverable :ref](../is-discoverable/) but the other
+way around.  It just exists for consistency and to make checks look a little
+bit nicer in some places.
diff --git a/content/docs/api/db/query/include-hidden/contents.lr b/content/docs/api/db/query/include-hidden/contents.lr
index eeea56a2..0e0ac0e7 100644
--- a/content/docs/api/db/query/include-hidden/contents.lr
+++ b/content/docs/api/db/query/include-hidden/contents.lr
@@ -10,8 +10,9 @@ body:
 
 This controls how the query should behave with regards to hidden records.
 A query created from the [children :ref](../../record/children/) attribute of
-a record will not include hidden records by default.  The opposite is true
-for queries created from the [query :ref](../../pad/query/) method of the pad.
+a record will not include hidden records (or undiscoverable) by default.  The
+opposite is true for queries created from the [query :ref](../../pad/query/)
+method of the pad.
 
 The parameter can be set to `True` to include hidden or `False` to exclude
 hidden records.
diff --git a/content/docs/api/db/query/include-undiscoverable/contents.lr b/content/docs/api/db/query/include-undiscoverable/contents.lr
new file mode 100644
index 00000000..d0abada9
--- /dev/null
+++ b/content/docs/api/db/query/include-undiscoverable/contents.lr
@@ -0,0 +1,31 @@
+title: include_undiscoverable
+---
+signature: value
+---
+summary: Controls what happens to records that are not discoverable.
+---
+type: method
+---
+version_added: 2.0
+---
+body:
+
+This controls how the query should behave with regards to undiscoverable
+records.  A query (either created from the [children :ref](../../record/children/)
+attribute or the [query :ref](../../pad/query/) method of the pad) will not
+include undiscoverable records by default.
+
+If undiscoverable records should included this method needs to be used.
+Set it to `True` to include hidden or `False` to exclude them (default).
+
+## Example
+
+Here a basic example of how to filter something in a template:
+
+```html+jinja
+<ul>
+{% for item in this.children.include_undiscoverable(true) %}
+  <li>{{ item.title }}
+{% endfor %}
+</ul>
+```