Documentation improvements (#143)

.gitignore

@@ -13,8 +13,8 @@ bin/*
 .DS_Store
 
 # Vale will install modules in `.vale/style` and those should not be in version control
-.vale/styles/*
-!.vale/styles/config
+.github/styles/*
+!.github/styles/config
 
 # Test binary, built with `go test -c`
 *.test
@@ -31,4 +31,4 @@ go.work
 dist/
 .tmp
 .fabric
-.fabric-lock.json
+.fabric-lock.json

docs/_index.md

@@ -1,17 +1,20 @@
 ---
 title: What is Fabric?
+description: Fabric is a user-friendly open-source command-line tool for reporting workflow automation. Fabric comes with a versatile template language and a rich ecosystem of plugins.
 menuName: Docs
 type: docs
 weight: 1
 ---
 
 # What's Fabric?
 
-Fabric is an open-source CLI tool and a configuration language that codifies and automation of the content generation process.
+Fabric is a user-friendly open-source command-line tool designed for reporting workflow automation. It comes with a versatile configuration language for reusable templates.
 
-Fabric Configuration Language (FCL) allows users to define the document data requirements and content structure with human-readable configuration files. The files can be version-controlled, reused, and shared.
+`fabric` CLI tool facilitates data collection from various sources and renders documents (reports, overviews, briefings, etc) from the templates in Fabric Configuration Language (FCL).
 
-`fabric` is a reports-as-code tool that renders templates defined in the FCL files into Markdown documents.
+[Fabric Configuration Language]({{< ref "language" >}}) offers a structured approach to defining data requirements and content structures. With its human-readable intuitive syntax and powerful features, FCL empowers users to create reusable modular templates.
+
+Together, Fabric CLI tool and FCL offer a comprehensive solution for organizations looking to formalize and streamline their content generation processes, enhancing their cyber-security and compliance efforts.
 
 ## Get started
 

docs/cli.md

@@ -1,5 +1,6 @@
 ---
 title: Fabric CLI
+description: Fabric CLI is your gateway to Fabric's powerful features. Use `fabric` binary with commands like `install`, `data`, and `render`. Dive deeper with `fabric --help` to explore additional options and commands. Get started with Fabric CLI and unlock seamless document generation.
 type: docs
 weight: 20
 ---
@@ -8,7 +9,7 @@ weight: 20
 
 The command line interface to Fabric is `fabric` CLI tool.
 
-The core sub-commands are:
+The core Fabric commands are:
 
 - `install` — installs all required plugins, listed in the [global configuration]({{< ref "language/configs.md#global-configuration" >}}). See [plugin installation docs]({{< ref "install.md#installing-plugins" >}}) for more details.
 - `data` — executes the data block and prints out prettified JSON to standard output.

docs/content-providers.md

@@ -1,5 +1,6 @@
 ---
-title: Content Providers
+title: Content providers
+description: Explore a wide array of content providers through Fabric plugins. These powerful integrations enable the rendering of document content locally or via external APIs, covering various types including text, tables, graphs, code, and more. Enhance your document generation capabilities with Fabric's versatile content provider plugins.
 type: docs
 weight: 58
 ---

docs/data-sources.md

@@ -1,5 +1,6 @@
 ---
-title: Data Sources
+title: Data sources
+description: Discover a diverse range of data sources within Fabric plugins. These integrations empower you to effortlessly load data from files, external services, APIs, and data storage systems. Simplify your data retrieval process and enhance your document generation workflow with Fabric's versatile data sources.
 type: docs
 weight: 52
 ---

docs/install.md

@@ -1,5 +1,6 @@
 ---
 title: Install
+description: Learn how to install Fabric and its plugins to streamline your templating workflow. Fabric binaries for Windows, macOS, and Linux are available at the project's GitHub releases page. Simply download the appropriate release archive for your operating system, unpack it, and you're ready to go.
 type: docs
 weight: 10
 code_blocks_no_wrap: true
@@ -36,7 +37,7 @@ tar -xvzf ./fabric_darwin_arm64.tar.gz -C ./fabric-bin
 
 ## Installing plugins
 
-Fabric relies on [the plugins]({{< ref "plugins.md" >}}) for implementing the integrations with various data sources, platforms, and services. Before the plugins can be used during the template rendering, they must be installed. Fabric's sub-command `install` can install the plugins automatically from the registry (`https://registry.blackstork.io`).
+Fabric uses [plugins]({{< ref "plugins.md" >}}) that implementing integrations with various data sources, platforms, and services. Before the plugins can be used during template rendering, they must be installed. Fabric's sub-command `install` can install the plugins automatically from the registry (`https://registry.blackstork.io`).
 
 To install the plugins:
 
@@ -53,7 +54,7 @@ To install the plugins:
 
 - **install the plugins**: run `install` sub-command to install the plugins. For example:
 
-  ```bash
+  ```text
   $ ./fabric install
   Mar 11 19:20:09.085 INF Searching plugin name=blackstork/elastic constraints=">=v0.0.1"
   Mar 11 19:20:09.522 INF Installing plugin name=blackstork/elastic version=0.4.0
@@ -62,7 +63,7 @@ To install the plugins:
   $
   ```
 
-The plugins are downloaded and installed in `./fabric` folder or in the location specified in `cache_dir` in [the global configuration]({{< ref "language/configs.md#global-configuration" >}}).
+The plugins are downloaded and installed in `./.fabric` folder or in the location specified in `cache_dir` in [the global configuration]({{< ref "language/configs.md#global-configuration" >}}).
 
 {{< hint note >}}
 

docs/language/_index.md

@@ -1,5 +1,6 @@
 ---
 title: Language
+description: Fabric Configuration Language (FCL) drives Fabric's document generation capabilities. With FCL, users define data needs and template structures in .fabric files, streamlining content creation. Automate document production efficiently with Fabric and FCL.
 type: docs
 weight: 40
 ---

docs/language/configs.md

@@ -1,5 +1,6 @@
 ---
 title: Configuration
+description: Learn how to configure Fabric, data sources and content providers.
 type: docs
 weight: 20
 ---

docs/language/content-blocks.md

@@ -1,5 +1,6 @@
 ---
 title: Content Blocks
+description: Learn how to use Fabric content blocks efficiently for building modular and reusable document templates.
 type: docs
 weight: 60
 ---
@@ -95,7 +96,7 @@ document "test-doc" {
 
     # The result of the query is stored in the `query_result` field in the context.
     # The context is available for the templating engine inside the `content.text` plugin.
-    text = "There are {{ .query_result }} items"
+    value = "There are {{ .query_result }} items"
   }
 
   content openai_text {

docs/language/data-blocks.md

@@ -1,5 +1,6 @@
 ---
 title: Data Blocks
+description: Learn how to use Fabric data blocks for defining data requirements for the templates.
 type: docs
 weight: 50
 ---

docs/language/documents.md

@@ -1,5 +1,6 @@
 ---
 title: Documents
+description: Learn how to use document blocks to define document templates, building a content structure with the content blocks and setting data requirements with the data blocks.
 type: docs
 weight: 40
 ---

docs/language/references.md

@@ -46,6 +46,8 @@ An anonymous `ref` block adopts a name of the referenced block. Since the final
 
 The `ref` block definition can include the attribute that would override the attributes provided in the original block. This is helpful if the block's behaviour needs adjustments per document.
 
+<!-- FIXME: https://github.com/blackstork-io/fabric/issues/29
+
 ## Query input requirement
 
 Content blocks rely on `query` attribute for selecting data needed for rendering (see content blocks' [Generic Arguments]({{< ref "content-blocks.md#generic-arguments" >}})). The JQ query uses the data path which is often document-specific and depends on the name of the data block. This hinders the re-usability of the content blocks.
@@ -68,8 +70,7 @@ content text "qux" {
   # Require the referrer to specify `query_input` query that will be used
   # to get the data for `query_input` field in the context
   query_input_required = true
-
-  text = "The data contains {{ .query_result }} elements"
+  value = "The data contains {{ .query_result }} elements"
 }
 
 document "test-document" {
@@ -99,3 +100,4 @@ document "test-document" {
 
 }
 ```
+-->

docs/language/section-blocks.md

@@ -1,5 +1,6 @@
 ---
 title: Section Blocks
+description: Learn how to use use section blocks to build modular and reusable content structures in your templates.
 type: docs
 weight: 70
 ---

docs/language/syntax.md

@@ -1,5 +1,6 @@
 ---
 title: Syntax
+description: Explore the syntax of Fabric Configuration Language (FCL). Built upon the foundation of HCL, FCL offers simplicity, readability, and clarity. Learn about arguments and blocks, the fundamental components for crafting configurations with FCL. Dive into examples and understand the expressive and modular nature of FCL configurations.
 type: docs
 weight: 10
 ---
@@ -16,7 +17,8 @@ The arguments play a crucial role in assigning values to names within a block. A
 
 ```hcl
 ... {
-    query_string = "kibana.alert.severity:critical"
+  index = ".alerts-security.alerts-default"
+  query_string = "kibana.alert.severity:critical"
 }
 ```
 
@@ -27,12 +29,15 @@ The argument name, `query_string` in the snippet above, is allowed to contain le
 In the Fabric Configuration Language (FCL), a block serves as a versatile container defining configurations, data requirements, or content structures. An example is provided below:
 
 ```hcl
-document "alerts_overview" {
+document "test_document" {
 
-    content text {
-        text = "Static text"
-    }
-    ...
+  data inline {
+    foo = 42
+  }
+
+  content text {
+    value = "My custom static text"
+  }
 
 }
 ```

docs/plugins/_index.md

@@ -1,20 +1,27 @@
 ---
 title: Plugins
+description: Discover the power of Fabric plugins, which implement various data sources and content providers to enhance your templating experience. Data sources enable loading data from files, external services, APIs, or data storage, while content providers render document content locally or via external APIs, supporting text, tables, graphs, code, and more.
 type: docs
-weight: 60
+weight: 50
 hideChildren: true
 ---
 
 # Plugins
 
-Fabric relies on plugins for implementing integrations with data sources and content providers. The global configuration should specify all required plugins (see [Global configuration]({{< ref "../language/configs.md/#global-configuration" >}}) for the details). Additionally, some data sources and content providers themselves require configuration (for example, API keys, URLs, credentials, etc).
+Fabric plugins implement various [data sources]({{< ref "data-sources.md" >}}) and [content providers]({{< ref "content-providers.md" >}}):
 
-A plugin name consists of a namespace (a name of a plugin vendor) and a short name. For example, `blackstork/elastic` plugin built by [BlackStork](https://blackstork.io) implements Elasticsearch and Elastic Security Cases data sources.
+- **data sources** are integrations responsible for loading data from the file, external service, API, or data storage.
+- **content providers** render the document content locally or through the external API (like LLM). The content types include text, tables, graphs, code and other elements.
 
-## Where to get the plugins
+## Dependencies
 
-Plugin releases are independent from Fabric releases. Plugins are distributed independently and have their own release cycle and version.
-You can find a list of plugins released by BlackStork at the [Releases page](https://github.com/blackstork-io/fabric/releases) in Fabric GitHub.
+The global configuration must include all required plugins (see [Global configuration]({{< ref "../language/configs.md/#global-configuration" >}})). A plugin name consists of a namespace (usually a vendor's name) and a short name. For example, [`blackstork/elastic`]({{< ref "./elastic/" >}}) plugin (built by BlackStork) implements [Elasticsearch data source]({{< ref "./elastic/data-sources/elasticsearch" >}}).
+
+## Installation
+
+Plugin releases are independent from Fabric releases and have their own release cycle and version. You can find a list of plugins released by BlackStork at the [Releases page](https://github.com/blackstork-io/fabric/releases) in Fabric GitHub repository.
+
+Required plugins can be downloaded and installed automatically with `fabric install` command. See [Installing plugins]({{< ref "../install.md#installing-plugins" >}}) for more details.
 
 ## Available plugins
 

docs/tutorial.md

@@ -1,5 +1,6 @@
 ---
 title: Tutorial
+description: Dive into Fabric tutorial to learn everything you need to know about using Fabric effectively. From the basics of FCL commands to advanced features such as data configurations, our tutorial provides clear, step-by-step instructions for building Fabric templates. Start improving your workflow with Fabric today.
 type: docs
 weight: 30
 code_blocks_no_wrap: true
@@ -28,7 +29,7 @@ Create a new `hello.fabric` file and define a simple template:
 document "greeting" {
 
   content text {
-    text = "Hello, Fabric!"
+    value = "Hello, Fabric!"
   }
 
 }
@@ -61,19 +62,18 @@ document "greeting" {
   title = "The Greeting"
 
   content text {
-    text = "Hello, Fabric!"
+    value = "Hello, Fabric!"
   }
 
 }
 ```
 
 {{< hint note >}}
-`title` argument for `document` block is a syntactic sugar that Fabric translates into `content.text` block with `format_as` attribute set to `title`:
+`title` argument for `document` block is a syntactic sugar that Fabric translates into `content.title` block:
 
 ```hcl
-content text {
-  text = "The Greeting"
-  format_as = "title"
+content title {
+  value = "The Greeting"
 }
 ```
 
@@ -111,13 +111,13 @@ document "greeting" {
   title = "The Greeting"
 
   content text {
-    text = "Hello, Fabric!"
+    value = "Hello, Fabric!"
   }
 
   content text {
     query = ".data.inline.solar_system.planets | length"
 
-    text = <<-EOT
+    value = <<-EOT
       There are {{ .query_result }} planets and {{ .data.inline.solar_system.moons_count }} moons in our solar system.
     EOT
   }
@@ -174,13 +174,13 @@ document "greeting" {
   title = "The Greeting"
 
   content text {
-    text = "Hello, Fabric!"
+    value = "Hello, Fabric!"
   }
 
   content text {
     query = ".data.inline.solar_system.planets | length"
 
-    text = <<-EOT
+    value = <<-EOT
       There are {{ .query_result }} planets and {{ .data.inline.solar_system.moons_count }} moons in our solar system.
     EOT
   }
@@ -266,13 +266,13 @@ document "greeting" {
   title = "The Greeting"
 
   content text {
-    text = "Hello, Fabric!"
+    value = "Hello, Fabric!"
   }
 
   content text {
     query = ".data.inline.solar_system.planets | length"
 
-    text = <<-EOT
+    value = <<-EOT
       There are {{ .query_result }} planets and {{ .data.inline.solar_system.moons_count }} moons in our solar system.
     EOT
   }