diff --git a/.assets/diagram.svg b/.assets/diagram.svg deleted file mode 100644 index 80706929..00000000 --- a/.assets/diagram.svg +++ /dev/null @@ -1,107 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/.github/diagram.png b/.github/diagram.png new file mode 100644 index 00000000..13713480 Binary files /dev/null and b/.github/diagram.png differ diff --git a/.assets/fabric.svg b/.github/fabric.svg similarity index 100% rename from .assets/fabric.svg rename to .github/fabric.svg diff --git a/.github/styles/config/vocabularies/fabric-vocab/accept.txt b/.github/styles/config/vocabularies/fabric-vocab/accept.txt index 75d5e680..4979bbae 100644 --- a/.github/styles/config/vocabularies/fabric-vocab/accept.txt +++ b/.github/styles/config/vocabularies/fabric-vocab/accept.txt @@ -1,4 +1,8 @@ -GitHub Fabric +GitHub boolean namespace +Sonoma +API +LLM +Splunk diff --git a/README.md b/README.md index a727af7d..f89d879e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@
-Fabric logo +Fabric logo

@@ -14,39 +14,102 @@ Codifying and automating mission-critical communications with standardized and r
-> [!NOTE] -> 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 CLI tool and a configuration language that codifies and automates content generation. +**Fabric** is an open-source Command Line Interface (CLI) tool coupled with a configuration language designed to encode and automate content generation for cyber-security and compliance.
- The diagram shows a sketch of a Fabric template and rendered document + The diagram illustrates a Fabric template and the corresponding rendered document
-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. +Fabric generates documents based on modular templates written in [Fabric Configuration Language](https://blackstork.io/fabric/docs/language/) (FCL). Template authors can delineate data requirements and content structures within the template, significantly reducing the manual effort associated with data consolidation and improving re-usability. + +The plugin ecosystem expands Fabric's capabilities by offering integrations with various platforms, data stores, and security solutions, including [JSON/CSV files](https://blackstork.io/fabric/docs/plugins/builtin/), [Elastic](https://blackstork.io/fabric/docs/plugins/elastic/), [OpenCTI](https://blackstork.io/fabric/docs/plugins/opencti/), [Splunk Cloud](https://blackstork.io/fabric/docs/plugins/splunk/), [GitHub](https://blackstork.io/fabric/docs/plugins/github/), and more. A comprehensive list of supported plugins is available in [the documentation](https://blackstork.io/fabric/docs/plugins/). + +To facilitate flexible content generation, Fabric content providers leverage powerful [Go templates](https://pkg.go.dev/text/template) and incorporate capabilities such as generative AI/LLMs (OpenAI API, Azure OpenAI, etc). -See [Documentation](https://blackstork.io/fabric/docs/) for more details on the Fabric language and Fabric CLI. +Refer to [the documentation](https://blackstork.io/fabric/docs/) for in-depth details about Fabric. + +> [!NOTE] +> Fabric is currently in the early stages of development, and there may be some issues. If you have any suggestions, ideas, or bug reports, please share them in [Fabric Community slack](https://fabric-community.slack.com/). # Installation -To get started with Fabric, follow these simple steps for installation across various operating systems: +## Installing Fabric + +Fabric binaries for Windows, macOS, and Linux are available at ["Releases"](https://github.com/blackstork-io/fabric/releases) page in the project's GitHub. + +To install Fabric: + +- **download a release archive**: choose and download Fabric release archive appropriate for your operating system (Windows, macOS/Darwin, or Linux) and architecture from ["Releases"](https://github.com/blackstork-io/fabric/releases) page; +- **unpack**: extract the contents of the downloaded release archive into a preferred directory. + +For example, the steps for macOS (arm64) are: + +```bash +# Create a folder +mkdir fabric-bin + +# Download the latest release of Fabric +wget https://github.com/blackstork-io/fabric/releases/latest/download/fabric_darwin_arm64.tar.gz \ + -O ./fabric_darwin_arm64.tar.gz + +# Unpack Fabric release archive into `fabric-bin` folder +tar -xvzf ./fabric_darwin_arm64.tar.gz -C ./fabric-bin + +# Verify that `fabric` runs +./fabric-bin/fabric --help +``` -- **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 archives to a preferred directory; +## Installing Fabric plugins -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. +Fabric relies on [the plugins](https://blackstork.io/fabric/docs/plugins/) 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. + +To install the plugins: + +- **add all necessary plugins into the global configuration**: [the global configuration](https://blackstork.io/fabric/docs/language/configs/#global-configuration) has a list of plugins dependencies in `plugin_versions` map. Add the plugins you would like to install in the map with a preferred version constraint. + + ```hcl + fabric { + plugin_versions = { + "blackstork/openai" = ">= 0.0.1", + "blackstork/elastic" = ">= 0.0.1", + } + } + ``` + +- **install the plugins**: run `install` sub-command to install the plugins. For example: + + ```bash + $ ./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 + Mar 11 19:20:10.769 INF Searching plugin name=blackstork/openai constraints=">=v0.0.1" + Mar 11 19:20:10.787 INF Installing plugin name=blackstork/openai version=0.4.0 + $ + ``` + +The plugins are downloaded and installed in `./fabric` folder. + +{{< hint note >}} + +> [!NOTE] +> It's not necessary to install any plugins if you are only using built-in [data sources](https://blackstork.io/fabric/docs/plugins/builtin/#data-sources) and [content providers](https://blackstork.io/fabric/docs/plugins/builtin/#content-providers) in your templates # Usage -The command line interface to Fabric is `fabric` CLI tool. It supports two sub-commands: +The command line interface to Fabric is `fabric` CLI tool. + +The core sub-commands are: +- `install` — installs all required plugins. - `data` — executes the data block and prints out prettified JSON to standard output. -- `render` — renders the specified target (a document template) into Markdown and outputs the result to standard output or to a file. +- `render` — renders the specified target (a document template) and prints out the result to standard output or to a file. -```text -$ fabric --help +To get more details, run `fabric --help`: +```text +$ ./fabric --help Usage: fabric [command] @@ -54,24 +117,22 @@ Available Commands: completion Generate the autocompletion script for the specified shell data Execute a single data block help Help about any command + install Install plugins 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 + --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") + --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`. +# Templates You can find a collection of free Fabric templates in [Fabric Templates](https://github.com/blackstork-io/fabric-templates) repository. @@ -81,9 +142,9 @@ Visit [https://blackstork.io/fabric/docs/](https://blackstork.io/fabric/docs/) f # Security -Please report any suspected security vulnerabilities through GitHub's [security advisory reporting](https://github.com/blackstork-io/fabric/security/advisories/new). We treat every report with utmost seriousness and will conduct a comprehensive investigation. +If you suspect any security vulnerabilities within Fabric, please promptly report them using GitHub's [security advisory reporting](https://github.com/blackstork-io/fabric/security/advisories/new). Every report is treated with the utmost seriousness, and we commit to conducting a thorough investigation. -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. +We kindly request that you engage in a conversation with us before making any public disclosures. This precautionary step ensures that no excessive information is divulged prematurely, allowing us to prepare a patch. Additionally, it provides users with enough time to upgrade and enhance their system security. # License diff --git a/docs/_index.md b/docs/_index.md index c0461b79..a0569ad1 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -16,6 +16,9 @@ Fabric Configuration Language (FCL) allows users to define the document data req ## Get started - [Install]({{< ref "install.md" >}}) — how to install and run Fabric. -- [Language]({{< ref "language.md" >}}) — Fabric Configuration Language details and main concepts. - [Fabric CLI]({{< ref "cli.md" >}}) — Fabric CLI usage details. +- [Tutorial]({{< ref "tutorial.md" >}}) — an extensive tutorial for starting with Fabric. +- [Language]({{< ref "language.md" >}}) — Fabric Configuration Language details and main concepts. +- [Data Sources]({{< ref "data-sources.md" >}}) — the data sources supported. +- [Content Providers]({{< ref "content-providers.md" >}}) — the content providers supported. - [Plugins]({{< ref "plugins.md" >}}) — the documentation for the plugins Fabric supports. diff --git a/docs/cli.md b/docs/cli.md index eb4a7501..4a117f1a 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,19 +1,23 @@ --- title: Fabric CLI type: docs -weight: 4 +weight: 20 --- # Fabric CLI -The command line interface to Fabric is `fabric` CLI tool. It supports two sub-commands: +The command line interface to Fabric is `fabric` CLI tool. -- `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. +The core sub-commands are: -```text -$ fabric --help +- `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. +- `render` — renders the specified target (a document template) and prints out the result to standard output or to a file. + +To get more details, run `fabric --help`: +```text +$ ./fabric --help Usage: fabric [command] @@ -21,22 +25,25 @@ Available Commands: completion Generate the autocompletion script for the specified shell data Execute a single data block help Help about any command + install Install plugins 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 + --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") + --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`. +Fabric loads `*.fabric` files from a source directory. By default, a source directory is the current directory (`.`) but it's possible to set `--source-dir` argument when running `fabric` to load files from a different location. + +## Next step + +Take a look at [the tutorial]({{< ref "tutorial.md" >}}) to see the commands in action. diff --git a/docs/content-providers.md b/docs/content-providers.md new file mode 100644 index 00000000..1c851f42 --- /dev/null +++ b/docs/content-providers.md @@ -0,0 +1,9 @@ +--- +title: Content Providers +type: docs +weight: 58 +--- + +# Content providers + +{{< plugin-resources "" "content-provider" >}} diff --git a/docs/data-sources.md b/docs/data-sources.md new file mode 100644 index 00000000..3d0244ba --- /dev/null +++ b/docs/data-sources.md @@ -0,0 +1,9 @@ +--- +title: Data Sources +type: docs +weight: 52 +--- + +# Data sources + +{{< plugin-resources "" "data-source" >}} diff --git a/docs/install.md b/docs/install.md index eb2d9441..30a5568c 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,19 +1,22 @@ --- title: Install type: docs -weight: 2 +weight: 10 +code_blocks_no_wrap: true --- # Install -## GitHub releases +## Installing Fabric -The archives of compiled binaries for Fabric and Fabric plugins are available for Windows, macOS, and Linux at the project's ["Releases"](https://github.com/blackstork-io/fabric/releases) page. +### GitHub releases -To get started with Fabric: +Fabric binaries for Windows, macOS, and Linux are available at ["Releases"](https://github.com/blackstork-io/fabric/releases) page in the project's GitHub. -- **download release archives**: choose and download the appropriate Fabric and Fabric plugin releases for your operating system (Windows, macOS/Darwin, or Linux) and architecture from ["Releases" section](https://github.com/blackstork-io/fabric/releases); -- **unpack the archives**: extract the contents of the downloaded archives to a preferred directory; +To install Fabric: + +- **download a release archive**: choose and download Fabric release archive appropriate for your operating system (Windows, macOS/Darwin, or Linux) and architecture from ["Releases"](https://github.com/blackstork-io/fabric/releases) page; +- **unpack**: extract the contents of the downloaded release archive into a preferred directory; For example, the steps for macOS (arm64) are: @@ -24,17 +27,49 @@ mkdir fabric-bin # Download the latest release of Fabric wget https://github.com/blackstork-io/fabric/releases/latest/download/fabric_darwin_arm64.tar.gz -O ./fabric_darwin_arm64.tar.gz -# Download the latest release of Fabric plugins -wget https://github.com/blackstork-io/fabric/releases/latest/download/plugins_darwin_arm64.tar.gz -O ./plugins_darwin_arm64.tar.gz - # Unpack Fabric release archive into `fabric-bin` folder tar -xvzf ./fabric_darwin_arm64.tar.gz -C ./fabric-bin -# Unpack Fabric plugins release archive into `fabric-bin` folder -tar -xvzf ./plugins_darwin_arm64.tar.gz -C ./fabric-bin - # Verify that `fabric` runs ./fabric-bin/fabric --help ``` -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. +## 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`). + +To install the plugins: + +- **add all necessary plugins into the global configuration**: [the global configuration]({{< ref "language/configs.md#global-configuration" >}}) has a list of plugins dependencies in `plugin_versions` map. Add the plugins you would like to install in the map with a preferred version constraint. + + ```hcl + fabric { + plugin_versions = { + "blackstork/openai" = ">= 0.0.1", + "blackstork/elastic" = ">= 0.0.1", + } + } + ``` + +- **install the plugins**: run `install` sub-command to install the plugins. For example: + + ```bash + $ ./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 + Mar 11 19:20:10.769 INF Searching plugin name=blackstork/openai constraints=">=v0.0.1" + Mar 11 19:20:10.787 INF Installing plugin name=blackstork/openai version=0.4.0 + $ + ``` + +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 >}} + +It's not necessary to install any plugins if you are only using built-in [data sources]({{< ref "plugins/builtin/_index.md#data-sources" >}}) and [content providers]({{< ref "plugins/builtin/_index.md#content-providers" >}}) in your templates + +{{}} + +## Next step + +That's it! You're now ready to use Fabric. Take a look at [the tutorial]({{< ref "tutorial.md" >}}) to see how to create and render the templates. diff --git a/docs/language/_index.md b/docs/language/_index.md index 6a1c9752..4af0b262 100644 --- a/docs/language/_index.md +++ b/docs/language/_index.md @@ -1,25 +1,23 @@ --- title: Language type: docs -weight: 2 +weight: 40 --- # 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. +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 using a lightweight syntax. -The document templates defined in the configuration files act as blueprints for data consolidation and creation of Markdown documents. +The document templates, defined in the configuration files, act as blueprints for consolidating data and creating Markdown documents. FCL empowers users to define, manage, and automate the document production process, delivering a sturdy and adaptable solution for content generation. -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 many files and sub-directories. +Fabric configuration files have the extension `.fabric` and contain configurations, data requirements, and content definitions. The Fabric configuration codebase may consist of many files and subdirectories. ## Core concepts -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: +Building upon the [HashiCorp Configuration Language](https://github.com/hashicorp/hcl) (HCL), Fabric language shares similarities with the [Terraform Configuration Language](https://developer.hashicorp.com/terraform/language) and comprises two fundamental elements: -- **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. +- **Blocks**: serve as containers defining objects, such as configurations, data requirements, or content structures. Blocks always include a block type and may have zero or more labels. +- **Arguments** assign values to names within blocks, facilitating the configuration process. ```hcl # Named data block: @@ -33,15 +31,12 @@ data elasticsearch "alerts" { = } - # Anonymous configuration block for a data plugin: - config data elasticsearch { cloud_id = "my-elastic-cloud-id" api_key = "my-elastic-cloud-api-key" } - { = } @@ -51,8 +46,8 @@ See [Syntax](./syntax/) for more details on the FCL syntax. ## IDE support -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. +Given that Fabric configuration language is built on HCL, IDE extensions designed for HCL syntax highlighting are applicable to Fabric files. It may be necessary to explicitly set the file type for `*.fabric` files to HCL. -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). +For users of Microsoft Visual Studio Code, there is a dedicated [Fabric Extension for Visual Studio Code](https://github.com/blackstork-io/vscode-fabric) available, providing enhanced support for Fabric configurations within the IDE. ![A screenshot of Fabric Extension for Visual Studio Code](./vscode-fabric-screenshot.png) diff --git a/docs/language/configs.md b/docs/language/configs.md index c3351b02..53e6b4f8 100644 --- a/docs/language/configs.md +++ b/docs/language/configs.md @@ -8,7 +8,7 @@ weight: 20 ## Global configuration -The `fabric` configuration block defines a global configuration for Fabric. It's used for defining plugin dependencies, the paths to local directories, etc. +The `fabric` configuration block serves as the global configuration for Fabric, offering a centralized space for defining essential aspects such as plugin dependencies and local directory paths. ```hcl fabric { @@ -16,24 +16,26 @@ fabric { } ``` -There can be only one `fabric` block defined within the codebase. +Within the codebase, only one `fabric` block can be defined. ### Supported arguments -- `plugin_versions`: (required) a map that matches name-spaced plugin names to the version constraints in SemVer (see Terraform [version constraint syntax](https://developer.hashicorp.com/terraform/language/expressions/version-constraints#version-constraint-syntax)). -- `cache_dir`: (optional) a path to a directory on the local file system. The default value is `.fabric` directory in the current folder. If the directory doesn't exist, Fabric will create it on the first run. +- `plugin_versions`: (required) a map that aligns namespaced plugin names with version constraints in SemVer (refer to Terraform [version constraint syntax](https://developer.hashicorp.com/terraform/language/expressions/version-constraints#version-constraint-syntax)). +- `cache_dir`: (optional) a path to a directory on the local file system. The default value is `.fabric` directory in the current folder. If the directory doesn't exist, Fabric creates it upon the first run. ### Supported nested blocks -- `plugin_registry` – (optional) a block that defines available plugin registries. At the moment, the block accepts only one attribute: +- `plugin_registry`: (optional) a block defines available plugin registries and can include the following arguments: ```hcl plugin_registry { + base_url = "" mirror_dir = "" } ``` - - `mirror_dir` – (optional) a path to a directory on the local filesystem with plugin binaries. + - `base_url`: (optional) the base URL of the plugin registry. Default value: `https://registry.blackstork.io` + - `mirror_dir`: (optional) the path to a directory on the local filesystem containing plugin binaries. ### Example @@ -47,7 +49,7 @@ fabric { } plugin_versions = { - "blackstork/elasticsearch" = "1.2.3" + "blackstork/elastic" = "1.2.3" "blackstork/openai" = "=11.22.33" } } @@ -57,9 +59,9 @@ fabric { A Fabric plugin can include one or more data sources. For example, `blackstork/github` plugin includes `github_issues` data source. -A data source loads data from a local or an external data store, platform, and service. +A data source within Fabric serves the purpose of loading data from either a local or an external data store, platform, or service. -Data sources are configured using `config` block: +Configuration for data sources is accomplished through the use of the `config` block: ```hcl config data "" { @@ -148,3 +150,7 @@ document "test-document" { } } ``` + +## Next steps + +See [Documents]({{< ref "documents.md" >}}) to learn how to build document templates in Fabric configuration language. diff --git a/docs/language/content-blocks.md b/docs/language/content-blocks.md index 3888f2df..8c6bca35 100644 --- a/docs/language/content-blocks.md +++ b/docs/language/content-blocks.md @@ -6,21 +6,22 @@ weight: 60 # Content blocks -`content` blocks define document segments: text paragraphs, tables, graphs, lists, etc. The order of the `content` blocks in the template determines the order of the generated content in the document. +`content` blocks define document segments: text paragraphs, tables, graphs, lists, etc. The block signature includes the name of the content provider that will execute the content block. Fabric supports many [content pproviders]({{< ref "content-providers.md" >}}) through its [plugin ecosystem]({{< ref "plugins.md" >}}). ```hcl -# Root-level definition of the content block +# Root-level definition of a content block content "" { ... } document "foobar" { - # In-document definition of the content block + # In-document named definition of a content block content "" { ... } + # In-document anonymous definition of a content block content { ... } @@ -28,11 +29,13 @@ document "foobar" { } ``` -If the block is defined at the root level of the file, outside of the `document` block, both names – the content provider name and the block name – are required. A combination of block type `content`, content provider name, and block name serves as a unique identifier of a block within the codebase. +The order of the `content` blocks in the template determines the order of the generated content in the document. + +If the block is placed at the root level of the file, outside of the `document` block, both names – the content provider name and the block name – are required. A combination of block type `content`, content provider name, and block name serves as a unique identifier of a block within the codebase. If the content block is defined within the document template, only a content provider name is required and a block name is optional. -A content block is rendered by a specified content provider. See [Plugins]({{< ref "plugins.md" >}}) for the list of the content providers supported by Fabric. +A content block is rendered by a specified content provider. See [Content Providers]({{< ref "content-providers.md" >}}) for the list of the content providers supported by Fabric. ## Supported arguments @@ -51,19 +54,21 @@ The arguments provided in the block are either generic arguments or plugin-speci Content provider specific are defined by a plugin specification. See [Plugins]({{< ref "plugins.md" >}}) for the details on the supported arguments per plugin. +Content provider arguments differ per content provider. See the documentation for a specific content provider (find it in [supported content providers]({{< ref "content-providers.md" >}})) for the details on the supported arguments. + ## Supported nested blocks - `meta`: (optional) a block containing metadata for the block. -- `config`: (optional) an inline configuration for the block. If provided, it takes precedence over the `config` argument and default configuration for the plugin. +- `config`: (optional) an inline configuration for the block. If provided, it takes precedence over the `config` argument and default configuration for the content provider. ## Context -When Fabric renders a content block, a corresponding content plugin is called. Along with the [content provider configuration]({{< ref "configs/#content-provider-configuration" >}}) and input parameters, a plugin receives the context object with all data available. +When Fabric renders a content block, a corresponding content provider is executed. Along with the [configuration]({{< ref "configs/#content-provider-configuration" >}}) and the input parameters, the provider receives the context object with the data available for the provider. The context object is a JSON dictionary with pre-defined root-level fields: -- `data` points to a map of all resolved data definitions for the document. The JSON path to a specific data point follows the data block signature: `data..`. -- `query_result` points to a result of the execution of a JQ query provided in `query` attribute, as requested by `query_input_required` attribute. This is mostly used in `ref` blocks to explicitly pre-filter the data for the JQ query set in `query` attribute. +- `data` points to a map of all resolved data definitions for the document. The JSON path to a specific data point follows the data block signature: `data..`. +- `query_result` points to a result of the execution of a JQ query provided in `query` argument. ## References @@ -71,6 +76,8 @@ See [References]({{< ref references.md >}}) for the details about referencing co ## Example +The template `document.test-doc` with one `data.inline` block, one `content.text` block and one `content.openai_text` block: + ```hcl config content openai_text "test_account" { api_key = "" @@ -103,9 +110,19 @@ document "test-doc" { } ``` -produces the output -``` +produces the following output: + +```text There are 3 items -In the vast expanse of the universe, three brave astronauts, aaa, bbb, and ccc, embarked on a daring mission of space exploration. As they soared through the galaxies, their unwavering determination and unyielding teamwork propelled them towards uncharted territories, uncovering hidden wonders and pushing the boundaries of human understanding. Together, aaa, bbb, and ccc, etched their names in the stars as pioneers of a new era, forever inspiring generations to dream beyond the confines of Earth. +In the vast expanse of the universe, three brave astronauts, aaa, bbb, and ccc, embarked on +a daring mission of space exploration. As they soared through the galaxies, their unwavering +determination and unyielding teamwork propelled them towards uncharted territories, +uncovering hidden wonders and pushing the boundaries of human understanding. +Together, aaa, bbb, and ccc, etched their names in the stars as pioneers of a new era, +forever inspiring generations to dream beyond the confines of Earth. ``` + +## Next steps + +See [Section Blocks]({{< ref "section-blocks.md" >}}) documentation to learn how to group the content into the sections for better maintainability and re-usability. diff --git a/docs/language/data-blocks.md b/docs/language/data-blocks.md index e1f18e30..b37094cf 100644 --- a/docs/language/data-blocks.md +++ b/docs/language/data-blocks.md @@ -6,15 +6,17 @@ weight: 50 # Data blocks -`data` blocks define data requirements for the template. In its signature, the block specifies the data source Fabric will fetch the data from. +`data` blocks define data requirements for the template. The block signature includes the name of the data source that will execute the data block and load the data from external source. Fabric supports many [data sources]({{< ref "data-sources.md" >}}) through its [plugin ecosystem]({{< ref "plugins.md" >}}). ```hcl +# Root-level definition of a data block data "" { ... } document "foobar" { + # In-document definition of a data block data "" { ... } @@ -30,20 +32,20 @@ When Fabric starts rendering the template, the data sources for the data blocks ## Supported arguments -The arguments provided in the block are either generic arguments or plugin-specific input parameters. +The arguments provided in the block are either generic arguments or data-source-specific input parameters. ### Generic arguments - `config`: (optional) a reference to a named configuration block for the data source or a content provider. If provided, it takes precedence over the default configuration. See [Data source configuration]({{< ref "configs.md#data-source-configuration" >}}) for the details. -### Plugin-specific Arguments +### Data source arguments -Plugin-specific arguments are defined by a plugin specification. See [Plugins]({{< ref "plugins.md" >}}) for the details on the supported arguments per plugin. +Data source arguments differ per data source. See the documentation for a specific data source (find it in [supported data sources]({{< ref "data-sources.md" >}})) for the details on the supported arguments. -## Supported Nested Blocks +## Supported nested blocks - `meta`: (optional) a block containing metadata for the block. -- `config`: (optional) an inline configuration for the block. If provided, it takes precedence over the `config` argument and default configuration for the plugin. +- `config`: (optional) an inline configuration for the block. If provided, it takes precedence over the `config` argument and default configuration for the content provider. ## References @@ -52,7 +54,6 @@ See [References]({{< ref references.md >}}) for the details about referencing da ## Example ```hcl - config data csv { delimiter = ";" } @@ -76,3 +77,7 @@ document "test-document" { } } ``` + +## Next steps + +See [Content Blocks]({{< ref "content-blocks.md" >}}) documentation to learn how to define content, like text paragraphs, tables, graphs and images, in the template. diff --git a/docs/language/documents.md b/docs/language/documents.md index 13f6cbdc..7f80062b 100644 --- a/docs/language/documents.md +++ b/docs/language/documents.md @@ -10,14 +10,16 @@ Document blocks are the most important element of the Fabric configuration. `doc ```hcl document "" { + + title = "" + ... } ``` -A block type `document` and a document name are used as an unique identifier for the document template within the codebase. -The document blocks must be on a root level of the configuration file and can not be inside other blocks. +A block type `document` and a document name are an unique identifier for the document template within the codebase. The document blocks must defined be on a root level of the configuration file and can not be inside other blocks. -The `document` block is a structure that groups the data definitions, the section, and the content blocks together. +The `document` block is a structure that groups the data definitions, the sections, and the content blocks together, and describes the document to be rendered. ## Supported arguments @@ -29,3 +31,7 @@ The `document` block is a structure that groups the data definitions, the sectio - `data`: see [Data Blocks]({{< ref data-blocks.md >}}) for the details. - `content`: see [Content Blocks]({{< ref content-blocks.md >}}) for the details. - `section`: see [Section Blocks]({{< ref section-blocks.md >}}) for the details. + +## Next steps + +See [Data Blocks]({{< ref "data-blocks.md" >}}) documentation to learn how to define data requirements in the templates. diff --git a/docs/language/syntax.md b/docs/language/syntax.md index 5832b97b..3aff5cc0 100644 --- a/docs/language/syntax.md +++ b/docs/language/syntax.md @@ -6,13 +6,13 @@ weight: 10 # Syntax -This page describes native syntax of the Fabric Configuration Language (FCL). FCL is based on [HCL](https://github.com/hashicorp/hcl/blob/main/hclsyntax/spec.md) (HashiCorp Configuration Language) favored by many applications for simplicity, readability, and clarity. +This page describes the native syntax of the Fabric Configuration Language (FCL). Leveraging the foundation laid by the [HashiCorp Configuration Language](https://github.com/hashicorp/hcl/blob/main/hclsyntax/spec.md) (HCL), FCL aligns itself with a syntax favored by numerous applications for its simplicity, readability, and clarity. -Fabric language syntax has two core components: arguments and blocks. +The syntax of the Fabric language revolves around two fundamental components: arguments and blocks. These elements constitute the building blocks for crafting configurations within the Fabric Configuration Language. ## Arguments -The arguments are used for assigning a value to a name inside a block: +The arguments play a crucial role in assigning values to names within a block. An example of using arguments is as follows: ```hcl ... { @@ -20,11 +20,11 @@ The arguments are used for assigning a value to a name inside a block: } ``` -The argument name (`query_string` in the snippet above) can contain letters, digits, underscores (`_`), and hyphens (`-`). The first character of an identifier must not be a digit. +The argument name, `query_string` in the snippet above, is allowed to contain letters, digits, underscores (`_`), and hyphens (`-`). However, the first character of an identifier must not be a digit. ## Blocks -A block is a container that defines a configuration, a data requirement or a content structure. +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" { @@ -37,7 +37,7 @@ document "alerts_overview" { } ``` -A block has a type (`document` and `content` in the example above) that defines how many labels can be used in a block signature. A block can have a name (`"alerts_overview"`) or be anonymous (as a `content text` in the snippet above). +A block is characterized by a type (`document` and `content` in the example above), dictating the number of labels permissible in a block signature. Additionally, a block can either bear a name (for example, "`alerts_overview`") or remain anonymous, as seen in the case of content text in the provided snippet. This flexibility in block composition contributes to the expressive and modular nature of FCL configurations. Supported categories of blocks: @@ -60,3 +60,7 @@ It's recommend to use `#` single-line comment style usually. Future Fabric code ## Character encoding Fabric configuration files must be UTF-8 encoded. Fabric allows non-ASCII characters in comments, and string values. + +## Next steps + +See [Configuration]({{< ref "configs.md" >}}) documentation to learn how to configure Fabric and Fabric plugins. diff --git a/docs/plugins/_index.md b/docs/plugins/_index.md index 939aafab..f481e8b4 100644 --- a/docs/plugins/_index.md +++ b/docs/plugins/_index.md @@ -1,16 +1,21 @@ --- title: Plugins type: docs -weight: 5 +weight: 60 +hideChildren: true --- # Plugins -Fabric relies on plugins to implement data sources and content providers. To utilise a plugin's data sources and content providers, it must be installed by Fabric. 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 require configuration (for example, API keys, URLs, credentials, etc). +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). -A plugin name consists of a namespace (a name of a plugin vendor) and a short name. For example, `blackstork/elasticsearch` plugin implements Elasticsearch client data source and is released by [BlackStork](https://blackstork.io). +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. ## Where to get the plugins -Plugins are released and distributed independently from Fabric, with their own release cycle and version. +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. + +## Available plugins + +{{< plugins >}} diff --git a/docs/plugins/builtin.md b/docs/plugins/builtin.md deleted file mode 100644 index 10bdd836..00000000 --- a/docs/plugins/builtin.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -title: Built-in -weight: 10 -type: docs ---- - -# Built-in data sources and content providers - -`fabric` binary includes a set of built-in data sources and content providers, available out-of-the-box. - -## Data sources - -### `csv` - -#### Configuration - -The data source supports the following configuration parameters: - -```hcl -config data csv { - delimiter = # optional -} -``` - -#### Usage - -The data source supports the following parameters in the data blocks: - -```hcl -data csv { - path = # required -} -``` - -### `inline` - -#### Configuration - -The data source doesn't support configuration. - -#### Usage - -The data source doesn't define any parameters in the `data` block. - -### `json` - -#### Configuration - -The data source doesn't support configuration. - -#### Usage - -The data source supports the following parameters in the data blocks: - -```hcl -data json { - glob = # required -} -``` - -### `txt` - -#### Configuration - -The data source doesn't support configuration. - -#### Usage - -The data source supports the following parameters in the data blocks: - -```hcl -data txt { - path = # required -} -``` - -## Content providers - -### `frontmatter` - -#### Configuration - -The content provider doesn't support configuration. - -#### Usage - -The content source supports the following parameters in the content blocks: - -```hcl -content frontmatter { - content = # optional - format = # optional -} -``` - -### `image` - -#### Configuration - -The content provider doesn't support configuration. - -#### Usage - -The content source supports the following parameters in the content blocks: - -```hcl -content image { - alt = # optional - src = # required -} -``` - -### `list` - -#### Configuration - -The content provider doesn't support configuration. - -#### Usage - -The content source supports the following parameters in the content blocks: - -```hcl -content list { - format = # optional - item_template = # required -} -``` - -### `table` - -#### Configuration - -The content provider doesn't support configuration. - -#### Usage - -The content source supports the following parameters in the content blocks: - -```hcl -content table { - columns = # required -} -``` - -### `text` - -#### Configuration - -The content provider doesn't support configuration. - -#### Usage - -The content source supports the following parameters in the content blocks: - -```hcl -content text { - absolute_title_size = # optional - code_language = # optional - format_as = # optional - text = # required -} -``` - -### `toc` - -#### Configuration - -The content provider doesn't support configuration. - -#### Usage - -The content source supports the following parameters in the content blocks: - -```hcl -content toc { - end_level = # optional - ordered = # optional - scope = # optional - start_level = # optional -} -``` diff --git a/docs/plugins/builtin/_index.md b/docs/plugins/builtin/_index.md new file mode 100644 index 00000000..711f971d --- /dev/null +++ b/docs/plugins/builtin/_index.md @@ -0,0 +1,24 @@ +--- +title: Built-in +weight: 10 +plugin: + name: blackstork/builtin + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/builtin/" +type: docs +--- + +{{< plugin-header "blackstork/builtin" "builtin" "v0.4.0" >}} + +`fabric` binary includes a set of built-in data sources and content providers, available out-of-the-box. + + +## Data sources + +{{< plugin-resources "builtin" "data-source" >}} + +## Content providers + +{{< plugin-resources "builtin" "content-provider" >}} \ No newline at end of file diff --git a/docs/plugins/builtin/content-providers/frontmatter.md b/docs/plugins/builtin/content-providers/frontmatter.md new file mode 100644 index 00000000..e97c14e7 --- /dev/null +++ b/docs/plugins/builtin/content-providers/frontmatter.md @@ -0,0 +1,35 @@ +--- +title: frontmatter +plugin: + name: blackstork/builtin + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/builtin/" +resource: + type: content-provider +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/builtin" "builtin" "v0.4.0" "frontmatter" "content provider" >}} + +The content provider is built-in, which means it's a part of `fabric` binary. It's available out-of-the-box, no installation required. + + +#### Configuration + +The content provider doesn't support any configuration parameters. + +#### Usage + +The content provider supports the following execution parameters: + +```hcl +content frontmatter { + content = # optional + format = # optional +} +``` + diff --git a/docs/plugins/builtin/content-providers/image.md b/docs/plugins/builtin/content-providers/image.md new file mode 100644 index 00000000..e579dd8e --- /dev/null +++ b/docs/plugins/builtin/content-providers/image.md @@ -0,0 +1,35 @@ +--- +title: image +plugin: + name: blackstork/builtin + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/builtin/" +resource: + type: content-provider +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/builtin" "builtin" "v0.4.0" "image" "content provider" >}} + +The content provider is built-in, which means it's a part of `fabric` binary. It's available out-of-the-box, no installation required. + + +#### Configuration + +The content provider doesn't support any configuration parameters. + +#### Usage + +The content provider supports the following execution parameters: + +```hcl +content image { + alt = # optional + src = # required +} +``` + diff --git a/docs/plugins/builtin/content-providers/list.md b/docs/plugins/builtin/content-providers/list.md new file mode 100644 index 00000000..6e0b8059 --- /dev/null +++ b/docs/plugins/builtin/content-providers/list.md @@ -0,0 +1,35 @@ +--- +title: list +plugin: + name: blackstork/builtin + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/builtin/" +resource: + type: content-provider +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/builtin" "builtin" "v0.4.0" "list" "content provider" >}} + +The content provider is built-in, which means it's a part of `fabric` binary. It's available out-of-the-box, no installation required. + + +#### Configuration + +The content provider doesn't support any configuration parameters. + +#### Usage + +The content provider supports the following execution parameters: + +```hcl +content list { + format = # optional + item_template = # required +} +``` + diff --git a/docs/plugins/builtin/content-providers/table.md b/docs/plugins/builtin/content-providers/table.md new file mode 100644 index 00000000..b1e2ff8e --- /dev/null +++ b/docs/plugins/builtin/content-providers/table.md @@ -0,0 +1,34 @@ +--- +title: table +plugin: + name: blackstork/builtin + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/builtin/" +resource: + type: content-provider +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/builtin" "builtin" "v0.4.0" "table" "content provider" >}} + +The content provider is built-in, which means it's a part of `fabric` binary. It's available out-of-the-box, no installation required. + + +#### Configuration + +The content provider doesn't support any configuration parameters. + +#### Usage + +The content provider supports the following execution parameters: + +```hcl +content table { + columns = # required +} +``` + diff --git a/docs/plugins/builtin/content-providers/text.md b/docs/plugins/builtin/content-providers/text.md new file mode 100644 index 00000000..5f09ba9c --- /dev/null +++ b/docs/plugins/builtin/content-providers/text.md @@ -0,0 +1,37 @@ +--- +title: text +plugin: + name: blackstork/builtin + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/builtin/" +resource: + type: content-provider +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/builtin" "builtin" "v0.4.0" "text" "content provider" >}} + +The content provider is built-in, which means it's a part of `fabric` binary. It's available out-of-the-box, no installation required. + + +#### Configuration + +The content provider doesn't support any configuration parameters. + +#### Usage + +The content provider supports the following execution parameters: + +```hcl +content text { + absolute_title_size = # optional + code_language = # optional + format_as = # optional + text = # required +} +``` + diff --git a/docs/plugins/builtin/content-providers/toc.md b/docs/plugins/builtin/content-providers/toc.md new file mode 100644 index 00000000..58f34aec --- /dev/null +++ b/docs/plugins/builtin/content-providers/toc.md @@ -0,0 +1,37 @@ +--- +title: toc +plugin: + name: blackstork/builtin + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/builtin/" +resource: + type: content-provider +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/builtin" "builtin" "v0.4.0" "toc" "content provider" >}} + +The content provider is built-in, which means it's a part of `fabric` binary. It's available out-of-the-box, no installation required. + + +#### Configuration + +The content provider doesn't support any configuration parameters. + +#### Usage + +The content provider supports the following execution parameters: + +```hcl +content toc { + end_level = # optional + ordered = # optional + scope = # optional + start_level = # optional +} +``` + diff --git a/docs/plugins/builtin/data-sources/csv.md b/docs/plugins/builtin/data-sources/csv.md new file mode 100644 index 00000000..894ffbe5 --- /dev/null +++ b/docs/plugins/builtin/data-sources/csv.md @@ -0,0 +1,38 @@ +--- +title: csv +plugin: + name: blackstork/builtin + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/builtin/" +resource: + type: data-source +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/builtin" "builtin" "v0.4.0" "csv" "data source" >}} + +The data source is built-in, which means it's a part of `fabric` binary. It's available out-of-the-box, no installation required. + +## Configuration + +The data source supports the following configuration parameters: + +```hcl +config data csv { + delimiter = # optional +} +``` + +## Usage + +The data source supports the following parameters in the data blocks: + +```hcl +data csv { + path = # required +} +``` \ No newline at end of file diff --git a/docs/plugins/builtin/data-sources/inline.md b/docs/plugins/builtin/data-sources/inline.md new file mode 100644 index 00000000..0e4b6784 --- /dev/null +++ b/docs/plugins/builtin/data-sources/inline.md @@ -0,0 +1,26 @@ +--- +title: inline +plugin: + name: blackstork/builtin + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/builtin/" +resource: + type: data-source +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/builtin" "builtin" "v0.4.0" "inline" "data source" >}} + +The data source is built-in, which means it's a part of `fabric` binary. It's available out-of-the-box, no installation required. + +## Configuration + +The data source doesn't support configuration. + +## Usage + +The data source doesn't define any execution parameters. \ No newline at end of file diff --git a/docs/plugins/builtin/data-sources/json.md b/docs/plugins/builtin/data-sources/json.md new file mode 100644 index 00000000..5fe48553 --- /dev/null +++ b/docs/plugins/builtin/data-sources/json.md @@ -0,0 +1,32 @@ +--- +title: json +plugin: + name: blackstork/builtin + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/builtin/" +resource: + type: data-source +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/builtin" "builtin" "v0.4.0" "json" "data source" >}} + +The data source is built-in, which means it's a part of `fabric` binary. It's available out-of-the-box, no installation required. + +## Configuration + +The data source doesn't support configuration. + +## Usage + +The data source supports the following parameters in the data blocks: + +```hcl +data json { + glob = # required +} +``` \ No newline at end of file diff --git a/docs/plugins/builtin/data-sources/txt.md b/docs/plugins/builtin/data-sources/txt.md new file mode 100644 index 00000000..a9cabd76 --- /dev/null +++ b/docs/plugins/builtin/data-sources/txt.md @@ -0,0 +1,32 @@ +--- +title: txt +plugin: + name: blackstork/builtin + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/builtin/" +resource: + type: data-source +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/builtin" "builtin" "v0.4.0" "txt" "data source" >}} + +The data source is built-in, which means it's a part of `fabric` binary. It's available out-of-the-box, no installation required. + +## Configuration + +The data source doesn't support configuration. + +## Usage + +The data source supports the following parameters in the data blocks: + +```hcl +data txt { + path = # required +} +``` \ No newline at end of file diff --git a/docs/plugins/elastic.md b/docs/plugins/elastic.md deleted file mode 100644 index b7e33bdd..00000000 --- a/docs/plugins/elastic.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: blackstork/elastic -weight: 20 -type: docs ---- - -# `blackstork/elastic` plugin - -## Installation - -To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: - -```hcl -fabric { - plugin_versions = { - "blackstork/elastic" = "=> v0.0.0-dev" - } -} -``` - -## Data sources - -The plugin has the following data sources available: - -### `elasticsearch` - -#### Configuration - -The data source supports the following configuration parameters: - -```hcl -config data elasticsearch { - api_key = # optional - api_key_str = # optional - base_url = # optional - basic_auth_password = # optional - basic_auth_username = # optional - bearer_auth = # optional - ca_certs = # optional - cloud_id = # optional -} -``` - -#### Usage - -The data source supports the following parameters in the data blocks: - -```hcl -data elasticsearch { - fields = # optional - id = # optional - index = # required - query = # optional - query_string = # optional - size = # optional -} -``` \ No newline at end of file diff --git a/docs/plugins/elastic/_index.md b/docs/plugins/elastic/_index.md new file mode 100644 index 00000000..32558c92 --- /dev/null +++ b/docs/plugins/elastic/_index.md @@ -0,0 +1,30 @@ +--- +title: blackstork/elastic +weight: 20 +plugin: + name: blackstork/elastic + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/elastic/" +type: docs +--- + +{{< plugin-header "blackstork/elastic" "elastic" "v0.4.0" >}} + +## Installation + +To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: + +```hcl +fabric { + plugin_versions = { + "blackstork/elastic" = ">= v0.4.0" + } +} +``` + + +## Data sources + +{{< plugin-resources "elastic" "data-source" >}} diff --git a/docs/plugins/elastic/data-sources/elasticsearch.md b/docs/plugins/elastic/data-sources/elasticsearch.md new file mode 100644 index 00000000..3acd6537 --- /dev/null +++ b/docs/plugins/elastic/data-sources/elasticsearch.md @@ -0,0 +1,66 @@ +--- +title: elasticsearch +plugin: + name: blackstork/elastic + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/elastic/" +resource: + type: data-source +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/elastic" "elastic" "v0.4.0" "elasticsearch" "data source" >}} + +## Installation + +To use `elasticsearch` data source, you must install the plugin `blackstork/elastic`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), as shown below: + +```hcl +fabric { + plugin_versions = { + "blackstork/elastic" = ">= v0.4.0" + } +} +``` + +Note the version constraint set for the plugin. + +## Configuration + +The data source supports the following configuration parameters: + +```hcl +config data elasticsearch { + api_key = # optional + api_key_str = # optional + base_url = # optional + basic_auth_password = # optional + basic_auth_username = # optional + bearer_auth = # optional + ca_certs = # optional + cloud_id = # optional +} +``` + +## Usage + +The data source supports the following parameters in the data blocks: + +```hcl +data elasticsearch { + aggs = # optional + fields = # optional + id = # optional + index = # required + only_hits = # optional + query = # optional + query_string = # optional + size = # optional +} +``` \ No newline at end of file diff --git a/docs/plugins/github.md b/docs/plugins/github.md deleted file mode 100644 index 223de247..00000000 --- a/docs/plugins/github.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: blackstork/github -weight: 20 -type: docs ---- - -# `blackstork/github` plugin - -## Installation - -To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: - -```hcl -fabric { - plugin_versions = { - "blackstork/github" = "=> v0.0.0-dev" - } -} -``` - -## Data sources - -The plugin has the following data sources available: - -### `github_issues` - -#### Configuration - -The data source supports the following configuration parameters: - -```hcl -config data github_issues { - github_token = # required -} -``` - -#### Usage - -The data source supports the following parameters in the data blocks: - -```hcl -data github_issues { - assignee = # optional - creator = # optional - direction = # optional - labels = # optional - limit = # optional - mentioned = # optional - milestone = # optional - repository = # required - since = # optional - sort = # optional - state = # optional -} -``` \ No newline at end of file diff --git a/docs/plugins/github/_index.md b/docs/plugins/github/_index.md new file mode 100644 index 00000000..fe418372 --- /dev/null +++ b/docs/plugins/github/_index.md @@ -0,0 +1,30 @@ +--- +title: blackstork/github +weight: 20 +plugin: + name: blackstork/github + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/github/" +type: docs +--- + +{{< plugin-header "blackstork/github" "github" "v0.4.0" >}} + +## Installation + +To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: + +```hcl +fabric { + plugin_versions = { + "blackstork/github" = ">= v0.4.0" + } +} +``` + + +## Data sources + +{{< plugin-resources "github" "data-source" >}} diff --git a/docs/plugins/github/data-sources/github_issues.md b/docs/plugins/github/data-sources/github_issues.md new file mode 100644 index 00000000..1e258182 --- /dev/null +++ b/docs/plugins/github/data-sources/github_issues.md @@ -0,0 +1,62 @@ +--- +title: github_issues +plugin: + name: blackstork/github + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/github/" +resource: + type: data-source +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/github" "github" "v0.4.0" "github_issues" "data source" >}} + +## Installation + +To use `github_issues` data source, you must install the plugin `blackstork/github`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), as shown below: + +```hcl +fabric { + plugin_versions = { + "blackstork/github" = ">= v0.4.0" + } +} +``` + +Note the version constraint set for the plugin. + +## Configuration + +The data source supports the following configuration parameters: + +```hcl +config data github_issues { + github_token = # required +} +``` + +## Usage + +The data source supports the following parameters in the data blocks: + +```hcl +data github_issues { + assignee = # optional + creator = # optional + direction = # optional + labels = # optional + limit = # optional + mentioned = # optional + milestone = # optional + repository = # required + since = # optional + sort = # optional + state = # optional +} +``` \ No newline at end of file diff --git a/docs/plugins/graphql.md b/docs/plugins/graphql.md deleted file mode 100644 index 07338056..00000000 --- a/docs/plugins/graphql.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: blackstork/graphql -weight: 20 -type: docs ---- - -# `blackstork/graphql` plugin - -## Installation - -To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: - -```hcl -fabric { - plugin_versions = { - "blackstork/graphql" = "=> v0.0.0-dev" - } -} -``` - -## Data sources - -The plugin has the following data sources available: - -### `graphql` - -#### Configuration - -The data source supports the following configuration parameters: - -```hcl -config data graphql { - auth_token = # optional - url = # required -} -``` - -#### Usage - -The data source supports the following parameters in the data blocks: - -```hcl -data graphql { - query = # required -} -``` \ No newline at end of file diff --git a/docs/plugins/graphql/_index.md b/docs/plugins/graphql/_index.md new file mode 100644 index 00000000..3f77b32f --- /dev/null +++ b/docs/plugins/graphql/_index.md @@ -0,0 +1,30 @@ +--- +title: blackstork/graphql +weight: 20 +plugin: + name: blackstork/graphql + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/graphql/" +type: docs +--- + +{{< plugin-header "blackstork/graphql" "graphql" "v0.4.0" >}} + +## Installation + +To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: + +```hcl +fabric { + plugin_versions = { + "blackstork/graphql" = ">= v0.4.0" + } +} +``` + + +## Data sources + +{{< plugin-resources "graphql" "data-source" >}} diff --git a/docs/plugins/graphql/data-sources/graphql.md b/docs/plugins/graphql/data-sources/graphql.md new file mode 100644 index 00000000..e1025f2c --- /dev/null +++ b/docs/plugins/graphql/data-sources/graphql.md @@ -0,0 +1,53 @@ +--- +title: graphql +plugin: + name: blackstork/graphql + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/graphql/" +resource: + type: data-source +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/graphql" "graphql" "v0.4.0" "graphql" "data source" >}} + +## Installation + +To use `graphql` data source, you must install the plugin `blackstork/graphql`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), as shown below: + +```hcl +fabric { + plugin_versions = { + "blackstork/graphql" = ">= v0.4.0" + } +} +``` + +Note the version constraint set for the plugin. + +## Configuration + +The data source supports the following configuration parameters: + +```hcl +config data graphql { + auth_token = # optional + url = # required +} +``` + +## Usage + +The data source supports the following parameters in the data blocks: + +```hcl +data graphql { + query = # required +} +``` \ No newline at end of file diff --git a/docs/plugins/hackerone/_index.md b/docs/plugins/hackerone/_index.md new file mode 100644 index 00000000..16723341 --- /dev/null +++ b/docs/plugins/hackerone/_index.md @@ -0,0 +1,30 @@ +--- +title: blackstork/hackerone +weight: 20 +plugin: + name: blackstork/hackerone + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/hackerone/" +type: docs +--- + +{{< plugin-header "blackstork/hackerone" "hackerone" "v0.4.0" >}} + +## Installation + +To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: + +```hcl +fabric { + plugin_versions = { + "blackstork/hackerone" = ">= v0.4.0" + } +} +``` + + +## Data sources + +{{< plugin-resources "hackerone" "data-source" >}} diff --git a/docs/plugins/hackerone.md b/docs/plugins/hackerone/data-sources/hackerone_reports.md similarity index 75% rename from docs/plugins/hackerone.md rename to docs/plugins/hackerone/data-sources/hackerone_reports.md index 307c4516..181dbfcb 100644 --- a/docs/plugins/hackerone.md +++ b/docs/plugins/hackerone/data-sources/hackerone_reports.md @@ -1,30 +1,37 @@ --- -title: blackstork/hackerone -weight: 20 +title: hackerone_reports +plugin: + name: blackstork/hackerone + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/hackerone/" +resource: + type: data-source type: docs --- -# `blackstork/hackerone` plugin +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/hackerone" "hackerone" "v0.4.0" "hackerone_reports" "data source" >}} ## Installation -To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: +To use `hackerone_reports` data source, you must install the plugin `blackstork/hackerone`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), as shown below: ```hcl fabric { plugin_versions = { - "blackstork/hackerone" = "=> v0.0.0-dev" + "blackstork/hackerone" = ">= v0.4.0" } } ``` -## Data sources - -The plugin has the following data sources available: - -### `hackerone_reports` +Note the version constraint set for the plugin. -#### Configuration +## Configuration The data source supports the following configuration parameters: @@ -35,7 +42,7 @@ config data hackerone_reports { } ``` -#### Usage +## Usage The data source supports the following parameters in the data blocks: diff --git a/docs/plugins/openai.md b/docs/plugins/openai.md deleted file mode 100644 index 771e204d..00000000 --- a/docs/plugins/openai.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: blackstork/openai -weight: 20 -type: docs ---- - -# `blackstork/openai` plugin - -## Installation - -To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: - -```hcl -fabric { - plugin_versions = { - "blackstork/openai" = "=> v0.0.0-dev" - } -} -``` - - - -## Content providers -The plugin has the following content providers available: - -### `openai_text` - -#### Configuration - -The content provider supports the following configuration parameters: - -```hcl -config content openai_text { - api_key = # required - organization_id = # optional - system_prompt = # optional -} -``` - -#### Usage - -The content source supports the following parameters in the content blocks: - -```hcl -content openai_text { - model = # optional - prompt = # required -} -``` diff --git a/docs/plugins/openai/_index.md b/docs/plugins/openai/_index.md new file mode 100644 index 00000000..9b95fd09 --- /dev/null +++ b/docs/plugins/openai/_index.md @@ -0,0 +1,31 @@ +--- +title: blackstork/openai +weight: 20 +plugin: + name: blackstork/openai + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/openai/" +type: docs +--- + +{{< plugin-header "blackstork/openai" "openai" "v0.4.0" >}} + +## Installation + +To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: + +```hcl +fabric { + plugin_versions = { + "blackstork/openai" = ">= v0.4.0" + } +} +``` + + + +## Content providers + +{{< plugin-resources "openai" "content-provider" >}} \ No newline at end of file diff --git a/docs/plugins/openai/content-providers/openai_text.md b/docs/plugins/openai/content-providers/openai_text.md new file mode 100644 index 00000000..0ea07d2d --- /dev/null +++ b/docs/plugins/openai/content-providers/openai_text.md @@ -0,0 +1,57 @@ +--- +title: openai_text +plugin: + name: blackstork/openai + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/openai/" +resource: + type: content-provider +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/openai" "openai" "v0.4.0" "openai_text" "content provider" >}} + +## Installation + +To use `openai_text` content provider, you must install the plugin `blackstork/openai`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), as shown below: + +```hcl +fabric { + plugin_versions = { + "blackstork/openai" = ">= v0.4.0" + } +} +``` + +Note the version constraint set for the plugin. + + +#### Configuration + +The content provider supports the following configuration parameters: + +```hcl +config content openai_text { + api_key = # required + organization_id = # optional + system_prompt = # optional +} +``` + +#### Usage + +The content provider supports the following execution parameters: + +```hcl +content openai_text { + model = # optional + prompt = # required +} +``` + diff --git a/docs/plugins/opencti/_index.md b/docs/plugins/opencti/_index.md new file mode 100644 index 00000000..1ffd41b1 --- /dev/null +++ b/docs/plugins/opencti/_index.md @@ -0,0 +1,30 @@ +--- +title: blackstork/opencti +weight: 20 +plugin: + name: blackstork/opencti + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/opencti/" +type: docs +--- + +{{< plugin-header "blackstork/opencti" "opencti" "v0.4.0" >}} + +## Installation + +To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: + +```hcl +fabric { + plugin_versions = { + "blackstork/opencti" = ">= v0.4.0" + } +} +``` + + +## Data sources + +{{< plugin-resources "opencti" "data-source" >}} diff --git a/docs/plugins/opencti/data-sources/opencti.md b/docs/plugins/opencti/data-sources/opencti.md new file mode 100644 index 00000000..bef1107b --- /dev/null +++ b/docs/plugins/opencti/data-sources/opencti.md @@ -0,0 +1,53 @@ +--- +title: opencti +plugin: + name: blackstork/opencti + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/opencti/" +resource: + type: data-source +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/opencti" "opencti" "v0.4.0" "opencti" "data source" >}} + +## Installation + +To use `opencti` data source, you must install the plugin `blackstork/opencti`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), as shown below: + +```hcl +fabric { + plugin_versions = { + "blackstork/opencti" = ">= v0.4.0" + } +} +``` + +Note the version constraint set for the plugin. + +## Configuration + +The data source supports the following configuration parameters: + +```hcl +config data opencti { + auth_token = # optional + graphql_url = # required +} +``` + +## Usage + +The data source supports the following parameters in the data blocks: + +```hcl +data opencti { + graphql_query = # required +} +``` \ No newline at end of file diff --git a/docs/plugins/plugins.json b/docs/plugins/plugins.json new file mode 100644 index 00000000..bbda848e --- /dev/null +++ b/docs/plugins/plugins.json @@ -0,0 +1,383 @@ +[ + { + "name": "blackstork/builtin", + "resources": [ + { + "name": "csv", + "type": "data-source", + "config_params": [ + "delimiter" + ], + "arguments": [ + "path" + ] + }, + { + "name": "txt", + "type": "data-source", + "arguments": [ + "path" + ] + }, + { + "name": "json", + "type": "data-source", + "arguments": [ + "glob" + ] + }, + { + "name": "inline", + "type": "data-source" + }, + { + "name": "toc", + "type": "content-provider", + "arguments": [ + "start_level", + "end_level", + "ordered", + "scope" + ] + }, + { + "name": "text", + "type": "content-provider", + "arguments": [ + "absolute_title_size", + "code_language", + "text", + "format_as" + ] + }, + { + "name": "image", + "type": "content-provider", + "arguments": [ + "src", + "alt" + ] + }, + { + "name": "list", + "type": "content-provider", + "arguments": [ + "item_template", + "format" + ] + }, + { + "name": "table", + "type": "content-provider", + "arguments": [ + "columns" + ] + }, + { + "name": "frontmatter", + "type": "content-provider", + "arguments": [ + "format", + "content" + ] + } + ], + "shortname": "builtin", + "version": "v0.4.0" + }, + { + "name": "blackstork/elastic", + "resources": [ + { + "name": "elasticsearch", + "type": "data-source", + "config_params": [ + "basic_auth_username", + "basic_auth_password", + "bearer_auth", + "ca_certs", + "base_url", + "cloud_id", + "api_key_str", + "api_key" + ], + "arguments": [ + "index", + "id", + "query_string", + "query", + "aggs", + "only_hits", + "fields", + "size" + ] + } + ], + "shortname": "elastic", + "version": "v0.4.0" + }, + { + "name": "blackstork/github", + "resources": [ + { + "name": "github_issues", + "type": "data-source", + "config_params": [ + "github_token" + ], + "arguments": [ + "labels", + "direction", + "since", + "limit", + "repository", + "assignee", + "creator", + "mentioned", + "milestone", + "state", + "sort" + ] + } + ], + "shortname": "github", + "version": "v0.4.0" + }, + { + "name": "blackstork/graphql", + "resources": [ + { + "name": "graphql", + "type": "data-source", + "config_params": [ + "url", + "auth_token" + ], + "arguments": [ + "query" + ] + } + ], + "shortname": "graphql", + "version": "v0.4.0" + }, + { + "name": "blackstork/openai", + "resources": [ + { + "name": "openai_text", + "type": "content-provider", + "config_params": [ + "system_prompt", + "api_key", + "organization_id" + ], + "arguments": [ + "model", + "prompt" + ] + } + ], + "shortname": "openai", + "version": "v0.4.0" + }, + { + "name": "blackstork/opencti", + "resources": [ + { + "name": "opencti", + "type": "data-source", + "config_params": [ + "graphql_url", + "auth_token" + ], + "arguments": [ + "graphql_query" + ] + } + ], + "shortname": "opencti", + "version": "v0.4.0" + }, + { + "name": "blackstork/postgresql", + "resources": [ + { + "name": "postgresql", + "type": "data-source", + "config_params": [ + "database_url" + ], + "arguments": [ + "sql_query", + "sql_args" + ] + } + ], + "shortname": "postgresql", + "version": "v0.4.0" + }, + { + "name": "blackstork/sqlite", + "resources": [ + { + "name": "sqlite", + "type": "data-source", + "config_params": [ + "database_uri" + ], + "arguments": [ + "sql_query", + "sql_args" + ] + } + ], + "shortname": "sqlite", + "version": "v0.4.0" + }, + { + "name": "blackstork/terraform", + "resources": [ + { + "name": "terraform_state_local", + "type": "data-source", + "arguments": [ + "path" + ] + } + ], + "shortname": "terraform", + "version": "v0.4.0" + }, + { + "name": "blackstork/hackerone", + "resources": [ + { + "name": "hackerone_reports", + "type": "data-source", + "config_params": [ + "api_username", + "api_token" + ], + "arguments": [ + "hacker_published", + "created_at__lt", + "submitted_at__lt", + "bounty_awarded_at__gt", + "swag_awarded_at__lt", + "last_program_activity_at__gt", + "page_number", + "submitted_at__gt", + "triaged_at__gt", + "triaged_at__null", + "disclosed_at__lt", + "first_program_activity_at__lt", + "last_program_activity_at__lt", + "last_public_activity_at__gt", + "created_at__gt", + "last_report_activity_at__gt", + "closed_at__lt", + "closed_at__null", + "disclosed_at__gt", + "bounty_awarded_at__null", + "last_activity_at__gt", + "keyword", + "triaged_at__lt", + "assignee", + "severity", + "last_report_activity_at__lt", + "first_program_activity_at__gt", + "last_activity_at__lt", + "size", + "weakness_id", + "disclosed_at__null", + "bounty_awarded_at__lt", + "swag_awarded_at__gt", + "swag_awarded_at__null", + "id", + "inbox_ids", + "reporter", + "closed_at__gt", + "reporter_agreed_on_going_public", + "first_program_activity_at__null", + "last_program_activity_at__null", + "custom_fields", + "sort", + "state", + "last_public_activity_at__lt", + "program" + ] + } + ], + "shortname": "hackerone", + "version": "v0.4.0" + }, + { + "name": "blackstork/virustotal", + "resources": [ + { + "name": "virustotal_api_usage", + "type": "data-source", + "config_params": [ + "api_key" + ], + "arguments": [ + "user_id", + "group_id", + "start_date", + "end_date" + ] + } + ], + "shortname": "virustotal", + "version": "v0.4.0" + }, + { + "name": "blackstork/splunk", + "resources": [ + { + "name": "splunk_search", + "type": "data-source", + "config_params": [ + "auth_token", + "host", + "deployment_name" + ], + "arguments": [ + "latest_time", + "search_query", + "max_count", + "status_buckets", + "rf", + "earliest_time" + ] + } + ], + "shortname": "splunk", + "version": "v0.4.0" + }, + { + "name": "blackstork/stixview", + "resources": [ + { + "name": "stixview", + "type": "content-provider", + "arguments": [ + "gist_id", + "caption", + "show_sidebar", + "show_tlp_as_tags", + "show_marking_nodes", + "show_labels", + "stix_url", + "show_footer", + "show_idrefs", + "width", + "height" + ] + } + ], + "shortname": "stixview", + "version": "v0.4.0" + } +] \ No newline at end of file diff --git a/docs/plugins/postgresql.md b/docs/plugins/postgresql.md deleted file mode 100644 index 2da82be1..00000000 --- a/docs/plugins/postgresql.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: blackstork/postgresql -weight: 20 -type: docs ---- - -# `blackstork/postgresql` plugin - -## Installation - -To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: - -```hcl -fabric { - plugin_versions = { - "blackstork/postgresql" = "=> v0.0.0-dev" - } -} -``` - -## Data sources - -The plugin has the following data sources available: - -### `postgresql` - -#### Configuration - -The data source supports the following configuration parameters: - -```hcl -config data postgresql { - database_url = # required -} -``` - -#### Usage - -The data source supports the following parameters in the data blocks: - -```hcl -data postgresql { - sql_args = # optional - sql_query = # required -} -``` \ No newline at end of file diff --git a/docs/plugins/postgresql/_index.md b/docs/plugins/postgresql/_index.md new file mode 100644 index 00000000..e346411c --- /dev/null +++ b/docs/plugins/postgresql/_index.md @@ -0,0 +1,30 @@ +--- +title: blackstork/postgresql +weight: 20 +plugin: + name: blackstork/postgresql + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/postgresql/" +type: docs +--- + +{{< plugin-header "blackstork/postgresql" "postgresql" "v0.4.0" >}} + +## Installation + +To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: + +```hcl +fabric { + plugin_versions = { + "blackstork/postgresql" = ">= v0.4.0" + } +} +``` + + +## Data sources + +{{< plugin-resources "postgresql" "data-source" >}} diff --git a/docs/plugins/postgresql/data-sources/postgresql.md b/docs/plugins/postgresql/data-sources/postgresql.md new file mode 100644 index 00000000..efda17a5 --- /dev/null +++ b/docs/plugins/postgresql/data-sources/postgresql.md @@ -0,0 +1,53 @@ +--- +title: postgresql +plugin: + name: blackstork/postgresql + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/postgresql/" +resource: + type: data-source +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/postgresql" "postgresql" "v0.4.0" "postgresql" "data source" >}} + +## Installation + +To use `postgresql` data source, you must install the plugin `blackstork/postgresql`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), as shown below: + +```hcl +fabric { + plugin_versions = { + "blackstork/postgresql" = ">= v0.4.0" + } +} +``` + +Note the version constraint set for the plugin. + +## Configuration + +The data source supports the following configuration parameters: + +```hcl +config data postgresql { + database_url = # required +} +``` + +## Usage + +The data source supports the following parameters in the data blocks: + +```hcl +data postgresql { + sql_args = # optional + sql_query = # required +} +``` \ No newline at end of file diff --git a/docs/plugins/splunk.md b/docs/plugins/splunk.md deleted file mode 100644 index 28ee1b41..00000000 --- a/docs/plugins/splunk.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: blackstork/splunk -weight: 20 -type: docs ---- - -# `blackstork/splunk` plugin - -## Installation - -To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: - -```hcl -fabric { - plugin_versions = { - "blackstork/splunk" = "=> v0.0.0-dev" - } -} -``` - -## Data sources - -The plugin has the following data sources available: - -### `splunk_search` - -#### Configuration - -The data source supports the following configuration parameters: - -```hcl -config data splunk_search { - auth_token = # required - deployment_name = # optional - host = # optional -} -``` - -#### Usage - -The data source supports the following parameters in the data blocks: - -```hcl -data splunk_search { - earliest_time = # optional - latest_time = # optional - max_count = # optional - rf = # optional - search_query = # required - status_buckets = # optional -} -``` \ No newline at end of file diff --git a/docs/plugins/splunk/_index.md b/docs/plugins/splunk/_index.md new file mode 100644 index 00000000..22459457 --- /dev/null +++ b/docs/plugins/splunk/_index.md @@ -0,0 +1,30 @@ +--- +title: blackstork/splunk +weight: 20 +plugin: + name: blackstork/splunk + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/splunk/" +type: docs +--- + +{{< plugin-header "blackstork/splunk" "splunk" "v0.4.0" >}} + +## Installation + +To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: + +```hcl +fabric { + plugin_versions = { + "blackstork/splunk" = ">= v0.4.0" + } +} +``` + + +## Data sources + +{{< plugin-resources "splunk" "data-source" >}} diff --git a/docs/plugins/splunk/data-sources/splunk_search.md b/docs/plugins/splunk/data-sources/splunk_search.md new file mode 100644 index 00000000..47f86afa --- /dev/null +++ b/docs/plugins/splunk/data-sources/splunk_search.md @@ -0,0 +1,59 @@ +--- +title: splunk_search +plugin: + name: blackstork/splunk + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/splunk/" +resource: + type: data-source +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/splunk" "splunk" "v0.4.0" "splunk_search" "data source" >}} + +## Installation + +To use `splunk_search` data source, you must install the plugin `blackstork/splunk`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), as shown below: + +```hcl +fabric { + plugin_versions = { + "blackstork/splunk" = ">= v0.4.0" + } +} +``` + +Note the version constraint set for the plugin. + +## Configuration + +The data source supports the following configuration parameters: + +```hcl +config data splunk_search { + auth_token = # required + deployment_name = # optional + host = # optional +} +``` + +## Usage + +The data source supports the following parameters in the data blocks: + +```hcl +data splunk_search { + earliest_time = # optional + latest_time = # optional + max_count = # optional + rf = # optional + search_query = # required + status_buckets = # optional +} +``` \ No newline at end of file diff --git a/docs/plugins/sqlite.md b/docs/plugins/sqlite.md deleted file mode 100644 index 9de43b68..00000000 --- a/docs/plugins/sqlite.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: blackstork/sqlite -weight: 20 -type: docs ---- - -# `blackstork/sqlite` plugin - -## Installation - -To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: - -```hcl -fabric { - plugin_versions = { - "blackstork/sqlite" = "=> v0.0.0-dev" - } -} -``` - -## Data sources - -The plugin has the following data sources available: - -### `sqlite` - -#### Configuration - -The data source supports the following configuration parameters: - -```hcl -config data sqlite { - database_uri = # required -} -``` - -#### Usage - -The data source supports the following parameters in the data blocks: - -```hcl -data sqlite { - sql_args = # optional - sql_query = # required -} -``` \ No newline at end of file diff --git a/docs/plugins/sqlite/_index.md b/docs/plugins/sqlite/_index.md new file mode 100644 index 00000000..cff77618 --- /dev/null +++ b/docs/plugins/sqlite/_index.md @@ -0,0 +1,30 @@ +--- +title: blackstork/sqlite +weight: 20 +plugin: + name: blackstork/sqlite + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/sqlite/" +type: docs +--- + +{{< plugin-header "blackstork/sqlite" "sqlite" "v0.4.0" >}} + +## Installation + +To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: + +```hcl +fabric { + plugin_versions = { + "blackstork/sqlite" = ">= v0.4.0" + } +} +``` + + +## Data sources + +{{< plugin-resources "sqlite" "data-source" >}} diff --git a/docs/plugins/sqlite/data-sources/sqlite.md b/docs/plugins/sqlite/data-sources/sqlite.md new file mode 100644 index 00000000..37733f1d --- /dev/null +++ b/docs/plugins/sqlite/data-sources/sqlite.md @@ -0,0 +1,53 @@ +--- +title: sqlite +plugin: + name: blackstork/sqlite + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/sqlite/" +resource: + type: data-source +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/sqlite" "sqlite" "v0.4.0" "sqlite" "data source" >}} + +## Installation + +To use `sqlite` data source, you must install the plugin `blackstork/sqlite`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), as shown below: + +```hcl +fabric { + plugin_versions = { + "blackstork/sqlite" = ">= v0.4.0" + } +} +``` + +Note the version constraint set for the plugin. + +## Configuration + +The data source supports the following configuration parameters: + +```hcl +config data sqlite { + database_uri = # required +} +``` + +## Usage + +The data source supports the following parameters in the data blocks: + +```hcl +data sqlite { + sql_args = # optional + sql_query = # required +} +``` \ No newline at end of file diff --git a/docs/plugins/stixview.md b/docs/plugins/stixview.md deleted file mode 100644 index 3df909b9..00000000 --- a/docs/plugins/stixview.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: blackstork/stixview -weight: 20 -type: docs ---- - -# `blackstork/stixview` plugin - -## Installation - -To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: - -```hcl -fabric { - plugin_versions = { - "blackstork/stixview" = "=> v0.0.0-dev" - } -} -``` - - - -## Content providers -The plugin has the following content providers available: - -### `stixview` - -#### Configuration - -The content provider doesn't support configuration. - -#### Usage - -The content source supports the following parameters in the content blocks: - -```hcl -content stixview { - caption = # optional - gist_id = # optional - height = # optional - show_footer = # optional - show_idrefs = # optional - show_labels = # optional - show_marking_nodes = # optional - show_sidebar = # optional - show_tlp_as_tags = # optional - stix_url = # optional - width = # optional -} -``` diff --git a/docs/plugins/stixview/_index.md b/docs/plugins/stixview/_index.md new file mode 100644 index 00000000..b423022b --- /dev/null +++ b/docs/plugins/stixview/_index.md @@ -0,0 +1,31 @@ +--- +title: blackstork/stixview +weight: 20 +plugin: + name: blackstork/stixview + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/stixview/" +type: docs +--- + +{{< plugin-header "blackstork/stixview" "stixview" "v0.4.0" >}} + +## Installation + +To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: + +```hcl +fabric { + plugin_versions = { + "blackstork/stixview" = ">= v0.4.0" + } +} +``` + + + +## Content providers + +{{< plugin-resources "stixview" "content-provider" >}} \ No newline at end of file diff --git a/docs/plugins/stixview/content-providers/stixview.md b/docs/plugins/stixview/content-providers/stixview.md new file mode 100644 index 00000000..47a0630b --- /dev/null +++ b/docs/plugins/stixview/content-providers/stixview.md @@ -0,0 +1,58 @@ +--- +title: stixview +plugin: + name: blackstork/stixview + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/stixview/" +resource: + type: content-provider +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/stixview" "stixview" "v0.4.0" "stixview" "content provider" >}} + +## Installation + +To use `stixview` content provider, you must install the plugin `blackstork/stixview`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), as shown below: + +```hcl +fabric { + plugin_versions = { + "blackstork/stixview" = ">= v0.4.0" + } +} +``` + +Note the version constraint set for the plugin. + + +#### Configuration + +The content provider doesn't support any configuration parameters. + +#### Usage + +The content provider supports the following execution parameters: + +```hcl +content stixview { + caption = # optional + gist_id = # optional + height = # optional + show_footer = # optional + show_idrefs = # optional + show_labels = # optional + show_marking_nodes = # optional + show_sidebar = # optional + show_tlp_as_tags = # optional + stix_url = # optional + width = # optional +} +``` + diff --git a/docs/plugins/terraform.md b/docs/plugins/terraform/_index.md similarity index 53% rename from docs/plugins/terraform.md rename to docs/plugins/terraform/_index.md index 08bfcb81..1fdb6c21 100644 --- a/docs/plugins/terraform.md +++ b/docs/plugins/terraform/_index.md @@ -1,10 +1,16 @@ --- title: blackstork/terraform weight: 20 +plugin: + name: blackstork/terraform + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/terraform/" type: docs --- -# `blackstork/terraform` plugin +{{< plugin-header "blackstork/terraform" "terraform" "v0.4.0" >}} ## Installation @@ -13,27 +19,12 @@ To install the plugin, add it to `plugin_versions` map in the Fabric global conf ```hcl fabric { plugin_versions = { - "blackstork/terraform" = "=> v0.0.0-dev" + "blackstork/terraform" = ">= v0.4.0" } } ``` -## Data sources - -The plugin has the following data sources available: - -### `terraform_state_local` - -#### Configuration - -The data source doesn't support configuration. -#### Usage - -The data source supports the following parameters in the data blocks: +## Data sources -```hcl -data terraform_state_local { - path = # required -} -``` \ No newline at end of file +{{< plugin-resources "terraform" "data-source" >}} diff --git a/docs/plugins/terraform/data-sources/terraform_state_local.md b/docs/plugins/terraform/data-sources/terraform_state_local.md new file mode 100644 index 00000000..146288ba --- /dev/null +++ b/docs/plugins/terraform/data-sources/terraform_state_local.md @@ -0,0 +1,46 @@ +--- +title: terraform_state_local +plugin: + name: blackstork/terraform + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/terraform/" +resource: + type: data-source +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/terraform" "terraform" "v0.4.0" "terraform_state_local" "data source" >}} + +## Installation + +To use `terraform_state_local` data source, you must install the plugin `blackstork/terraform`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), as shown below: + +```hcl +fabric { + plugin_versions = { + "blackstork/terraform" = ">= v0.4.0" + } +} +``` + +Note the version constraint set for the plugin. + +## Configuration + +The data source doesn't support configuration. + +## Usage + +The data source supports the following parameters in the data blocks: + +```hcl +data terraform_state_local { + path = # required +} +``` \ No newline at end of file diff --git a/docs/plugins/virustotal.md b/docs/plugins/virustotal.md deleted file mode 100644 index fe4930ca..00000000 --- a/docs/plugins/virustotal.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: blackstork/virustotal -weight: 20 -type: docs ---- - -# `blackstork/virustotal` plugin - -## Installation - -To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: - -```hcl -fabric { - plugin_versions = { - "blackstork/virustotal" = "=> v0.0.0-dev" - } -} -``` - -## Data sources - -The plugin has the following data sources available: - -### `virustotal_api_usage` - -#### Configuration - -The data source supports the following configuration parameters: - -```hcl -config data virustotal_api_usage { - api_key = # required -} -``` - -#### Usage - -The data source supports the following parameters in the data blocks: - -```hcl -data virustotal_api_usage { - end_date = # optional - group_id = # optional - start_date = # optional - user_id = # optional -} -``` \ No newline at end of file diff --git a/docs/plugins/virustotal/_index.md b/docs/plugins/virustotal/_index.md new file mode 100644 index 00000000..c51f0988 --- /dev/null +++ b/docs/plugins/virustotal/_index.md @@ -0,0 +1,30 @@ +--- +title: blackstork/virustotal +weight: 20 +plugin: + name: blackstork/virustotal + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/virustotal/" +type: docs +--- + +{{< plugin-header "blackstork/virustotal" "virustotal" "v0.4.0" >}} + +## Installation + +To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: + +```hcl +fabric { + plugin_versions = { + "blackstork/virustotal" = ">= v0.4.0" + } +} +``` + + +## Data sources + +{{< plugin-resources "virustotal" "data-source" >}} diff --git a/docs/plugins/virustotal/data-sources/virustotal_api_usage.md b/docs/plugins/virustotal/data-sources/virustotal_api_usage.md new file mode 100644 index 00000000..946e9cac --- /dev/null +++ b/docs/plugins/virustotal/data-sources/virustotal_api_usage.md @@ -0,0 +1,55 @@ +--- +title: virustotal_api_usage +plugin: + name: blackstork/virustotal + description: "" + tags: [] + version: "v0.4.0" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/virustotal/" +resource: + type: data-source +type: docs +--- + +{{< breadcrumbs 2 >}} + +{{< plugin-resource-header "blackstork/virustotal" "virustotal" "v0.4.0" "virustotal_api_usage" "data source" >}} + +## Installation + +To use `virustotal_api_usage` data source, you must install the plugin `blackstork/virustotal`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{< ref "configs.md#global-configuration" >}}) for more details), as shown below: + +```hcl +fabric { + plugin_versions = { + "blackstork/virustotal" = ">= v0.4.0" + } +} +``` + +Note the version constraint set for the plugin. + +## Configuration + +The data source supports the following configuration parameters: + +```hcl +config data virustotal_api_usage { + api_key = # required +} +``` + +## Usage + +The data source supports the following parameters in the data blocks: + +```hcl +data virustotal_api_usage { + end_date = # optional + group_id = # optional + start_date = # optional + user_id = # optional +} +``` \ No newline at end of file diff --git a/docs/tutorial.md b/docs/tutorial.md new file mode 100644 index 00000000..70e39fb5 --- /dev/null +++ b/docs/tutorial.md @@ -0,0 +1,327 @@ +--- +title: Tutorial +type: docs +weight: 30 +code_blocks_no_wrap: true +--- + +# Tutorial + +This tutorial provides comprehensive guidance on using Fabric and the [Fabric Configuration Language]({{< ref "language" >}}) (FCL) for document generation. We'll systematically cover creating a basic template, incorporating data blocks, applying data filtering and mutation, installing plugins, and rendering text with external content providers. + +## Prerequisites + +To effectively follow this tutorial, ensure you have the following: + +- Fabric CLI [installed]({{< ref "install.md" >}}) and `fabric` CLI command available +- (optional) OpenAI API token + +Throughout this tutorial, the command examples were executed in macOS Sonoma, in `zsh` shell. + +## Hello, Fabric + +Let's start with a straightforward "Hello, Fabric!" template to confirm that everything is configured correctly. + +Create a new `hello.fabric` file and define a simple template: + +```hcl +document "greeting" { + + content text { + text = "Hello, Fabric!" + } + +} +``` + +In this code snippet, the `document.greeting` block defines a template with a single anonymous content block containing the text "Hello, Fabric!" + +To render the document, ensure that Fabric can locate the `hello.fabric` file. Execute `fabric` command in the same directory (or explicitly provide `--source-dir` CLI argument): + +```shell +fabric render document.greeting +``` + +The output should resemble the following: + +```shell +$ fabric render document.greeting +Hello, Fabric! +``` + +## Document title + +Documents typically include titles, and the document block supports the `title` argument as a straightforward method to set a title for a document. + +Enhance the `document.greeting` template by adding a title using the `title` argument: + +```hcl +document "greeting" { + + title = "The Greeting" + + content text { + text = "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`: + +```hcl +content text { + text = "The Greeting" + format_as = "title" +} +``` + +See [the documentation]({{< ref "plugins/builtin/content-providers/text" >}}) for the details about the arguments supported by `text` content provider. +{{< /hint >}} + +The rendered output should now include the document title: + +```markdown +$ fabric render document.greeting +# The Greeting + +Hello, Fabric! +``` + +## Data blocks + +A core feature of the Fabric configuration language is the ability to define data requirements inside templates with the [data blocks]({{< ref "language/data-blocks.md" >}}). The easiest way is to use [`inline`]({{< ref "plugins/builtin/data-sources/inline" >}}) data source that supports free-form data structures. + +Note, you must define `data` blocks on the root level of the `document` block. + +Modify the template in the `hello.fabric` file to include a `data` block and another `content.text` block: + +```hcl +document "greeting" { + + data inline "solar_system" { + planets = [ + "Mercury", "Venus", "Earth", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune" + ] + + moons_count = 146 + } + + title = "The Greeting" + + content text { + text = "Hello, Fabric!" + } + + content text { + query = ".data.inline.solar_system.planets | length" + + text = <<-EOT + There are {{ .query_result }} planets and {{ .data.inline.solar_system.moons_count }} moons in our solar system. + EOT + } + +} +``` + +The content blocks can access and transform the data available with [JQ query](https://jqlang.github.io/jq/manual/) in the [`query`]({{< ref "language/content-blocks.md#generic-arguments" >}}) argument. It's applied to [the context object]({{< ref "language/content-blocks.md#context" >}}) during the evaluation of the block, and the result is stored in the context object under the `query_result` field. + +As you can see, `text` argument value in the new content block is a template string – `content.text` blocks support [Go templates](https://pkg.go.dev/text/template) out-of-the-box. The templates can access the context object, so it's easy to include `query_result` or `moons_count` values from the context. + +The rendered output should now include the new sentence: + +```shell +$ fabric render document.greeting +# The Greeting + +Hello, Fabric! + +There are 8 planets and 146 moons in our solar system. +``` + +## Content providers + +Fabric seamlessly integrates with external APIs for content generation. An excellent example is the utilization of the OpenAI API to dynamically generate text through prompts. + +In scenarios where providing the exact text or a template string for the content block proves challenging or impossible, leveraging generative AI for summarization becomes invaluable. This enables users to dynamically create context-aware text. + +In this tutorial, we will utilize the [`openai_text`]({{< ref "plugins/openai/content-providers/openai_text" >}}) content provider, allowing us to generate text with the OpenAI Language Model (LLM). + +### Installation + +Before using [`openai_text`]({{< ref "plugins/openai/content-providers/openai_text" >}}) content provider, it's necessary to add [`blackstork/openai`]({{< ref "plugins/openai" >}}) plugin as a dependency and install it. + +To achieve this, update the `hello.fabric` file to resemble the following: + +```hcl +fabric { + plugin_versions = { + "blackstork/openai" = ">= 0.4.0" + } +} + +document "greeting" { + + data inline "solar_system" { + planets = [ + "Mercury", "Venus", "Earth", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune" + ] + + moons_count = 146 + } + + title = "The Greeting" + + content text { + text = "Hello, Fabric!" + } + + content text { + query = ".data.inline.solar_system.planets | length" + + text = <<-EOT + There are {{ .query_result }} planets and {{ .data.inline.solar_system.moons_count }} moons in our solar system. + EOT + } + +} +``` + +Here, we added a fully qualified name plugin name `blackstork/openai` to the list of dependencies in the `plugin_versions` argument in [the global configuration]({{< ref "language/configs.md#global-configuration" >}}). + +With the `hello.fabric` file updated, you can install all required plugins with the `fabric install` command: + +```shell +$ fabric install +Mar 11 19:20:10.769 INF Searching plugin name=blackstork/openai constraints=">=v0.4.0" +Mar 11 19:20:10.787 INF Installing plugin name=blackstork/openai version=0.4.0 +$ +``` + +Fabric fetched the `blackstork/openai` plugin release from the plugin registry and installed it in the `./.fabric/` folder. + +### Configuration + +[`openai_text`]({{< ref "plugins/openai/content-providers/openai_text" >}}) content provider requires an OpenAI API key. The key can be set in the provider's configuration block. It's recommended to store credentials and API keys separately from Fabric code, and using the `from_env_variable` function to read the key from the `OPENAI_API_KEY` environment variable. + +The `config` block for the `openai_text` content provider would look like this: + +```hcl +config content openai_text { + api_key = from_env_variable("OPENAI_API_KEY") +} +``` + +Add this block to `hello.fabric` file. + +### Usage + +Lets define the content block that uses `openai_text` content provider: + +```hcl +... + +document "greeting" { + + ... + + content openai_text { + query = "{planet: .data.inline.solar_system.planets[-1]}" + prompt = "Share a fact about the planet specified in the provided data" + } + +} +``` + +A JQ query `"{planet: .data.inline.solar_system.planets[-1]}` in `query` argument fetches the last item from the list (`Neptune`) and creates a new JSON object `{"planet": "Neptune"}`. This object is stored under `query_result` field in the context. `openai_text` content provider combines the `prompt` string with the `query_result` value to create a user prompt for OpenAI API. + +{{< hint note >}} +If you would like to specify a system prompt for OpenAI API, you can set it up in the configuration for `openai_text` provider. See the provider's [documentation]({{< ref "plugins/openai/content-providers/openai_text" >}}) for more configuration options. +{{< /hint >}} + +The complete content of the `hello.fabric` file should look like this: + +```hcl +fabric { + plugin_versions = { + "blackstork/openai" = ">= 0.4" + } +} + +config content openai_text { + api_key = from_env_variable("OPENAI_API_KEY") +} + +document "greeting" { + + data inline "solar_system" { + planets = [ + "Mercury", "Venus", "Earth", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune" + ] + + moons_count = 146 + } + + title = "The Greeting" + + content text { + text = "Hello, Fabric!" + } + + content text { + query = ".data.inline.solar_system.planets | length" + + text = <<-EOT + There are {{ .query_result }} planets and {{ .data.inline.solar_system.moons_count }} moons in our solar system. + EOT + } + + content openai_text { + query = "{planet: .data.inline.solar_system.planets[-1]}" + prompt = "Share a fact about the planet specified in the provided data" + } + +} +``` + +To render the document, `OPENAI_API_KEY` environment variable must be set. A simple way to do that, is to set it for each execution: + +```shell +$ OPENAI_API_KEY="" fabric render document.greeting +... +``` + +{{< hint warning >}} +Remember to replace `` in the CLI command with your OpenAI API key value. +{{< /hint >}} + +The results of the render should look similar to the following: + +```bash +$ OPENAI_API_KEY="" ./fabric render document.greeting +Mar 11 20:39:17.834 INF Loading plugin name=blackstork/openai path=.fabric/plugins/blackstork/openai@0.4.0 +# The Greeting + +Hello, Fabric! + +There are 8 planets and 146 moons in our solar system. + +Neptune is the eighth planet from the Sun in our solar system and is the coldest planet. It has average temperatures of minus 353 degrees Fahrenheit (minus 214 degrees Celsius). +``` + +## Markdown rendering + +Fabric produces Markdown documents that are compatible with various Markdown editors, allowing rendering in formats such as HTML or PDF. It's also possible to copy-paste rich text into the word processors like Microsoft Word or Google Docs. + +An excellent choice for macOS users is [MacDown](https://macdown.uranusjr.com/), an open-source Markdown editor. + +![Rendered template in the MacDown Markdown editor](/images/the-greeting.png "The document in MacDown editor") + +# Next steps + +Congratulations! By completing this tutorial, you've gained a solid understanding of Fabric and its core principles. + +Explore the open-source templates in the [Fabric Templates](https://github.com/blackstork-io/fabric-templates) GitHub repository. You can reuse entire documents or specific blocks in your own templates! + +If you have any questions, feel free to ask in the [Fabric Community Slack](https://fabric-community.slack.com/) and we'll be glad to assist you! diff --git a/tools/docgen/content-provider.md.gotempl b/tools/docgen/content-provider.md.gotempl new file mode 100644 index 00000000..751c3fa1 --- /dev/null +++ b/tools/docgen/content-provider.md.gotempl @@ -0,0 +1,68 @@ +--- +title: {{ .name }} +plugin: + name: {{ .plugin.Name }} + description: "" + tags: [] + version: "{{ .plugin.Version }}" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/{{ .plugin_shortname }}/" +resource: + type: content-provider +type: docs +--- + +{{"{{"}}< breadcrumbs 2 >{{"}}"}} + +{{"{{"}}< plugin-resource-header "{{ .plugin.Name }}" "{{ .plugin_shortname }}" "{{ .plugin.Version }}" "{{ .name }}" "content provider" >{{"}}"}} + +{{ if eq .plugin.Name "blackstork/builtin" -}} +The content provider is built-in, which means it's a part of `fabric` binary. It's available out-of-the-box, no installation required. +{{ else -}} +## Installation + +To use `{{ .name }}` content provider, you must install the plugin `{{ .plugin.Name }}`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{"{{"}}< ref "configs.md#global-configuration" >{{"}}"}}) for more details), as shown below: + +```hcl +fabric { + plugin_versions = { + "{{ .plugin.Name }}" = ">= {{ .plugin.Version }}" + } +} +``` + +Note the version constraint set for the plugin. +{{ end }} + +#### Configuration + +{{ $ctx := . -}} +{{with .content_provider.Config -}} +The content provider supports the following configuration parameters: + +```hcl +config content {{ $ctx.name }} { +{{- range $key, $value := . }} + {{ $key }} = <{{ $value | attrType }}> # {{if $value.Required}}required{{else}}optional{{end}} +{{- end }} +} +``` +{{ else -}} +The content provider doesn't support any configuration parameters. +{{ end }} +#### Usage + +{{with .content_provider.Args -}} +The content provider supports the following execution parameters: + +```hcl +content {{ $ctx.name }} { +{{- range $key, $value := . }} + {{ $key }} = <{{ $value | attrType }}> # {{if $value.Required}}required{{else}}optional{{end}} +{{- end }} +} +``` +{{ else }} +The content provider doesn't define any execution parameters. +{{ end }} diff --git a/tools/docgen/data-source.md.gotempl b/tools/docgen/data-source.md.gotempl new file mode 100644 index 00000000..41c8cee6 --- /dev/null +++ b/tools/docgen/data-source.md.gotempl @@ -0,0 +1,68 @@ +--- +title: {{ .name }} +plugin: + name: {{ .plugin.Name }} + description: "" + tags: [] + version: "{{ .plugin.Version }}" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/{{ .plugin_shortname }}/" +resource: + type: data-source +type: docs +--- + +{{"{{"}}< breadcrumbs 2 >{{"}}"}} + +{{"{{"}}< plugin-resource-header "{{ .plugin.Name }}" "{{ .plugin_shortname }}" "{{ .plugin.Version }}" "{{ .name }}" "data source" >{{"}}"}} + +{{ if eq .plugin.Name "blackstork/builtin" -}} +The data source is built-in, which means it's a part of `fabric` binary. It's available out-of-the-box, no installation required. +{{ else -}} +## Installation + +To use `{{ .name }}` data source, you must install the plugin `{{ .plugin.Name }}`. + +To install the plugin, add the full plugin name to the `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{"{{"}}< ref "configs.md#global-configuration" >{{"}}"}}) for more details), as shown below: + +```hcl +fabric { + plugin_versions = { + "{{ .plugin.Name }}" = ">= {{ .plugin.Version }}" + } +} +``` + +Note the version constraint set for the plugin. +{{ end }} +## Configuration + +{{ $ctx := . -}} +{{ with .data_source.Config -}} +The data source supports the following configuration parameters: + +```hcl +config data {{ $ctx.name }} { +{{- range $key, $value := . }} + {{ $key }} = <{{ $value | attrType }}> # {{if $value.Required}}required{{else}}optional{{end}} +{{- end }} +} +``` +{{- else -}} +The data source doesn't support configuration. +{{- end }} + +## Usage + +{{with .data_source.Args -}} +The data source supports the following parameters in the data blocks: + +```hcl +data {{ $ctx.name }} { +{{- range $key, $value := . }} + {{ $key }} = <{{ $value | attrType }}> # {{if $value.Required}}required{{else}}optional{{end}} +{{- end }} +} +``` +{{- else -}} +The data source doesn't define any execution parameters. +{{- end -}} diff --git a/tools/docgen/main.go b/tools/docgen/main.go index 68fff488..d2dac580 100644 --- a/tools/docgen/main.go +++ b/tools/docgen/main.go @@ -2,7 +2,9 @@ package main import ( _ "embed" + "encoding/json" "fmt" + "log/slog" "os" "path/filepath" "strings" @@ -17,6 +19,7 @@ import ( "github.com/blackstork-io/fabric/internal/graphql" "github.com/blackstork-io/fabric/internal/hackerone" "github.com/blackstork-io/fabric/internal/openai" + "github.com/blackstork-io/fabric/internal/opencti" "github.com/blackstork-io/fabric/internal/postgresql" "github.com/blackstork-io/fabric/internal/splunk" "github.com/blackstork-io/fabric/internal/sqlite" @@ -31,10 +34,166 @@ var ( outputDir string ) -//go:embed markdown.gotempl -var markdownTempl string +//go:embed content-provider.md.gotempl +var contentProviderTemplValue string -var templ *template.Template +var contentProviderTempl *template.Template + +//go:embed data-source.md.gotempl +var dataSourceTemplValue string + +var dataSourceTempl *template.Template + +//go:embed plugin.md.gotempl +var pluginTemplValue string + +var pluginTempl *template.Template + +type PluginResourceMeta struct { + Name string `json:"name"` + Type string `json:"type"` + ConfigParams []string `json:"config_params,omitempty"` + Arguments []string `json:"arguments,omitempty"` +} + +func generateDataSourceDocs(log *slog.Logger, p *plugin.Schema, outputDir string) { + log.Info("Found data sources inside the plugin", "count", len(p.DataSources)) + + dataSourcesDir := filepath.Join(outputDir, "data-sources") + + // Create a directory for plugin's data sources if it doesn't exist + err := os.MkdirAll(dataSourcesDir, 0766) + if err != nil { + log.Error("Can't create a directory", "path", dataSourcesDir) + panic(err) + } + + for name, dataSource := range p.DataSources { + log.Info("Found a data source", "name", name) + docFilename := fmt.Sprintf("%s.md", name) + docPath := filepath.Join(dataSourcesDir, docFilename) + err := renderDataSourceDoc(p, name, dataSource, docPath) + if err != nil { + log.Error("Error while rendering a data source doc", "plugin", p.Name, "dataSource", name) + panic(err) + } + } +} + +func generateContentProviderDocs(log *slog.Logger, p *plugin.Schema, outputDir string) { + log.Info("Found content providers inside the plugin", "count", len(p.ContentProviders)) + + contentProvidersDir := filepath.Join(outputDir, "content-providers") + + // Create a directory for plugin's content providers if it doesn't exist + err := os.MkdirAll(contentProvidersDir, 0766) + if err != nil { + log.Error("Can't create a directory", "path", contentProvidersDir) + panic(err) + } + + for name, contentProvider := range p.ContentProviders { + log.Info("Found a content provider", "name", name) + + docFilename := fmt.Sprintf("%s.md", name) + docPath := filepath.Join(contentProvidersDir, docFilename) + err := renderContentProviderDoc(p, name, contentProvider, docPath) + if err != nil { + log.Error("Error while rendering a content provider doc", "plugin", p.Name, "contentProvider", name) + panic(err) + } + } +} + +func marshalDataSource(name string, ds *plugin.DataSource) PluginResourceMeta { + + var configParams []string + configSpec, ok := ds.Config.(hcldec.ObjectSpec) + if ok && configSpec != nil { + for k := range configSpec { + configParams = append(configParams, k) + } + } + + var arguments []string + argsSpec, ok := ds.Args.(hcldec.ObjectSpec) + if ok && argsSpec != nil { + for k := range argsSpec { + arguments = append(arguments, k) + } + } + return PluginResourceMeta{ + Name: name, + Type: "data-source", + ConfigParams: configParams, + Arguments: arguments, + } +} + +func marshalContentProvider(name string, p *plugin.ContentProvider) PluginResourceMeta { + + var configParams []string + configSpec, ok := p.Config.(hcldec.ObjectSpec) + if ok && configSpec != nil { + for k := range configSpec { + configParams = append(configParams, k) + } + } + + var arguments []string + argsSpec, ok := p.Args.(hcldec.ObjectSpec) + if ok && argsSpec != nil { + for k := range argsSpec { + arguments = append(arguments, k) + } + } + return PluginResourceMeta{ + Name: name, + Type: "content-provider", + ConfigParams: configParams, + Arguments: arguments, + } +} + +func generateMetadataFile(plugins []*plugin.Schema, outputDir string) { + pluginDetails := make([]any, len(plugins)) + + for i, p := range plugins { + + var resources []PluginResourceMeta + + for name, dataSource := range p.DataSources { + resources = append(resources, marshalDataSource(name, dataSource)) + } + for name, contentProvider := range p.ContentProviders { + resources = append(resources, marshalContentProvider(name, contentProvider)) + } + + pluginDetails[i] = map[string]any{ + "name": p.Name, + "version": p.Version, + "shortname": shortname(p.Name), + "resources": resources, + } + } + + jsonData, err := json.MarshalIndent(pluginDetails, "", " ") + if err != nil { + slog.Error("Failed to marshal the plugin details into JSON") + return + } + + pluginDetailsPath := filepath.Join(outputDir, "plugins.json") + file, err := os.Create(pluginDetailsPath) + if err != nil { + panic(err) + } + defer file.Close() + + file.Write(jsonData) + + slog.Info("Plugin details file generated", "path", pluginDetailsPath) +} func main() { // parse flags @@ -42,10 +201,6 @@ func main() { flags.StringVar(&version, "version", "v0.0.0-dev", "version of the build") flags.StringVar(&outputDir, "output", "./dist/docs", "output directory") flags.Parse(os.Args[1:]) - // ensure output directory exists - if err := os.MkdirAll(outputDir, 0o755); err != nil { - panic(err) - } // load all plugins plugins := []*plugin.Schema{ builtin.Plugin(version), @@ -53,6 +208,7 @@ func main() { github.Plugin(version, nil), graphql.Plugin(version), openai.Plugin(version, nil), + opencti.Plugin(version), postgresql.Plugin(version), sqlite.Plugin(version), terraform.Plugin(version), @@ -63,21 +219,81 @@ func main() { } // generate markdown for each plugin for _, p := range plugins { - fp := filepath.Join(outputDir, fmt.Sprintf("%s.md", shortname(p.Name))) - fmt.Printf("Generating '%s': '%s'\n", p.Name, fp) - if err := generate(p, fp); err != nil { + + log := slog.With("plugin", p.Name) + + pluginShortname := shortname(p.Name) + + // Use a shortname as a plugin directory name + pluginOutputDir := filepath.Join(outputDir, pluginShortname) + + // Create a plugin directory if it doesn't exist + err := os.MkdirAll(pluginOutputDir, 0766) + if err != nil { + log.Error("Can't create a plugin directory", "path", pluginOutputDir) + panic(err) + } + + pluginDocPath := filepath.Join(pluginOutputDir, "_index.md") + err = renderPluginDoc(p, pluginDocPath) + if err != nil { + log.Error("Error while rendering a plugin doc", "plugin", p.Name) panic(err) } + + log.Info("Plugin doc rendered", "path", pluginDocPath) + + if len(p.DataSources) != 0 { + generateDataSourceDocs(log, p, pluginOutputDir) + } + + if len(p.ContentProviders) != 0 { + generateContentProviderDocs(log, p, pluginOutputDir) + } } + generateMetadataFile(plugins, outputDir) } -func generate(schema *plugin.Schema, fp string) error { +func renderPluginDoc(pluginSchema *plugin.Schema, fp string) error { f, err := os.Create(fp) if err != nil { return err } defer f.Close() - return templ.Execute(f, schema) + + return pluginTempl.Execute(f, pluginSchema) +} + +func renderContentProviderDoc(pluginSchema *plugin.Schema, contentProviderName string, contentProvider *plugin.ContentProvider, fp string) error { + f, err := os.Create(fp) + if err != nil { + return err + } + defer f.Close() + + var templContext = map[string]any{ + "plugin": pluginSchema, + "plugin_shortname": shortname(pluginSchema.Name), + "name": contentProviderName, + "content_provider": contentProvider, + } + return contentProviderTempl.Execute(f, templContext) +} + +func renderDataSourceDoc(pluginSchema *plugin.Schema, dataSourceName string, dataSource *plugin.DataSource, fp string) error { + f, err := os.Create(fp) + if err != nil { + return err + } + defer f.Close() + + var templContext = map[string]any{ + "plugin": pluginSchema, + "plugin_shortname": shortname(pluginSchema.Name), + "name": dataSourceName, + "data_source": dataSource, + } + return dataSourceTempl.Execute(f, templContext) } func shortname(name string) string { @@ -88,16 +304,24 @@ func shortname(name string) string { return name } +func templateAttrTypeFunc(val hcldec.Spec) string { + switch v := val.(type) { + case *hcldec.AttrSpec: + return v.Type.FriendlyName() + default: + return "unknown" + } +} + func init() { - templ = template.Must(template.New("markdown").Funcs(template.FuncMap{ + contentProviderTempl = template.Must(template.New("content-provider").Funcs(template.FuncMap{ + "attrType": templateAttrTypeFunc, + }).Parse(contentProviderTemplValue)) + dataSourceTempl = template.Must(template.New("data-source").Funcs(template.FuncMap{ + "attrType": templateAttrTypeFunc, + }).Parse(dataSourceTemplValue)) + pluginTempl = template.Must(template.New("plugin").Funcs(template.FuncMap{ + "attrType": templateAttrTypeFunc, "shortname": shortname, - "attrType": func(val hcldec.Spec) string { - switch v := val.(type) { - case *hcldec.AttrSpec: - return v.Type.FriendlyName() - default: - return "unknown" - } - }, - }).Parse(markdownTempl)) + }).Parse(pluginTemplValue)) } diff --git a/tools/docgen/markdown.gotempl b/tools/docgen/markdown.gotempl deleted file mode 100644 index 990ee825..00000000 --- a/tools/docgen/markdown.gotempl +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: {{ if eq .Name "blackstork/builtin" -}}Built-in{{- else -}}{{ .Name }}{{- end }} -{{ if eq .Name "blackstork/builtin" -}}weight: 10{{- else -}}weight: 20{{- end }} -type: docs ---- - -{{ if eq .Name "blackstork/builtin" -}} -# Built-in data sources and content providers -{{- else -}} -# `{{ .Name }}` plugin -{{- end }} - -{{ if eq .Name "blackstork/builtin" -}} -`fabric` binary includes a set of built-in data sources and content providers, available out-of-the-box. -{{ else -}} -## Installation - -To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{"{{"}}< ref "configs.md#global-configuration" >{{"}}"}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: - -```hcl -fabric { - plugin_versions = { - "{{ .Name }}" = "=> {{ .Version }}" - } -} -``` -{{ end }} -{{ $plugin := . -}} - -{{ with .DataSources -}} -## Data sources -{{- if eq $plugin.Name "blackstork/builtin" -}} -{{ else }} - -The plugin has the following data sources available: -{{- end -}} -{{ range $name, $ds := . }} - -### `{{ $name }}` - -#### Configuration - -{{ with $ds.Config -}} -The data source supports the following configuration parameters: - -```hcl -config data {{ $name }} { -{{- range $key, $value := . }} - {{ $key }} = <{{ $value | attrType }}> # {{if $value.Required}}required{{else}}optional{{end}} -{{- end }} -} -``` -{{- else -}} -The data source doesn't support configuration. -{{- end }} - -#### Usage - -{{with $ds.Args -}} -The data source supports the following parameters in the data blocks: - -```hcl -data {{ $name }} { -{{- range $key, $value := . }} - {{ $key }} = <{{ $value | attrType }}> # {{if $value.Required}}required{{else}}optional{{end}} -{{- end }} -} -``` -{{- else -}} -The data source doesn't define any parameters in the `data` block. -{{- end -}} -{{ end -}} -{{ end }} - -{{- with .ContentProviders }} - -## Content providers -{{ if eq $plugin.Name "blackstork/builtin" -}} -{{ else -}} -The plugin has the following content providers available: -{{ end -}} -{{ range $name, $provider := . }} -### `{{ $name }}` - -#### Configuration - -{{with $provider.Config -}} -The content provider supports the following configuration parameters: - -```hcl -config content {{ $name }} { -{{- range $key, $value := . }} - {{ $key }} = <{{ $value | attrType }}> # {{if $value.Required}}required{{else}}optional{{end}} -{{- end }} -} -``` -{{ else -}} -The content provider doesn't support configuration. -{{ end }} -#### Usage - -{{with $provider.Args -}} -The content source supports the following parameters in the content blocks: - -```hcl -content {{ $name }} { -{{- range $key, $value := . }} - {{ $key }} = <{{ $value | attrType }}> # {{if $value.Required}}required{{else}}optional{{end}} -{{- end }} -} -``` -{{ else }} -The content provider doesn't define any parameters in the `content` block. -{{ end }} -{{- end -}} -{{- end -}} diff --git a/tools/docgen/plugin.md.gotempl b/tools/docgen/plugin.md.gotempl new file mode 100644 index 00000000..47dda435 --- /dev/null +++ b/tools/docgen/plugin.md.gotempl @@ -0,0 +1,43 @@ +--- +title: {{ if eq .Name "blackstork/builtin" -}}Built-in{{- else -}}{{ .Name }}{{- end }} +{{ if eq .Name "blackstork/builtin" -}}weight: 10{{- else -}}weight: 20{{- end }} +plugin: + name: {{ .Name }} + description: "" + tags: [] + version: "{{ .Version }}" + source_github: "https://github.com/blackstork-io/fabric/tree/main/internal/{{ shortname .Name }}/" +type: docs +--- + +{{"{{"}}< plugin-header "{{ .Name }}" "{{ shortname .Name }}" "{{ .Version }}" >{{"}}"}} + +{{ if eq .Name "blackstork/builtin" -}} +`fabric` binary includes a set of built-in data sources and content providers, available out-of-the-box. +{{ else -}} +## Installation + +To install the plugin, add it to `plugin_versions` map in the Fabric global configuration block (see [Global configuration]({{"{{"}}< ref "configs.md#global-configuration" >{{"}}"}}) for more details), with a version constraint restricting which available versions of the plugin the codebase is compatible with: + +```hcl +fabric { + plugin_versions = { + "{{ .Name }}" = ">= {{ .Version }}" + } +} +``` +{{ end }} + +{{ $plugin := . -}} + +{{ with .DataSources -}} +## Data sources + +{{"{{"}}< plugin-resources "{{ shortname $plugin.Name }}" "data-source" >{{"}}"}} +{{ end }} + +{{- with .ContentProviders }} +## Content providers + +{{"{{"}}< plugin-resources "{{ shortname $plugin.Name }}" "content-provider" >{{"}}"}} +{{- end -}}