diff --git a/content/docs/api/db/record/getitem/contents.lr b/content/docs/api/db/record/getitem/contents.lr new file mode 100644 index 00000000..99baf1d2 --- /dev/null +++ b/content/docs/api/db/record/getitem/contents.lr @@ -0,0 +1,22 @@ +title: [] +--- +summary: Looks up a field from the type. +--- +type: operator +--- +body: + +The “get-item” operator is used to look up a field from a record. Within +templates attribute access automatically falls back to this operator which +is why you can typically access `foo.bar` instead of `foo['bar']` unless a +conflict with a record property exists. + +All available fields can be accessed this way (model defined fields as well +as system fields which are prefixed by an underscore). + +## Example + +```python +for child in this.children: + print 'ID: %s' % child['_id'] +``` diff --git a/content/docs/api/db/system-fields/alt/contents.lr b/content/docs/api/db/system-fields/alt/contents.lr new file mode 100644 index 00000000..fba8eb90 --- /dev/null +++ b/content/docs/api/db/system-fields/alt/contents.lr @@ -0,0 +1,11 @@ +title: _alt +--- +summary: The alt for this record. +--- +type: sysfield +--- +body: + +This field points to the [Alternative :ref](../../../../content/alts/) of +the page. This should be considered as an internal field that is exposed +through the [alt :ref](../../obj/alt/) source object property instead. diff --git a/content/docs/api/db/system-fields/attachment-type/contents.lr b/content/docs/api/db/system-fields/attachment-type/contents.lr new file mode 100644 index 00000000..5471f6e7 --- /dev/null +++ b/content/docs/api/db/system-fields/attachment-type/contents.lr @@ -0,0 +1,14 @@ +title: _attachment_type +--- +summary: An indication of the attachment type. +--- +type: sysfield +--- +body: + +This indicates the type of the attachment. Currently only a small set of +attachments is detected. The most useful attachment type is `image` which +identifies images. The attachments are detected by the file extension. + +!!!! This feature in many ways does not entirely work as you would expect +and should be taken is something that will improve in future versions. diff --git a/content/docs/api/db/system-fields/contents.lr b/content/docs/api/db/system-fields/contents.lr new file mode 100644 index 00000000..9d48a849 --- /dev/null +++ b/content/docs/api/db/system-fields/contents.lr @@ -0,0 +1,13 @@ +title: System Fields +--- +summary: The complete list of system fields in Lektor +--- +body: + +All records have a few system fields available in addition to the fields +defined by the data model. These fields are always there and control internal +behavior in Lektor. They are prefixed by an underscore to separate them +from the fields a model defines. + +Many system fields are hidden from the admin panel but some can be changed +there (`_template`, `_hidden`, and a few others). diff --git a/content/docs/api/db/system-fields/discoverable/contents.lr b/content/docs/api/db/system-fields/discoverable/contents.lr new file mode 100644 index 00000000..080035d8 --- /dev/null +++ b/content/docs/api/db/system-fields/discoverable/contents.lr @@ -0,0 +1,20 @@ +title: _discoverable +--- +summary: Controls if this page is picked up by collection queries by default. +--- +type: sysfield +--- +version_added: 2.0 +--- +body: + +By default any non hidden page is returned from `.children` on iteration. This +field can be set to `no` to hide a page from such default queries. This +implicitly hides a page for most template operations but Lektor will still +build it. This for instance is very useful for draft blog posts. If a post is +set to not being discoverable it will be hidden from the blog index without +further custom template code, but someone who knows the URL can still find it. + +This is also particularly useful to hide special pages such as `sitemap.xml` +which would otherwise cause problems because generic code might not expect +it. diff --git a/content/docs/api/db/system-fields/gid/contents.lr b/content/docs/api/db/system-fields/gid/contents.lr new file mode 100644 index 00000000..11353d03 --- /dev/null +++ b/content/docs/api/db/system-fields/gid/contents.lr @@ -0,0 +1,20 @@ +title: _gid +--- +summary: A globally unique ID of the page. +--- +type: sysfield +--- +body: + +The `_gid` is the MD5 hashed version of the page's [`_path`](../path/). This +is useful in situations where a stable ID is needed that follows a certain +format. For instance it can come in useful when a ID is needed for a DOM +element. + +## Example + +```html+jinja + +... + +``` diff --git a/content/docs/api/db/system-fields/hidden/contents.lr b/content/docs/api/db/system-fields/hidden/contents.lr new file mode 100644 index 00000000..330e6bc8 --- /dev/null +++ b/content/docs/api/db/system-fields/hidden/contents.lr @@ -0,0 +1,20 @@ +title: _hidden +--- +summary: Controls if the page should be built or not. +--- +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`. + +This also automatically applies to all children of a page unless they +forcefully override this setting. + +This is useful for more advanced setups like [Single Page Applications +:ref](../../../../guides/single-page/). + +Hidden pages are automatically also removed from the `.children` property +of records but stay available for querying via the pad. diff --git a/content/docs/api/db/system-fields/id/contents.lr b/content/docs/api/db/system-fields/id/contents.lr new file mode 100644 index 00000000..a26d4311 --- /dev/null +++ b/content/docs/api/db/system-fields/id/contents.lr @@ -0,0 +1,32 @@ +title: _id +--- +summary: The local identifier of a record. +--- +type: sysfield +--- +body: + +Each record has an `_id`. This ID is basically a form of the filename. +Depending on if you are looking at an attachment or a page the rules are +slightly different. + +For pages the ID is the name of the folder. So if you have a page called +`docs/overview/contents.lr` then `_id` is `overview`. If you have however +an attachment named `docs/overview/screenshot.jpg` the `_id` will be the +filename of the attachment: `screenshot.jpg`. + +Note that IDs are not globally unique! There is also the `_path` which is +the entire path if the record. + +The `_id` is automatically set and cannot be overridden. + +## Example + +```html+jinja + +``` diff --git a/content/docs/api/db/system-fields/model/contents.lr b/content/docs/api/db/system-fields/model/contents.lr new file mode 100644 index 00000000..d8f2f3b8 --- /dev/null +++ b/content/docs/api/db/system-fields/model/contents.lr @@ -0,0 +1,23 @@ +title: _model +--- +summary: The model the record uses for its fields. +--- +type: sysfield +--- +body: + +This field selects the model that should be used for non-system fields. In +many situations the model is picked automatically but for equally many +situations it needs to be selected manually. + +This field is most useful for filtering when operating on mixed collections. + +## Example + +```html+jinja + +``` diff --git a/content/docs/api/db/system-fields/path/contents.lr b/content/docs/api/db/system-fields/path/contents.lr new file mode 100644 index 00000000..25909794 --- /dev/null +++ b/content/docs/api/db/system-fields/path/contents.lr @@ -0,0 +1,22 @@ +title: _path +--- +summary: The full path of the record. +--- +type: sysfield +--- +body: + +The `_path` is the more complete version of the [`_id`](../id/). It contains +the entire path of records that are the parents of a record. So if you have a +record named `docs/api/db/contents.lr` the `_id` would be `db` but the `_path` +would be `docs/api/db`. + +The path can be used to uniquely identify a page but for that purpose the +[`_gid`](../gid/) can also be used which is a hashed hexadecimal version of +the page. + +## Example + +```html+jinja + +``` diff --git a/content/docs/api/db/system-fields/slug/contents.lr b/content/docs/api/db/system-fields/slug/contents.lr new file mode 100644 index 00000000..1eac76ad --- /dev/null +++ b/content/docs/api/db/system-fields/slug/contents.lr @@ -0,0 +1,13 @@ +title: _slug +--- +summary: The URL slug of the record. +--- +type: sysfield +--- +body: + +This field defines the URL slug of the record. If not set it defaults to +either the `_id` or an expansion of what the parent defines for all children. + +For more information about this refer to [URLs and Slugs +:ref](../../../../content/urls/). diff --git a/content/docs/api/db/system-fields/source-alt/contents.lr b/content/docs/api/db/system-fields/source-alt/contents.lr new file mode 100644 index 00000000..dee19b74 --- /dev/null +++ b/content/docs/api/db/system-fields/source-alt/contents.lr @@ -0,0 +1,20 @@ +title: _source_alt +--- +summary: The alt from the source of the record. +--- +type: sysfield +--- +body: + +This field points to the true source [Alternative +:ref](../../../../content/alts/) of the page. This primarily exists internally +to support the builder. In particular the difference to the `_alt` field is +that this one will indicate if an alt falls back to a different alternative. +At present pages can only fall back to the `_primary` alternative which will +be reflected by this field. + +## Example + +```html+jinja + +``` diff --git a/content/docs/api/db/system-fields/template/contents.lr b/content/docs/api/db/system-fields/template/contents.lr new file mode 100644 index 00000000..06663af9 --- /dev/null +++ b/content/docs/api/db/system-fields/template/contents.lr @@ -0,0 +1,13 @@ +title: _template +--- +signature: +--- +summary: Selects the template for the page. +--- +type: sysfield +--- +body: + +This field sets the template that Lektor uses for rendering. It defaults to +model name + `.html`. If the `_model` is `page` the name of the template +will be `page.html`. In some situations it makes sense to override this. diff --git a/content/docs/content/contents.lr b/content/docs/content/contents.lr index 709dbcb8..4a5abecb 100644 --- a/content/docs/content/contents.lr +++ b/content/docs/content/contents.lr @@ -85,6 +85,10 @@ the key. The format of each field is specific to how the model is configured. Some fields are plain text, others can be markdown syntax and more. These fields become available for rendering in the template automatically. -**Tip:** If you want to use `---` itself in the document text, just add another +!!! If you want to use `---` itself in the document text, just add another dash. This means `----` will render as `---` and `-----` will render as `----` etc. + +Fields prefixed with an underscore are so-called system fields. They are +provided by Lektor and customize behavior within Lektor. For a list of +available fields see [System Fields :ref](../api/db/system-fields/). diff --git a/models/doc-page.ini b/models/doc-page.ini index 7a299f62..52d28bdc 100644 --- a/models/doc-page.ini +++ b/models/doc-page.ini @@ -28,16 +28,12 @@ default = yes checkbox_label = Show comment box width = 1/4 -[fields.body] -label = Body -type = markdown - [fields.type] label = Technical Type type = select description = Of what general type this doc page is. If not set, it's a normal doc page. -choices = class, function, method, property, operator, filter, cmdlet, event, type -choice_labels = Class, Function, Method, Property, Operator, Filter, Commandlet, Event, Field Type +choices = class, function, method, property, operator, filter, cmdlet, event, type, sysfield +choice_labels = Class, Function, Method, Property, Operator, Filter, Commandlet, Event, Field Type, System Field width = 1/2 [fields.module] @@ -61,3 +57,7 @@ description = An optional template variable if it exists there as such. [fields.version_added] label = Added in version type = string + +[fields.body] +label = Body +type = markdown diff --git a/templates/macros/docs.html b/templates/macros/docs.html index b2c76c55..11395064 100644 --- a/templates/macros/docs.html +++ b/templates/macros/docs.html @@ -11,7 +11,7 @@ {%- elif page.type == 'event' -%} - {%- elif page.type == 'type' -%} + {%- elif page.type == 'type' or page.type == 'sysfield' -%} {%- else -%}