🌋 Igneous-md

The simple and lightweight markdown framework / viewer written in rust

Igneous-md is a gfm compatible markdown viewer and viewer framework with a focus of staying lightweight and extensible

Features

• Syntax highlighting similar to GitHub using highlight.js
• Standalone markdown viewer outside browser
• Switching of stylesheets on the fly
• Ability to add custom CSS
• Export generated HTML
• Works offline

To-do

• Write e2e tests (and benchmarks with hyperfine?)

• Create packages

• Allow multiple running instances at the same time on different docs

• Add change streaming API

  • Editor integration either via plugin

• Fix bug relating to multi line GFM notes

• Add github theme closer to github itself (limit width and center content)

• Optimize performance

  • Fix slow shutdown times

Installation

NixOS

If your system uses nix flakes you can do the following:

# flake.nix
inputs = {
    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";

    igneous-md = {
      url = "github:DOD-101/igneous-md"; # or /ref/tags/0.3.0 to pin a version
      inputs.nixpkgs.follows = "nixpkgs";
    };
}

and then

# configuration.nix
{
    inputs,
    ...
}:
{
    environment.systemPackages = [
        inputs.igneous-md.packages."${pkgs.stdenv.hostPlatform.system}".igneous-md-release
    ];
}

Important

This will build the project from source

Via Cargo

cargo install igneous-md

Important

This will build the project from source (see build dependencies)

You must also install webkit-gtk 2.3x+.

Building from source

1. Clone the repo git clone https://github.com/DOD-101/igneous-md.git

2. Install the following build dependencies:

   • rust 1.89+
   • gtk4 (also a runtime dependency)
   • webkit-gtk 2.3x+ (also a runtime dependency)
   • esbuild

   Arch Linux

   sudo pacman -Syu gtk4 webkitgtk-6.0 base-devel

   Ubuntu

   sudo apt update && apt install libgtk-4-dev libwebkitgtk-6.0-dev build-essential libssl-dev

   [!NOTE] Feel free to add your distro here! PRs welcome!

3. Run cargo build --release

4. Finally run cargo install --path crates/igneous-md

Usage

igneous-md view path/to/file.md

FAQ

Or at least questions I think people could ask

1. How do I view my markdown in the browser?

   Simply pass the --browser flag. For all options run igneous-md --help

2. How can I change the order of color schemes?

   Prefix the css file names with numbers e.g:

   00_github-dark.css
   01_github-light.css
   

Configuration

To get started run igneous-md generate-config (will run by automatically if you view a file without the config dir ~/.config/igneous-md/)

Layout

# in ~/.config/igneous-md/

css # general styling
├── github-markdown-dark.css
├── github-markdown-light.css
└── hljs # codeblocks
    ├── github-dark.css
    └── github-light.css

Note

Config generation is only available if compiled with --features generate_config (a default feature)

Keybindings

Key	Description
c	Go to next color scheme
C	Go to previous color scheme
e	Export html
hjkl	Vim bindings for moving

Neovim Integration

This allows to to launch igneous-md directly from your editor on the current buffer

local job_id = -1
vim.keymap.set("n", "gm", function()
	if job_id ~= -1 then
		vim.fn.jobstop(job_id)
	end
	local current_buffer_path = vim.fn.expand("%")
	job_id = vim.fn.jobstart({ "igneous-md", "view", current_buffer_path })
end, {})

Converting md to html

igneous-md convert <PATH>

A markdown viewer Framework?

Yes. It's simpler than it sounds.

Since igneous-md works by using a server in the background and then communicates with the built-in viewer, as well as the browser, using https and websockets anyone could use this to write their own viewer.

The benefits of this being you receive all of the hot-reloading and conversion from md to html for free, while having full freedom to implement your viewer however they you like.

The only real limitation on this is what the websocket json-protocol is written to support. (PRs welcome)

This aspect of igneous-md is still experimental, but if you already want to get started check out ./crates/igneous-md/src/ws/msg.rs and have a look at what is possible right now.

If you want to only use igneous-md for this be sure to disable the viewer cargo feature.

Attribution

Many thanks to all the people, who have created/contributed to technology used in the creation this project.

GitHub for their markdown styling and markdown-alert icons.

License

This project is licensed under either of

• Apache License, Version 2.0
• MIT License

at your option.