luma--markdown/README.md

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:

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:

mv luma_markdown luma-md

Pass a file path as the only argument:

./luma_markdown input.luma

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

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 !:

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.

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 to bundle the Erlang runtime and cross-compile the native launcher.

Install Queso and Zig once on the build machine:

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:

sudo pacman -S rustup
rustup default stable

Then build both self-contained binaries with one command:

./scripts/build-linux-binaries.sh

The results are:

./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 binary build uses the prebuilt jaypoch/luma-markdown-builder:latest image, which contains Gleam, Rust, rustup, Zig, Queso, and cargo-zigbuild. The image definition is in Dockerfile.luma-builder.

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. Copy it into your Neovim configuration or source it with:

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:

export LUMA_MARKDOWN_BIN="$PWD/luma_markdown"

It registers the :LumaPreview command and automatically refreshes the preview for *.luma files. Conversion runs asynchronously and is debounced while typing, so a slow converter does not block Neovim input; an older conversion is discarded when newer buffer contents are available.

Development

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.