@import template.nml
%<make_doc({}, "Getting Started", "Getting Started")>%

#{building_nml} Building NML

You need at least the nightly version of rustc to compile NML.
Instruction for your operating system can be found on [Rust's website](https://forge.rust-lang.org/infra/other-installation-methods.html).
You'll also need liblua 5.4 installed. You can then move the `nml` executable in `target/release/nml` into your `\$PATH`

``cargo build --bin nml`` or for release mode: ``cargo build --release --bin nml``
*(Note: The release build binary is much smaller than the debug build one)*

# Building your first document

 * ``nml -i input.nml -o output.html``

# Using the cache

NML relies on sqlite to keep a cache of pre-compiled elements that take a long time to process (e.g $|[kind=inline] \LaTeX|$).
To enable caching, use option `-d` with a path: ``-d cache.db``. You can reuse the same cache for multiple documents and benefit from cached elements.
Note that in directory-processing mode, a cache is required so that only modified ``.nml`` files get reprocessed.

**Elements that will use the cache:**
 * All $|[kind=inline] \LaTeX|$ elements
 (*NOTE: Upon modification of the $|[kind=inline] \LaTeX|$ environment, they will be reprocessed, see &{#tex_cache}[caption=TeX Cache] for more information*)
 * All Graphviz elements
 * All code blocks

# Directory-Processing mode

To use directory-processing mode, you need to pass an input directory and an output directory. Directory-processing mode requires that you use a database, so that it knows which documents have already been compiled. If the output directory doesn't exist, it will be automatically created.

Compiling the docs: 
``Plain Text
nml -i docs -o docs_out -d cache.db
``

If you modify an ``Plain Text,@import``ed file, you will need to use the ``--force-rebuild`` option, as NML currently doesn't track which files are imported by other files.

# Building the Language Server

NML comes with it's own language server, ready to be used in any LSP-compatible text editor, such as NeoVim.

Build it by using the following command: ``cargo build --bin nmlls`` or for release mode: ``cargo build --release --bin nmlls``
*(Note: The release build binary is much smaller than the debug build one)*

You should move the language server somewhere in your ``$PATH``.

##* Integrating the LSP

Below is a list of integration steps the language server in various editors.

###* NeoVim

The first step is to add the `.nml` extension to NeoVim, so it is recognized:
``Lua
vim.filetype.add({
	pattern = {
		['.*%.nml'] = 'nml',
	},
})
``

Then you need to register the language server in NeoVim. I recommend the ``lsp-zero`` plugin for that purpose:
``Lua
{
	"VonHeikemen/lsp-zero.nvim",
	config = function()
		local lsp_zero = require('lsp-zero')

		lsp_zero.on_attach(function(client, bufnr)
			lsp_zero.default_keymaps({buffer = bufnr})
		end)

		lsp_zero.new_client({
			name = 'nmlls',
			cmd = {'<PATH TO BINARY IF NOT IN $PATH/>nmlls'},
			filetypes = {'nml'},
		})
	end,
}
``