nimble_publisher

# NimblePublisher

[Online Documentation](https://hexdocs.pm/nimble_publisher).

<!-- MDOC !-->

`NimblePublisher` is a minimal filesystem-based publishing engine with Markdown support and
code highlighting.

```elixir
use NimblePublisher,
  build: Article,
  from: Application.app_dir(:app_name, "priv/articles/**/*.md"),
  as: :articles,
  highlighters: [:makeup_elixir, :makeup_erlang]
```

The example above will get all articles in the given directory,
call `Article.build/3` for each article, passing the filename,
the metadata, and the article body, and define a module attribute
named `@articles` with all built articles returned by the
`Article.build/3` function.

Each article in the articles directory must have the format:

    %{
      title: "Hello world"
    }
    ---
    Body of the "Hello world" article.

    This is a *markdown* document with support for code highlighters:

    ```elixir
    IO.puts "hello world"
    ```

## Options

  * `:build` - the name of the module that will build each entry

  * `:from` - a wildcard pattern where to find all entries. Files with the
    `.md`, `.markdown`, or `.livemd` extension will be converted to HTML with
    `MDExNative`. Other files will be kept as is.

  * `:as` - the name of the module attribute to store all built entries

  * `:comrak_options` - a keyword list of options accepted by
    [`MDExNative.Comrak.markdown_to_html`](https://mdex-native.hexdocs.pm/MDExNative.Comrak.html#markdown_to_html/2)
    to customize Markdown rendering. The default options enable GitHub
    Flavored Markdown and assume you are rendering trusted content,
    as `NimblePublisher` is designed to render your own articles:

    ```elixir
    [
      extension: [table: true, autolink: true, strikethrough: true],
      render: [hardbreaks: false, unsafe: true]
    ]
    ```

  * `:highlighters` - which `Makeup` syntax highlighters to use.
    See "Syntax highlighting" section below for more information.

  * `:parser` - custom module with a `parse/2` function that receives the file path
    and content as params. See [Custom parser](#module-custom-parser) for more details.

  * `:html_converter` - custom module with a `convert/4` function that receives the
    file path, body, and attributes of the markdown file, as well as all options
    as params. See [Custom HTML converter](#module-custom-html-converter) for more details.

## Examples

Let's see a complete example. First add `nimble_publisher` with
the desired highlighters as a dependency:

    def deps do
      [
        {:nimble_publisher, "~> 2.1", runtime: false}
      ]
    end

In this example, we are building a blog. Each post stays in the
"posts" directory with the format:

    /posts/YEAR/MONTH-DAY-ID.md

A typical blog post will look like this:

    # /posts/2020/04-17-hello-world.md
    %{
      title: "Hello world!",
      author: "José Valim",
      tags: ~w(hello),
      description: "Let's learn how to say hello world"
    }
    ---
    This is the