Adding the docs folder

docs/_index.md

@@ -0,0 +1,11 @@
+---
+title: Overview
+menuName: Docs
+type: docs
+menus: main
+weight: 1
+---
+
+# What is Fabric?
+
+Fabric is an open-source configuration language and a CLI tool that enables the codification and automation of content generation process. The language includes components like documents, data definitions and content blocks.

docs/cli.md

@@ -0,0 +1,9 @@
+---
+title: Fabric CLI
+type: docs
+weight: 4
+---
+
+# Fabric CLI
+
+[TBD]

docs/install.md

@@ -0,0 +1,9 @@
+---
+title: Install
+type: docs
+weight: 2
+---
+
+# Install
+
+[TBD]

docs/language/_index.md

@@ -0,0 +1,9 @@
+---
+title: Language
+type: docs
+weight: 3
+---
+
+# Overview
+
+[TBD]

docs/language/blocks/_index.md

@@ -0,0 +1,9 @@
+---
+title: Blocks
+type: docs
+weight: 4
+---
+
+# Overview
+
+[TBD]

docs/language/blocks/content.md

@@ -0,0 +1,82 @@
+---
+title: Content blocks
+type: docs
+weight: 2
+---
+
+# Content blocks
+
+`content` block defines a call to a content plugin that produces a document segment. The order in which the `content` blocks are defined is important – it is the order in which the generated content will be placed in the document.
+
+```hcl
+# Root-level definition of the content block
+content <plugin-name> "<block-name>" {
+  ...
+}
+
+document "foobar" {
+
+  # In-document definition of the content block
+  content <plugin-name> "<block-name>" {
+    ...
+  }
+
+  content <plugin-name> {
+    ...
+  }
+
+}
+```
+
+If `content` block is defined on a root level of the configuration file, both names - the name of the plugin and the block name - must be provided. The plugin name / block name pair must be unique within the codebase, as it will be used as an identifier when referencing this block. The content blocks defined outside the document are not executed independently but must be referenced inside the document template.
+
+If the `content` block is defined in the document, only the plugin's name is required, while the block name is optional.
+
+The arguments set in the block are the input parameters for the content plugin, together with the plugin configuration and the local context map. Content plugins are expected to return a Markdown text string.
+
+The order in which `content` blocks are defined is preserved.
+
+## Supported Arguments
+
+- `config` – _(optional)_ a reference to a named config block defined on a root level. If provided, it takes precedence over the default config for the plugin.
+- `query` – _(optional)_ a `jq` query that will be applied to the global context map, and the result will be stored under the `query_result` path in the local context map (a local extended copy of the global context map).
+- `render_if_no_query_result` – _(optional)_ if content block should be rendered while `query_result` is empty. `true` by default (see [#28](https://github.com/blackstork-io/fabric/issues/28))
+- `text_when_no_query_result` – _(optional)_ provides a text to be rendered instead of the plugin-returned text. Only used when `render_if_no_query_result` is `true` (see [#28](https://github.com/blackstork-io/fabric/issues/28))
+- `query_input_required` – _(optional)_ an attribute with a boolean value, set to false by default (see [#29](https://github.com/blackstork-io/fabric/issues/29))
+- `query_input` – (optional) an attribute with a string value, empty by default. (see [#29](https://github.com/blackstork-io/fabric/issues/29))
+
+The plugin might define other supported arguments.
+
+
+## Supported Nested Blocks
+
+- `meta` – _(optional)_ a block that contains metadata for the content block
+- `config` – an inline config block for the plugin. If provided, it takes precedence over the default configuration for the plugin.
+
+Other nested blocks are not supported.
+
+
+## References
+
+If the label `ref` is used instead of `<plugin-name>`, the block references another content block defined on a root level. The name of the referer block is optional if the block is defined within the document. If the referer block (with label `ref`) is defined on a root level of the config file, the name is required.
+
+```hcl
+content openai "foo" {
+  ...
+}
+
+document "overview" {
+
+  content ref {
+    base = content.openai.foo
+    ...
+  }
+
+}
+
+```
+Every referer data block must have a `base` attribute set, pointing to a data block defined on a root level in the config file.
+
+Other supported arguments are defined by the plugin of the referent block (`openai` in the above example). If any arguments are provided in the referer block, they take precedence over the arguments set in the referent block.
+
+Referer blocks can not contain nested blocks.

docs/language/blocks/data.md

@@ -0,0 +1,80 @@
+---
+title: Data blocks
+type: docs
+weight: 1
+---
+
+# Data blocks
+
+`data` block defines a call to a data plugin. The data plugins provide data from external sources for content rendering. The order of the `data` block definitions in the document does not matter.
+
+```hcl
+data <plugin-name> "<result-name>" {
+  ...
+}
+
+document "foobar" {
+
+  data <plugin-name> "<result-name>" {
+    ...
+  }
+
+}
+```
+
+If `data` block is defined on a root level of the configuration file, both names - the name of the plugin and the result name - must be provided. The plugin name / result name pair must be unique within the codebase, as it will be used as an identifier when referencing this block. The data blocks defined outside the document are not executed independently but must be referenced inside the document template.
+
+If the `data` block is defined in the document, it must be on the root level of the document. The name of the plugin and the name of the result are required. The plugin name / result name pair must be unique in the scope of the document, since it will be used as an identifier.
+
+The arguments set in the block are the input parameters for the data plugin, together with the plugin configuration. The data returned by the plugin is set in the global context map under a path `data.<plugin-name>.<result-name>`
+
+
+## Supported Arguments
+
+- `config` – _(optional)_ a reference to a named config block defined on a root level. If provided, it takes precedence over the default config for the plugin.
+
+The plugin might define other supported arguments.
+
+
+## Supported Nested Blocks
+
+- `meta`
+- `config` – _(optional)_ an inline config block for the plugin. If provided, it takes precedence over the default configuration for the plugin.
+
+Other nested blocks are not supported.
+
+
+## References
+
+If the label `ref` is used instead of `<plugin-name>`, the block references another data block defined on a root level. The name of the referer block is optional if the block is defined within the document. If the referer block (with label `ref`) is defined on a root level of the config file, the name is required.
+
+{{< hint warning >}}
+#### Overriding existing blocks
+The data ref block with the already used name (explicit or inherited) will override the previously defined block.  
+{{< /hint >}}
+
+```hcl
+data elasticsearch "foo" {
+  ...
+}
+
+document "overview" {
+
+  data ref {
+    base = data.elasticsearch.foo
+    ...
+  }
+
+  data ref "foo2" {
+    base = data.elasticsearch.foo
+    ...
+  }
+
+}
+```
+
+Every referer block must have a `base` attribute set, pointing to a named data block defined on a root level in the config file.
+
+Other supported arguments are defined by the plugin of the referent block (`elasticsearch` in the above example). If any arguments are provided in the referer block, they take precedence over the arguments set in the referent block.
+
+Referer blocks can not contain nested blocks.

docs/language/blocks/section.md

@@ -0,0 +1,78 @@
+---
+title: Section blocks
+type: docs
+weight: 3
+---
+
+
+# Section blocks ([#16](https://github.com/blackstork-io/fabric/issues/16))
+
+`section` blocks are used for grouping `content` blocks for easier reusability and referencing. `section` blocks can contain other `section` blocks inside.
+
+```hcl
+section "<section-name>" {
+  ...
+}
+
+document "foobar" {
+  section {
+    ...
+  }
+
+  section "<section-name>" {
+    section {
+      ...
+    }
+    ...
+  }
+}
+```
+
+A section name must be provided if the `section` block is defined on a root level of the configuration file. The section name must be unique within the codebase, as it will be used as an identifier when referencing this block. The section blocks defined outside the document are not executed independently but must be referenced inside the document template.
+
+If the `section` block is defined inside the document template, a section name is optional.
+
+
+## Supported Arguments
+
+- `title` – _(optional)_ a title of the content group. It is a syntax sugar for a nested `content` block that renders a title. The title content block precedes any other nested `content` blocks or `sequence` blocks defined at the same level.
+
+
+No other arguments are supported.
+
+
+## Supported Nested Blocks
+
+- `meta`
+- `content`
+- `section`
+
+
+## References ([#9](https://github.com/blackstork-io/fabric/issues/9))
+
+If the label `ref` is used instead of `<section-name>`, the block references another `section` block defined on a root level. The name of the referer block is optional if the block is defined within the document. If the referer block (with label `ref`) is defined on a root level of the config file, the name is required.
+
+```hcl
+
+section "foo" {
+  ...
+}
+
+document "overview" {
+
+  section ref {
+    base = section.foo
+    ...
+  }
+
+}
+```
+
+If `title` argument is provided in the referer block, it takes precedence over the title defined in the referent block.
+
+Every referer block must have a `base` attribute set, pointing to a block defined on a root level in the config file.
+
+Referer blocks can not contain nested blocks.
+
+
+

docs/language/configs.md

@@ -0,0 +1,65 @@
+---
+title: Configuration
+type: docs
+weight: 2
+---
+
+# Global configuration ([#5](https://github.com/blackstork-io/fabric/issues/5))
+
+Fabric can be configured through a global configuration block:
+```hcl
+fabric {
+  ...
+}
+```
+
+There can be only one `fabric` block defined within the codebase.
+
+## Supported Arguments
+
+- `cache_dir` – _(optional)_ a path to a directory on the local FS. The default value is `./.fabric`. If the directory does not exist, it will be created on the first run of `fabric`.
+- `plugin_versions` – (required) a map that matches namespaced plugin names to the version constraints (SemVer, in Terraform's [version constraint syntax](https://developer.hashicorp.com/terraform/language/expressions/version-constraints#version-constraint-syntax))
+
+No other arguments are supported.
+
+## Supported Nested Blocks
+
+- `plugin_registry` – _(optional)_ block that defines available plugin registries. The block accepts only one attribute
+  ```hcl
+  plugin_registry {
+    mirror_dir = "/tmp/plugins/"
+  }
+  ```
+  - `mirror_dir` – _(optional)_ a path to a directory on the local FS with plugin archives.
+
+
+# Plugin configurations ([#4](https://github.com/blackstork-io/fabric/issues/4))
+
+`config` block defines a configuration for a plugin.
+
+```hcl
+
+config <plugin-type> <plugin-name> {
+    ...
+}
+
+config <plugin-type> <plugin-name> "<config-name>" {
+    ...
+}
+```
+
+`<plugin-type>` is either `content` or `data`.
+
+If `<config-name>` is not provided, the block is treated as a default configuration for the plugin of a specified type (`content` or `data`) with a specified name. Every time the plugin is executed (during the execution of `content` or `data` blocks), the configuration will be passed to the plugin.
+
+If `<config-name>` is set, the config block can be explicitely referenced inside the `content` or `data` block. This is helpful if there is a need to have multiple configurations for the same plugin.
+
+
+## Supported Arguments
+The arguments supported in the block are plugin-specific – every plugin defines the configuration options supported.
+
+
+## Supported Nested Blocks
+
+Nested blocks are not supported inside `config` blocks.
+

docs/language/documents.md

@@ -0,0 +1,31 @@
+---
+title: Documents
+type: docs
+weight: 3 
+---
+
+# Documents
+
+`document` block defines a document template with a specific name. The template name must be unique within the codebase, as it can be used as an identifier when referencing this block.
+
+The document name is required. The document blocks must be defined on a root level of the configuration file and can not be inside other blocks.
+
+```hcl
+document <document-name> {
+  ...
+}
+```
+
+## Supported Arguments
+
+- `title` – _(optional)_ a title of the document. It is a syntax sugar for a nested `content` block that renders a title. The title content block precedes any other nested `content` blocks or `sequence` blocks defined at the same level.
+
+No other arguments are supported.
+
+## Supported Nested Blocks
+
+- `meta`
+- `data`
+- `content`
+- `section`
+