143 lines
3.8 KiB
Markdown
143 lines
3.8 KiB
Markdown
# luma_markdown
|
|
|
|
[](https://hex.pm/packages/luma_markdown)
|
|
[](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>.
|