More docs for system fields

content/docs/content/system-fields/contents.lr

@@ -0,0 +1,61 @@
+title: System Fields
+---
+summary: Brief overview of the system fields in Lektor.
+---
+body:
+
+In addition to the fields that are defined through the [Data Model
+:ref](../../models/) there are a lot of fields that come directly from Lektor.
+They can be easily recognized because they are prefixed by a leading underscore
+(`_`).
+
+These fields influence how Lektor treats pages and attachment.  Here we will
+just go over the most important ones but for a full list you can have a look
+[at the API Documentation :ref](../../api/db/system-fields/).
+
+## `_hidden`
+
+This field is a boolean value and controls if a page is hidden or not.  If a
+page is hidden all of it's children will automatically also be hidden.  A page
+that is hidden will not be processed by Lektor's build system.  This means such
+pages can be discovered through the query API but they are not rendered
+themselves.  This is useful for situations where you want to have information
+stored but not rendered.  This is for instance used to [implement Single-Page
+websites :ref](../../guides/single-page/).
+
+*To read more read [the field documentation :ref](../../api/db/system-fields/hidden/).*
+
+## `_discoverable`
+
+This fields in many ways is similar to `_hidden` but instead makes a page
+be only hidden from queries.  In particular this means that it will still be
+processed and built, but that it becomes harder for code to reference it.
+Pages that are not set to discoverable can only be found through queries if
+they are [explicitly included :ref](../../api/db/query/include-undiscoverable/).
+
+!! This field was added in Lektor 2.0.  In earlier versions this feature is
+unavailable.
+
+*To read more read [the field documentation :ref](../../api/db/system-fields/discoverable/).*
+
+## `_model`
+
+This key sets the [Data Model :ref](../../models/) that is used for the record.
+If not set this defaults to one of different choices depending on configuration
+or name.  Parent models can pre-define models for children which is the used if
+this key is not set.  If not set this will be picked up by an algorithm.
+See [Default Model Selection :ref](../../models/selection/) for more information.
+
+*To read more read [the field documentation :ref](../../api/db/system-fields/model/).*
+
+## `_slug`
+
+This field can override the default URL slug.  For more information about this
+feature see [URLs and Slugs :ref](../urls/).
+
+## `_template`
+
+This field can be used to override the default template selection which is
+just the model name with the `.html` extension.
+
+*To read more read [the field documentation :ref](../../api/db/system-fields/template/).*

content/docs/models/contents.lr

@@ -15,8 +15,9 @@ easier later to generate beautiful looking HTML.
 Models are the blueprints for your pages.  They define which fields exist and
 what goes into them.  Models are stored in the `models` folder in your project
 and are basic UTF-8 encoded INI files.  Models can have any name but if no
-model has been explicitly selected, the model with the name `page` will be
+model has been explicitly selected, a default model will be selected.  For
-used.  So having a model with that name is always a good idea.
+most situations this will be the model with the name `page`.  Detailed
+information can be found under [Default Model Selection :ref](selection/).
 
 Here is an example of a very basic model (`models/page.ini`):
 

content/docs/models/selection/contents.lr

@@ -0,0 +1,23 @@
+title: Default Model Selection
+---
+summary: Explains how Lektor decides on the model to use.
+---
+body:
+
+When Lektor encounters a content file it needs to decide which data model to
+use for figuring out how to handle the fields.  In the ideal case the content
+file contains `_model` field which will point explicitly to a model.  However
+if a model was not defined it's picked automatically.
+
+Lektor will attempt to load a few models and will pick the first that exists.
+If no model exists at all then Lektor calls back to the special `none` model
+which is empty other than for system fields.
+
+1. If a model is defined for children by the parent model then it's used.
+   For more information about this feature see [Children & Pagination
+   :ref](../children/).
+2. The ID of the page is attempted as model name next.
+3. If it still does not match anything, it will try the default `page`
+   model.
+4. If that also does not match, it falls back to the special `none` model
+   which is always empty.