Import docs

docs/Website.lektorproject

@@ -0,0 +1,16 @@
+[project]
+name = Lektor
+url = https://www.getlektor.com/
+url_style = absolute
+
+[servers.production]
+enabled = yes
+name = Production
+target = rsync://deploy@flow.srv.pocoo.org/srv/websites/getlektor.com/static
+default = yes
+
+[packages]
+lektor-webpack-support = 0.3
+lektor-markdown-header-anchors = 0.1
+lektor-markdown-highlighter = 0.1
+lektor-markdown-admonition = 0.1

docs/configs/markdown-highlighter.ini

@@ -0,0 +1,2 @@
+[pygments]
+style = tango

docs/content/api/build/artifact/artifact-name/contents.lr

@@ -0,0 +1,11 @@
+title: artifact_name
+---
+summary: The name of the artifact
+---
+type: property
+---
+body:
+
+This property just returns the artifact name.  This is mostly useful for
+debugging purposes as in the majority of situations you already have
+the artifact name from different sources.

docs/content/api/build/artifact/contents.lr

@@ -0,0 +1,34 @@
+title: Artifact
+---
+summary: Represents an artifact during the build process.
+---
+type: class
+---
+body:
+
+During the build process Lektor creates artifact objects to represent final
+build artifacts.  Generally each [Source Object :ref](../../db/obj/) will
+generate one artifact for which it acts as a primary source.
+
+There are however many cases in which a source object will create
+sub-artifacts.  For instance any thumbnail created in the context of a page
+will be creating its own artifact.  To give plugins the same ability the
+artifact system is partially documented.  See also [sub_artifact
+:ref](../context/sub-artifact/) to see how to create your own artifact
+instances.
+
+The most important function of an artifact is [open :ref](open/) which can
+open the artifact for reading or writing.  If the build goes well, Lektor
+will commit those changes and persist them.
+
+## Example
+
+```python
+ctx = get_ctx()
+@ctx.sub_artifact('artifact.txt')
+def build_stylesheet(artifact):
+    with artifact.open('w') as f:
+        f.write('Hello World!\n')
+```
+---
+module: lektor.builder

docs/content/api/build/artifact/is-current/contents.lr

@@ -0,0 +1,12 @@
+title: is_current
+---
+summary: Indicates if the artifact is up to date or needs building.
+---
+type: property
+---
+body:
+
+This property on an artifact returns `True` if building is necessary or
+`False` if not based on the state of all dependencies.  When you are using
+the sub-artifact system, the builder callback will only be invoked if the
+artifact is not current.

docs/content/api/build/artifact/open/contents.lr

@@ -0,0 +1,28 @@
+title: open
+---
+summary: Can open the artifact for reading or writing.
+---
+type: method
+---
+signature: mode='rb', ensure_dir=None
+---
+body:
+
+This opens the artifact for reading or writing.  The default behavior is that
+if the artifact is opened for reading, the directory it's contained within
+automatically is created.  This can be disabled or enabled with the
+`ensure_dir` parameter.
+
+If the artifact is opened for writing, a copy will be created and only
+committed when the entire build process goes through smoothly and the
+changes are committed by the builder.
+
+## Example
+
+```python
+ctx = get_ctx()
+@ctx.sub_artifact('artifact.txt')
+def build_stylesheet(artifact):
+    with artifact.open('w') as f:
+        f.write('Hello World!\n')
+```

docs/content/api/build/artifact/render-template-into/contents.lr

@@ -0,0 +1,26 @@
+title: render_template_into
+---
+summary: Renders a template into the artifact.
+---
+signature: template_name, this, fail=False, pad=None, this=None, values=None, alt=None
+---
+type: method
+---
+body:
+
+This method renders a template into the artifact.  The default behavior is to
+catch the error and render it into the template with a failure marker.  This
+can be changed with the `fail` parameter.  This is similar to the behavior of
+the [render_template :ref](../../../environment/render-template/) method of the
+environment.
+
+## Example
+
+```python
+class MyBuildProgram(BuildProgram):
+    ...
+
+    def build_artifact(self, artifact):
+        artifact.render_template_into(
+            self.source['_template'], this=self.source)
+```

docs/content/api/build/artifact/replace-with-file/contents.lr

@@ -0,0 +1,24 @@
+title: replace_with_file
+---
+summary: Replaces the artifact with a file from the file system.
+---
+type: method
+---
+signature: filename, ensure_dir=None, copy=False
+---
+body:
+
+This method will replace the artifact with another file on the file system
+on commit.  This is useful when you are dealing with external applications
+that create temporaries.  By default the file is moved as this is what's
+common with temporaries but this can be changed into a copy with `copy=True`.
+
+## Example
+
+```python
+ctx = get_ctx()
+@ctx.sub_artifact('artifact.txt')
+def build_stylesheet(artifact):
+    temporary_file = invoke_external_program()
+    artifact.replace_with_file(temporary_file)
+```

docs/content/api/build/artifact/source-obj/contents.lr

@@ -0,0 +1,12 @@
+title: source_obj
+---
+summary: A reference to the source object if available.
+---
+type: property
+---
+body:
+
+If an artifact directly corresponds to a [Source Object :ref](../../../db/obj/)
+then this will be a reference to it.  For most plugins this is unlikely but
+if you provide a source obj in the `sub_artifact` call it will be available
+here.

docs/content/api/build/contents.lr

@@ -0,0 +1,9 @@
+title: Build System
+---
+summary: Everything about Lektor's build system.
+---
+body:
+
+The build system in Lektor is what is responsible for converting the source
+files into the final website.  Parts of it are currently documented so that
+the plugin system can interact with it.

docs/content/api/build/context/changed-base-url/contents.lr

@@ -0,0 +1,21 @@
+title: changed_base_url
+---
+summary: Can override the base URL that is used for relative URL generation.
+---
+type: method
+---
+signature: value
+---
+body:
+
+By default the URL generation is relative to the current source record
+but in some cases this can lead to issues when plugins attempt more complex
+operations.  In these cases the base URL can temporarily be overridden
+with this method.
+
+## Example
+
+```python
+with get_ctx().changed_base_url('/downloads/'):
+    url = url_to('/')
+```

docs/content/api/build/context/contents.lr

@@ -0,0 +1,29 @@
+title: Context
+---
+summary: Provides context information for the current build.
+---
+module: lektor.context
+---
+type: class
+---
+body:
+
+When Lektor builds sources into finished build artifacts it performs many
+operations in addition to just creating the end result.  For instance it needs
+to perform dependency tracking, it needs to remember that there might be
+associated other artifacts and more.  All this information is tracked on the
+`Context` during a build of a single source.  At a later point the builder
+will look at the context to decide on further operations to perform.
+
+The current context can be discovered by calling the [get_ctx :ref](../get-ctx/)
+function which will return it.  If there is no artifact build ongoing then
+the return value will be `None`.
+
+## Basic Example
+
+```python
+from lektor.context import get_ctx
+
+ctx = get_ctx()
+print('The current source is %s' % ctx.source)
+```

docs/content/api/build/context/gather-dependencies/contents.lr

@@ -0,0 +1,25 @@
+title: gather_dependencies
+---
+summary: Can collect dependencies for a code block.
+---
+type: method
+---
+signature: func
+---
+body:
+
+As code is executing in the context of the build process Lektor will
+automatically track dependencies.  However in some cases it might be
+useful for a plugin to know exactly which dependencies are recorded.
+
+In this case this method can be used as a context manager.  Whenever Lektor
+encounters a dependency it will invoke the passed function.
+
+## Example
+
+```python
+deps = set()
+with get_ctx().gather_dependencies(deps.add):
+    items = pad.query('/path/to/some/pages').all()
+print('The dependencies are: %s' % deps)
+```

docs/content/api/build/context/locale/contents.lr

@@ -0,0 +1,20 @@
+title: locale
+---
+summary: The current locale (language/territory) code for the context.
+---
+type: property
+---
+body:
+
+For functionality in Lektor that is dependent on the locale (technical
+term for language and territory) the context provides this information.  It's
+automatically resolved based on configuration from the current alt.
+
+This is primarily useful for plugins that want to change their behavior based
+on the current requested language.
+
+## Example
+
+```python
+print get_ctx().locale
+```

docs/content/api/build/context/pad/contents.lr

@@ -0,0 +1,20 @@
+title: pad
+---
+summary: A reference to the active database pad.
+---
+type: property
+---
+body:
+
+To access the current pad from the context, this attribute can be used.  It
+refers to the active [Pad :ref](../../../db/pad/).
+
+## Example
+
+```python
+from lektor.context import get_ctx
+
+ctx = get_ctx()
+for child in ctx.pad.root.children:
+    do_something_with(child)
+```

docs/content/api/build/context/record-dependency/contents.lr

@@ -0,0 +1,43 @@
+title: record_dependency
+---
+summary: Instructs the builder to record a new dependency for the current artifact.
+---
+type: method
+---
+signature: filename
+---
+body:
+
+Because Lektor is a system that builds artifacts into static files, an
+important part of it is the dependency graph.  It tracks dependencies between
+produced artifacts and source files to automatically determine which files
+need to be rebuilt when sources change.
+
+As such it's crucial that plugins record dependencies properly or changes
+will not show up, even if sources change.
+
+This can be achieved with the `record_dependency` context method.  If a plugin
+references a file which can affect the output of the plugin, it's important
+to record this as a dependency.
+
+Note that you should only track dependencies below the project folder.  It
+is possible to dependend to things outside of it, but the automatic watch
+system of the builder will not track files there so they will not show up
+unless a manual build is instructed.
+
+## Example
+
+```python
+import os
+from lektor.pluginsystem import Plugin
+
+class IncludeFilePlugin(Plugin):
+
+    def setup_env(self, **extra):
+        def include_file(filename):
+            fn = os.path.join(self.env.root_path, 'inc', filename)
+            get_ctx().record_dependency(fn)
+            with open(fn) as f:
+                return f.read().decode('utf-8')
+        self.env.jinja_env.globals['include_file'] = include_file
+```

docs/content/api/build/context/record/contents.lr

@@ -0,0 +1,20 @@
+title: record
+---
+summary: A reference to the current source record.
+---
+type: property
+---
+body:
+
+This works almost exactly like the [source :ref](../source/) property but the
+difference is that it is `None` if the source object is not a
+[Record :ref](../../../db/record/).
+
+## Example
+
+```python
+from lektor.context import get_ctx
+
+ctx = get_ctx()
+print ctx.record.record_label
+```

docs/content/api/build/context/source/contents.lr

@@ -0,0 +1,21 @@
+title: source
+---
+summary: A reference to the current source object.
+---
+type: property
+---
+body:
+
+The context is created for each target artifact.  As most artifacts are
+created from [Source Objects :ref](../../../db/obj/), it's typically possible
+to refer back to it.  Note that there are situations in which artifacts are
+created but no source is available.  In this case the value will be `None`.
+
+## Example
+
+```python
+from lektor.context import get_ctx
+
+ctx = get_ctx()
+print ctx.source.source_filename
+```