litlua

README

LitLua v0.0.1

LitLua is a literate programming tool inspired by Emacs designed to support better formating of lua based configuration. It enables you to write and maintain well-documented Lua configurations by transforming literate Markdown docs into executable Lua code.

🚨 This is a very early work in progress, and not truly ready to handle all your configuration needs yet! 🚨

Until v1, things will break and change until the DX is agreed :)

Features

• 📝 Markdown-Based: Write your configurations in familiar Markdown format
• 🔍 Code Block Extraction: Automatically extracts and processes Lua code blocks
• 💾 Redundancy Precautions: Automatically creates backups of configuration files before overwriting
• 🛠 Simple CLI Interface: Easy to use command-line tool

Why?

After spending some time with Emacs, I could see the value of having litterate configurations for more than just the emacs eco system - configurations being just a readable 'pretty' markdown file, that will be 'transpiled' into the expected format!

For now its a simply extracter of lua source code but future versions will include syntax checking, and other features to make it a more complete tool.

Check out Examples for a small showcase of what LitLua is about.

I've re-written some of kickstart.nvim in markdown and used LitLua to generate the lua files, you can see the same for an example wezterm config. *.lua is the transpiled file, *.md is the markdown source.

Roadmap

• Basic Markdown to Lua conversion to SFO
• Single file to multiple file output (master file, into multiple configuration .lua files)
• Hot swapping configuration management
• Built in lua LSP support (linter, formatter, etc)
• 'Tagging' of code blocks for easy reference
• Watch mode for live updating of configuration files

Generally the idea is this should seamlessly integrate into existing lua based configuration setups, such as Neovim, and work alongside existing lua files.

Installation

Install via Go

Assuming you have go installed - https://go.dev/doc/install

go install github.com/jwtly10/litlua/cmd/litlua@latest

Build from source

git clone https://github.com/jwtly10/litlua.git
go build -o litlua cmd/litlua/main.go
# Move the binary to your PATH  
mv litlua /usr/local/bin  

More installation options will be available in the future.

Usage

Basic usage:

Converts markdown document to lua file:

litlua <your_configuration_file_with_lua_src.md>

Enable debug logging during conversion:

litlua -debug <your_configuration_file_with_lua_src.md>

File Format

LitLua processes Markdown files (.md) containing Lua code blocks. Here's an example:

<!-- @pragma output: init.lua -->

# Neovim Telescope Configuration

Our telescope setup with detailed explanations.

```lua
require('telescope').setup({
    defaults = {
        mappings = {
            i = {
                ['<C-u>'] = false,
                ['<C-d>'] = false,
            },
        },
    },
})
```

This configures the basic telescope behavior. Let's add some keymaps:

```lua
-- File browsing
vim.keymap.set('n', '<leader>ff', 
    require('telescope.builtin').find_files)

-- Live grep
vim.keymap.set('n', '<leader>fg', 
    require('telescope.builtin').live_grep)
```

The tool will:

1. Parse the Markdown document
2. Extract pragma directives at the top of the file, such as output:init.lua
3. Extract Lua code blocks
4. Generate a clean Lua file with all the code to the output file init.lua
5. Create a backup of any existing output file

Output

LitLua generates a single Lua file containing all the extracted code blocks, maintaining their original order as specified in the Markdown source.

Configuration

Output Path Resolution

By default, LitLua will generate the output file in the same directory as the input file, with a .lua extension. You can customize the output path using pragmas at the start your document:

NOTE: The file path will ALWAYS be relative to the input file

<!-- @pragma output: init.lua -->

# My Neovim Configuration
...

Development

Setup locally

git clone https://github.com/jwtly10/litlua
go run ./cmd/litlua/main.go ./examples/kickstart.nvim/kickstart_configuration.md

You will see a newly generated file in ./examples/kickstart.nvim/output.lua

Running Tests

go test ./...

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

• Constants
• func MustAbs(path string) string
• func ResolveOutputPath(mdPath string, pragma Pragma) (string, error)
• type BackupManager
  • func NewBackupManager(path string) *BackupManager
  • func (bm *BackupManager) CreateBackup() (backupPath string, err error)
• type CodeBlock
• type Document
• type MetaData
• type Parser
  • func NewParser() *Parser
  • func (p *Parser) ParseMarkdownDoc(r io.Reader, md MetaData) (*Document, error)
• type Pragma
• type PragmaKey
• type Writer
  • func NewWriter(output io.Writer) *Writer
  • func (w *Writer) Write(doc *Document, now time.Time) error

Constants

const CLI_VERSION = "v0.0.1"

Functions

func MustAbs

func MustAbs(path string) string

func ResolveOutputPath

func ResolveOutputPath(mdPath string, pragma Pragma) (string, error)

ResolveOutputPath determines the final output path from the input markdown source path

Types

type BackupManager

type BackupManager struct {
	// contains filtered or unexported fields
}

BackupManager is a helper struct to manage backups of output files

This is a short term solution to ensuring that the output file is not overwritten by accident.

func NewBackupManager

func NewBackupManager(path string) *BackupManager

func (*BackupManager) CreateBackup

func (bm *BackupManager) CreateBackup() (backupPath string, err error)

CreateBackup creates a backup of the output file if it already exists

Returns the path to the backup file, or an empty string if no backup was created

type CodeBlock

type CodeBlock struct {
	// The code that was parsed from the markdown source
	Code string
	// The original markdown source code file where the code block extracted from
	Source string
}

type Document

type Document struct {
	// Metadata about the source file
	Metadata MetaData
	// Document-level pragmas controlling extraction options
	Pragmas Pragma
	// The extracted code blocks
	Blocks []CodeBlock
}

Document represents a parsed markdown document containing pragmas and code blocks, and any other required metadata about the source file

type MetaData

type MetaData struct {
	// The source file path
	Source string
}

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

func NewParser

func NewParser() *Parser

func (*Parser) ParseMarkdownDoc

func (p *Parser) ParseMarkdownDoc(r io.Reader, md MetaData) (*Document, error)

ParseMarkdownDoc parses a markdown document into its constituent parts see [TODO](TODO) for more information on the structure of the document

type Pragma

type Pragma struct {
	// The lua file output directory, relative to the source markdown file
	Output string
	// Internal flag for additional debugging output
	Debug bool
}

type PragmaKey

type PragmaKey string

const (
	PragmaOutput PragmaKey = "output"
	PragmaDebug  PragmaKey = "debug"
)

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

func NewWriter

func NewWriter(output io.Writer) *Writer

func (*Writer) Write

func (w *Writer) Write(doc *Document, now time.Time) error

Write writes a parsed Markdown Document to the configured output writer