More docs (#94)

.github/styles/.vale-config/1-Hugo.ini

@@ -0,0 +1,10 @@
+[*.md]
+# Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}})
+TokenIgnores = ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \
+(\[.+\]\({{< .+ >}}\)), \
+({{[%<] .+ [%>]}})
+
+# Exclude `{{<  myshortcode `This is some <b>HTML</b>, ... >}}`
+BlockIgnores = (?sm)^({{[%<] [^{]*? [%>]}})\n$, \
+(?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}), \
+({{[%<] .+ [%>]}})

.github/styles/.vale-config/2-Hugo.ini

@@ -0,0 +1,10 @@
+[*.md]
+# Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}})
+TokenIgnores = ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \
+(\[.+\]\({{< .+ >}}\)), \
+({{[%<] .+ [%>]}})
+
+# Exclude `{{<  myshortcode `This is some <b>HTML</b>, ... >}}`
+BlockIgnores = (?sm)^({{[%<] [^{]*? [%>]}})\n$, \
+(?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}), \
+({{[%<] .+ [%>]}})

.github/styles/config/vocabularies/fabric-vocab/accept.txt

@@ -0,0 +1,3 @@
+GitHub
+Fabric
+boolean

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '**.md'
+  pull_request:
+    paths:
+      - '**.md'
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  # https://github.com/igorshubovych/markdownlint-cli
+  markdownlint-cli:
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: nosborn/[email protected]
+        with:
+          files: '**/*.md'
+          config_file: .markdownlint.yaml
+          dot: true
+
+  # https://github.com/errata-ai/vale-action
+  vale:
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: errata-ai/vale-action@reviewdog
+        with:
+          fail_on_error: true
+          vale_flags: "--glob='**/*.md'"
+

.github/workflows/main.yml

@@ -7,10 +7,8 @@ on:
   pull_request:
   workflow_dispatch:
 
-    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
-
 concurrency:
-  group: ${{ github.head_ref || github.run_id }}
+  group: main-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
 jobs:
@@ -56,14 +54,3 @@ jobs:
         uses: golangci/golangci-lint-action@v3
         with:
           version: v1.55.2
-
-  markdownlint-cli:
-    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: nosborn/[email protected]
-        with:
-          files: docs/
-          config_file: .markdownlint.yaml
-          dot: true

.gitignore

@@ -11,6 +11,12 @@ bin/*
 *.so
 *.dylib
 
+.DS_Store
+
+# Vale will install modules in `.vale/style` and those should not be in version control
+.vale/styles/*
+!.vale/styles/config
+
 # Test binary, built with `go test -c`
 *.test
 

.vale.ini

@@ -0,0 +1,15 @@
+MinAlertLevel = suggestion
+Packages = Microsoft, Hugo
+StylesPath = .github/styles
+Vocab = fabric-vocab
+
+[*.md]
+BasedOnStyles = Vale, Microsoft
+
+# Style.Rule = {YES, NO, suggestion, warning, error} to
+
+# Disable a requirement of no spaces around dashes
+Microsoft.Dashes = NO
+
+# Allow CLI in the headings
+Microsoft.HeadingAcronyms = NO

README.md

@@ -1,37 +1,80 @@
 <div align="center">
 
-<img src=".assets/fabric.svg" alt="fabric-logo" width="250px"/>
+<img src=".assets/fabric.svg" alt="Fabric logo" width="250px"/>
 <br/>
 <br/>
 
 Codifying and automating mission-critical communications with standardized and reusable templates.
 
-#### [Releases](https://github.com/blackstork-io/fabric/releases) | [Docs](https://blackstork.io/fabric/docs/) | [Use Cases](https://blackstork.io/fabric/docs/use-cases/) | [Slack](https://fabric-community.slack.com/)
+[Releases](https://github.com/blackstork-io/fabric/releases) | [Docs](https://blackstork.io/fabric/docs/) | [Slack](https://fabric-community.slack.com/)
 
-![GitHub Repo stars](https://img.shields.io/github/stars/blackstork-io/fabric?style=social)
+![GitHub Repository stars](https://img.shields.io/github/stars/blackstork-io/fabric?style=social)
 ![GitHub Release](https://img.shields.io/github/v/release/blackstork-io/fabric)
 [![Join Slack](https://img.shields.io/badge/slack-join-8F87F7)](https://fabric-community.slack.com/)
 
 </div>
 
 > [!NOTE]  
-> Fabric is currently in the early stages of development, and there may be some issues. We welcome your feedback, so if you have any suggestions, ideas, or encounter bugs, please share them with us in our [Slack](https://fabric-community.slack.com/).
+> Fabric is currently in the early stages of development, and there may be some issues. If you have any suggestions, ideas, or encounter bugs, please share them in [Fabric Community slack](https://fabric-community.slack.com/).
 
-Fabric is an open-source configuration language and a CLI tool that enables the codification and automation of the content generation process.
+Fabric is an open-source CLI tool and a configuration language that codifies and automation of the content generation process.
 
 <div align="center">
-    <img src=".assets/diagram.svg" alt="fabric-diagram" width="600px"/>
+    <img src=".assets/diagram.svg" alt="The diagram shows a sketch of a Fabric template and rendered document" width="600px"/>
 </div>
 
-Fabric produces rich Markdown documents from the template files that declaratively define data requirements and content structure. The templates consist of reusable blocks powered by plugins. Fabric fetches data from various external data stores, security solutions, and platforms using a collection of integrations and renders the Markdown document through a set of content blocks. Since the output file is just a Markdown document, it can be quickly rendered into PDF / HTML using any 3rd party renderer.
+Fabric produces Markdown documents from the templates that define data requirements and content structure. The templates are written in Fabric Configuration Language and consist of reusable blocks, powered by plugins.
+Data blocks fetch data from various external sources -- data stores, security solutions, and platforms. The content blocks render the template into a Markdown document.
+
+See [Documentation](https://blackstork.io/fabric/docs/) for more details on the Fabric language and Fabric CLI.
 
 # Installation
 
-[TBD]
+To get started with Fabric, follow these simple steps for installation across various operating systems:
+
+- **download release archives**: choose and download the appropriate release for your operating system (Windows, macOS, or Linux) and architecture (32-bit or 64-bit) in ["Releases" section](https://github.com/blackstork-io/fabric/releases);
+- **unpack the archives**: extract the contents of the downloaded archive to a preferred directory;
+- **run the binary**: run `fabric` binary from the command line to launch Fabric.
+
+That's it! You're now ready to use Fabric. For more details on usage and configuration options, refer to the "Usage" paragraph below or [Fabric CLI](https://blackstork.io/fabric/docs/cli) documentation.
+
+
 
 # Usage
 
-[TBD]
+The command line interface to Fabric is `fabric` CLI tool. It supports two sub-commands:
+
+- `fabric data` — executes the data block and prints out prettified JSON to standard output.
+- `fabric render` — renders the specified target (a document template) into Markdown and outputs the result to standard output or to a file.
+
+```bash
+$ fabric --help
+
+Usage:
+  fabric [command]
+
+Available Commands:
+  completion  Generate the autocompletion script for the specified shell
+  data        Execute a single data block
+  help        Help about any command
+  render      Render the document
+
+Flags:
+      --color                enables colorizing the logs and diagnostics (if supported by the terminal and log format) (default true)
+  -h, --help                 help for fabric
+      --log-format string    format of the logs (plain or json) (default "plain")
+      --log-level string     logging level ('debug', 'info', 'warn', 'error') (default "info")
+      --plugins-dir string   override for plugins dir from fabric configuration
+      --source-dir string    a path to a directory with *.fabric files (default ".")
+  -v, --verbose              a shortcut to --log-level debug
+      --version              version for fabric
+
+Use "fabric [command] --help" for more information about a command.
+```
+
+## Source directory
+
+Fabric loads `*.fabric` files from a source directory. By default, the current directory (`.`) is a source directory. If you wish to specify a different location, use `--source-dir` argument when running `fabric`.
 
 # Documentation
 
@@ -41,7 +84,7 @@ Visit [https://blackstork.io/fabric/docs/](https://blackstork.io/fabric/docs/) f
 
 Please report any suspected security vulnerabilities through GitHub's [security advisory reporting](https://github.com/blackstork-io/fabric/security/advisories/new). We take all legitimate reports seriously and will thoroughly investigate.
 
-We kindly request that you talk to us before making any public disclosures. This ensures that no excessive information is revealed before a patch is ready and users have sufficient time to upgrade.
+We kindly request that you talk to us before making any public disclosures. This ensures that no excessive information is revealed before a patch is ready and users have enough time to upgrade.
 
 # License
 

docs/_index.md

@@ -2,15 +2,18 @@
 title: What is Fabric?
 menuName: Docs
 type: docs
-menus: main
 weight: 1
 ---
 
-# What is Fabric?
+# What's 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.
+Fabric is an open-source CLI tool and a configuration language that codifies and automation of the content generation process.
 
-## Get Started
+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` is a reports-as-code tool that renders templates defined in the FCL files into Markdown documents.
+
+## Get started
 
 - [Install]({{< ref "install.md" >}}) — how to install and run Fabric.
 - [Language]({{< ref "language.md" >}}) — Fabric Configuration Language details and main concepts.

docs/cli.md

@@ -6,4 +6,37 @@ weight: 4
 
 # Fabric CLI
 
-[TBD]
+The command line interface to Fabric is `fabric` CLI tool. It supports two sub-commands:
+
+- `fabric data` — executes the data block and prints out prettified JSON to standard output
+- `fabric render` — renders the specified target (a document template) into Markdown and outputs the result to standard output or to a file.
+
+```text
+$ fabric --help
+
+Usage:
+  fabric [command]
+
+Available Commands:
+  completion  Generate the autocompletion script for the specified shell
+  data        Execute a single data block
+  help        Help about any command
+  render      Render the document
+
+Flags:
+      --color                enables colorizing the logs and diagnostics (if supported by the terminal
+                             and log format) (default true)
+  -h, --help                 help for fabric
+      --log-format string    format of the logs (plain or json) (default "plain")
+      --log-level string     logging level ('debug', 'info', 'warn', 'error') (default "info")
+      --plugins-dir string   override for plugins dir from fabric configuration
+      --source-dir string    a path to a directory with *.fabric files (default ".")
+  -v, --verbose              a shortcut to --log-level debug
+      --version              version for fabric
+
+Use "fabric [command] --help" for more information about a command.
+```
+
+## Source directory
+
+Fabric loads `*.fabric` files from a source directory. By default, a source directory is the current directory  (`.`). To load Fabric files from a different location, set `--source-dir` argument when running `fabric`.

docs/install.md

@@ -6,4 +6,21 @@ weight: 2
 
 # Install
 
-[TBD]
+## GitHub releases
+
+The archives of compiled binaries for Fabric are available for Windows, macOS, and Linux at the project's ["Releases"](https://github.com/blackstork-io/fabric/releases) page.
+
+To get started with Fabric:
+
+- **download release archives**: choose and download the appropriate release for your operating system (Windows, macOS/Darwin, or Linux) and architecture in ["Releases" section](https://github.com/blackstork-io/fabric/releases);
+- **unpack the archives**: extract the contents of the downloaded archive to a preferred directory;
+
+For example, on macOS you can do:
+
+```bash
+wget https://github.com/blackstork-io/fabric/releases/download/v0.3.0/vale_0.3.0_Linux_64-bit.tar.gz
+mkdir fabric && tar -xvzf vale_2.28.0_Linux_64-bit.tar.gz -C bin
+export PATH=./bin:"$PATH"
+```
+
+That's it! You're now ready to use Fabric. For more details on usage and configuration options, refer [Fabric CLI]({{< ref "cli.md" >}}) documentation.

docs/language/_index.md

@@ -4,21 +4,21 @@ type: docs
 weight: 2
 ---
 
-# Fabric Configuration Language
+# Fabric configuration language
 
 Fabric Configuration Language (FCL) serves as the core feature for Fabric — a powerful tool designed to streamline document generation. FCL enables users to express data requirements and template structures within configuration files with lightweight syntax.
 
 The document templates defined in the configuration files act as blueprints for data consolidation and creation of Markdown documents.
 
 FCL empowers users to define, manage, and automate the document production process, delivering a sturdy and adaptable solution for content generation.
 
-Fabric configuration files have extension `.fabric` and contain configurations, data requirements and content definitions. Fabric configuration codebase can consist of multiple files and sub-directories.
+Fabric configuration files have extension `.fabric` and contain configurations, data requirements and content definitions. Fabric configuration codebase can consist of many files and sub-directories.
 
-## Core Concepts
+## Core concepts
 
-Similar to [Terraform Configuration Language](https://developer.hashicorp.com/terraform/language), FCL is based on [HCL syntax](https://github.com/hashicorp/hcl), that consists of two core elements:
+Similar to [Terraform Configuration Language](https://developer.hashicorp.com/terraform/language), Fabric language builds upon [HashiCorp Configuration Language](https://github.com/hashicorp/hcl) (HCL), and consists of two core elements:
 
-- **Blocks** are containers that define an object, like a configuration, a data requirement or a content structure. Blocks always have a block type, zero or more labels, and can be named or anonymous.
+- **Blocks** are containers that define an object, like a configuration, a data requirement or a content structure. Blocks always have a block type and zero or more labels.
 - **Arguments** assign a value to a name inside a blocks.
 
 ```hcl
@@ -49,10 +49,10 @@ config data elasticsearch {
 
 See [Syntax](./syntax/) for more details on the FCL syntax.
 
-## IDE Support
+## IDE support
 
-Since Fabric configuration language is based on HCL, IDE extensions for HCL syntax highlighting will work with Fabric files out of the box.
+Since Fabric configuration language builds on HCL, IDE extensions for HCL syntax highlighting will work with Fabric files as well. You might need to explicitly set a file type for `*.fabric` files to HCL.
 
-If you are using Microsoft VSCode, take a look at [Fabric Extension for Visual Studio Code](https://github.com/blackstork-io/vscode-fabric).
+If you are using Microsoft Visual Studio Code, take a look at [Fabric Extension for Visual Studio Code](https://github.com/blackstork-io/vscode-fabric).
 
-![VSCode Fabric Extension screenshot](./vscode-fabric-screenshot.png)
+![A screenshot of Fabric Extension for Visual Studio Code](./vscode-fabric-screenshot.png)