Readmix (readmix v0.8.0)

Copy Markdown

Readmix is a tool for generating and maintaining documentation with dynamic content.

It allows you to embed special tags in your markdown or other text files that will be processed and replaced with generated content.

Basic Usage

# Create a new Readmix instance
rdmx = Readmix.new([])

# Update a file containing Readmix blocks
Readmix.update_file(rdmx, "README.md")

Block Format

Readmix blocks are defined in HTML comments with a special rdmx prefix:

<!-- rdmx my_namespace:my_action param1:"value1" param2:$my_var -->
This content will be replaced by the generator.
<!-- rdmx my_namespace:my_action -->

Configuration

You can configure Readmix with custom generators, variables, and scope modules:

Readmix.new(
  generators: %{my_namespace: MyGeneratorModule},
  vars: %{my_var: "hello"},
  env: [MyScope | Readmix.default_scopes()]
)

Summary

Types

block()
t()

Functions

blocks_to_iodata(rdmx, blocks)

Renders a list of preprocessed blocks into iodata.

default_backup_directory()

Returns the default backup directory for updated files.

default_scopes()

Returns the default scopes used for built-in generators.

format_error(e)

Returns a human-readable message for an error returned by Readmix functions.

new(opts)

Creates a new Readmix instance from the given options.

parse_string(string, source_path \\ nil)

Parses a string into a list of blocks without rendering them.

transform_string(rdmx, string, opts \\ [])

Transforms a string, replacing the content of its Readmix blocks, and returns the result as a binary.

transform_string_to_iodata(rdmx, string, opts \\ [])

Like transform_string/3 but returns the result as iodata instead of a binary.

update_file(rdmx, path)

Transforms the file at the given path in place, replacing the content of its Readmix blocks.

Types

block()

@type block() :: Readmix.Blocks.Generated.t() | Readmix.Blocks.Text.t()

t()

@type t() :: %Readmix{
  backup_fun: function(),
  resolver: function(),
  vars: %{optional(atom()) => term()}
}

Functions

blocks_to_iodata(rdmx, blocks)

Renders a list of preprocessed blocks into iodata.

Returns {:ok, iodata} or {:error, reason}.

default_backup_directory()

Returns the default backup directory for updated files.

Readmix will append the otp_app name to the path so it is safe to use the same directory for multiple applications.

default_scopes()

Returns the default scopes used for built-in generators.

If you need to configure your own scopes but want to use default Readmix scopes as well, include these in the configuration:

# config/dev.exs
import Config

config :readmix,
  scopes: [MyScope1, MyScope2 | Readmix.default_scopes()]

format_error(e)

Returns a human-readable message for an error returned by Readmix functions.

new(opts)

Creates a new Readmix instance from the given options.

Options

  • :generators - a map of %{namespace => module} defining the generators available to blocks. Defaults to the application configuration, falling back to the built-in generators.
  • :vars - a map of variables made available to blocks. Takes precedence over variables provided by scope modules.
  • :scopes - a list of scope modules providing variables. Defaults to the application configuration, falling back to default_scopes/0.
  • :backup? - whether to back up files before updating them. Defaults to true.
  • :backup_dir - the root directory used to store backups. Defaults to default_backup_directory/0.

parse_string(string, source_path \\ nil)

Parses a string into a list of blocks without rendering them.

The optional source_path is used to report the file name in parse error messages. Returns {:ok, blocks} or {:error, reason}.

transform_string(rdmx, string, opts \\ [])

Transforms a string, replacing the content of its Readmix blocks, and returns the result as a binary.

Accepts a :source_path option used to report the file name in error messages. Returns {:ok, binary} or {:error, reason}.

transform_string_to_iodata(rdmx, string, opts \\ [])

Like transform_string/3 but returns the result as iodata instead of a binary.

Returns {:ok, iodata} or {:error, reason}.

update_file(rdmx, path)

Transforms the file at the given path in place, replacing the content of its Readmix blocks.

Unless backups are disabled, a copy of the original file is written before the file is overwritten. Returns :ok or {:error, reason}.