# luma_markdown

[![Package Version](https://img.shields.io/hexpm/v/luma_markdown)](https://hex.pm/packages/luma_markdown)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/luma_markdown/)

`luma_markdown` converts Luma markup to Markdown. It can read a file or consume
all of its input from standard input.

## Standalone executable

Gleam can package the Erlang version of the program as an escript. An escript
is one executable file containing the compiled program and its dependencies.
The target system must still have a compatible Erlang/OTP installation with
`escript` on `PATH`.

From the project directory, run:

```sh
gleam export escript
chmod +x luma_markdown
```

This creates the single executable `./luma_markdown`. Re-run the export
command after changing the source. To use a different filename, rename the
generated file:

```sh
mv luma_markdown luma-md
```

Pass a file path as the only argument:

```sh
./luma_markdown input.luma
```

Or pipe content into it. The command receiving the pipe must come last:

```sh
echo "#1 A heading" | ./luma_markdown
cat input.luma | ./luma_markdown
```

When using a shell with history expansion (such as interactive zsh), use
single quotes or `printf` for input beginning with `!`:

```sh
printf '%s\n' '!4 emphasized text' | ./luma_markdown
```

With no arguments, the executable reads until standard input reaches EOF and
writes the resulting Markdown to standard output.

### ARM builds

The escript contains portable BEAM bytecode, so the same file can work on
x86, ARM64, and ARM32. It is not, however, a self-contained native executable:
the target still needs Erlang/OTP. If the ARM system cannot have anything
installed, this built-in export is not sufficient.

```sh
gleam export escript
./luma_markdown input.luma
```

For a no-install distribution, produce one bundled native artifact per
architecture (for example, an x86_64 Linux artifact and an ARM64 Linux
artifact). A native executable cannot run on both instruction sets. This
repository uses [Queso](https://github.com/jtdowney/queso) to bundle the
Erlang runtime and cross-compile the native launcher.

Install Queso and Zig once on the build machine:

```sh
cargo install --locked queso
cargo install cargo-zigbuild
# Install Zig from https://ziglang.org/download/
# Install Rust through https://rustup.rs (the build script adds the targets)
```

On Arch Linux, the Rust toolchain manager can be installed with:

```sh
sudo pacman -S rustup
rustup default stable
```

Then build both self-contained binaries with one command:

```sh
./scripts/build-linux-binaries.sh
```

The results are:

```text
./luma_markdown-linux-x86_64
./luma_markdown-linux-arm64
```

Copy the matching file to a Linux system and run it directly. The destination
does not need Erlang, Gleam, Zig, or Queso.

### CI artifacts

Every push runs the native build in Gitea Actions after formatting succeeds.
The workflow uploads two downloadable artifacts:

- `luma_markdown-linux-x86_64`
- `luma_markdown-linux-arm64`

Download the artifact matching the destination machine, make it executable if
necessary, and run it directly.

## Neovim preview

The working preview configuration is also included in
[`examples/neovim_luma_preview.lua`](examples/neovim_luma_preview.lua). Copy it
into your Neovim configuration or source it with:

```lua
dofile(vim.fn.getcwd() .. "/examples/neovim_luma_preview.lua")
```

The snippet looks for `luma_markdown` on `PATH`. To use the executable in this
repository directly, set its path before starting Neovim:

```sh
export LUMA_MARKDOWN_BIN="$PWD/luma_markdown"
```

It registers the `:LumaPreview` command and automatically refreshes the
preview for `*.luma` files.

## Development

```sh
gleam run -- input.luma  # Run from the Gleam toolchain
gleam test               # Run the tests
```

Further documentation can be found at <https://hexdocs.pm/luma_markdown>.