Example
The following is an example of using the library to document the programs.neovim options from NixOS.
Base files
This document is created simply by loading the Vue component with the data from the loader. Please read the documentation.
<!-- index.md -->
## Title
Some text
<script setup>
import { data } from "./nixos.data.js";
import { RenderDocs } from "easy-nix-documentation";
</script>
## Options
<RenderDocs :options="data" />// nixos.data.ts
import { dirname } from 'node:path'
import { fileURLToPath } from 'node:url'
import { loadOptions, stripNixStore } from "easy-nix-documentation/loader"
export default {
async load() {
const __dirname = dirname(fileURLToPath(import.meta.url));
return await loadOptions(`-f ${__dirname}/example.nix optionsJSON`, {
include: [/programs\.neovim\.*/],
mapDeclarations: declaration => {
const relDecl = stripNixStore(declaration);
return `<a href="http://github.com/NixOS/nixpkgs/tree/nixos-unstable/${relDecl}"><${relDecl}></a>`
},
})
}
}# example.nix
let
pkgs = import <nixpkgs> { };
nixos = import <nixpkgs/nixos> {
configuration = { };
};
in
pkgs.nixosOptionsDoc {
inherit (nixos) options;
}Neovim Options
programs.neovim.configure
Generate your init file from your list of plugins and custom commands.
Neovim will then be wrapped to load nvim -u /nix/store/«hash»-vimrc
attribute set{ }{
customRC = ''
" here your custom configuration goes!
'';
packages.myVimPackage = with pkgs.vimPlugins; {
# loaded on launch
start = [ fugitive ];
# manually loadable by calling `:packadd $plugin-name`
opt = [ ];
};
}programs.neovim.defaultEditor
When enabled, installs neovim and configures neovim to be the default editor using the EDITOR environment variable.
programs.neovim.enable
Whether to enable Neovim.
When enabled through this option, Neovim is wrapped to use a
configuration managed by this module. The configuration file in the
user's home directory at ~/.config/nvim/init.vim is no longer
loaded by default.
programs.neovim.package
The neovim-unwrapped package to use.
programs.neovim.runtime
Set of files that have to be linked in runtime.
attribute set of (submodule){ }{ "ftplugin/c.vim".text = "setlocal omnifunc=v:lua.vim.lsp.omnifunc"; }programs.neovim.runtime.<name>.enable
Whether this runtime directory should be generated. This option allows specific runtime files to be disabled.
programs.neovim.runtime.<name>.source
Path of the source file.
programs.neovim.runtime.<name>.target
Name of symlink. Defaults to the attribute name.
programs.neovim.runtime.<name>.text
Text of the file.
null or strings concatenated with "\n"nullprograms.neovim.viAlias
Symlink vi to {command}nvim binary.
programs.neovim.vimAlias
Symlink vim to {command}nvim binary.
programs.neovim.withNodeJs
Enable Node provider.
programs.neovim.withPython3
Enable Python 3 provider.
programs.neovim.withRuby
Enable Ruby provider.
Rsnapshot Options
services.rsnapshot.cronIntervals
Periodicity at which intervals should be run by cron. Note that the intervals also have to exist in configuration as retain options.
attribute set of string{ }{
daily = "50 21 * * *";
hourly = "0 * * * *";
}services.rsnapshot.enable
Whether to enable rsnapshot backups.
booleanfalsetrueservices.rsnapshot.enableManualRsnapshot
Whether to enable manual usage of the rsnapshot command with this module.
services.rsnapshot.extraConfig
rsnapshot configuration option in addition to the defaults from rsnapshot and this module.
Note that tabs are required to separate option arguments, and directory names require trailing slashes.
The "extra" in the option name might be a little misleading right now, as it is required to get a functional configuration.
strings concatenated with "\n"""''
retains hourly 24
retain daily 365
backup /home/ localhost/
''Xmonad Options
services.xserver.windowManager.xmonad.config
Configuration from which XMonad gets compiled. If no value is specified, a vanilla xmonad binary is put in PATH, which will attempt to recompile and exec your xmonad config from $HOME/.xmonad. This setup is then analogous to other (non-NixOS) linux distributions.
If you do set this option, you likely want to use "launch" as your
entry point for xmonad (as in the example), to avoid xmonad's
recompilation logic on startup. Doing so will render the default
"mod+q" restart key binding dysfunctional though, because that attempts
to call your binary with the "--restart" command line option, unless
you implement that yourself. You way mant to bind "mod+q" to
(restart "xmonad" True) instead, which will just restart
xmonad from PATH. This allows e.g. switching to the new xmonad binary
after rebuilding your system with nixos-rebuild.
For the same reason, ghc is not added to the environment when this
option is set, unless {option}enableConfiguredRecompile is
set to true.
If you actually want to run xmonad with a config specified here, but
also be able to recompile and restart it from a copy of that source in
$HOME/.xmonad on the fly, set {option}enableConfiguredRecompile
to true and implement something like "compileRestart"
from the example.
This should allow you to switch at will between the local xmonad and
the one NixOS puts in your PATH.
null or absolute path or stringnull''
import XMonad
import XMonad.Util.EZConfig (additionalKeys)
import Control.Monad (when)
import Text.Printf (printf)
import System.Posix.Process (executeFile)
import System.Info (arch,os)
import System.Environment (getArgs)
import System.FilePath ((</>))
compiledConfig = printf "xmonad-%s-%s" arch os
myConfig = defaultConfig
{ modMask = mod4Mask -- Use Super instead of Alt
, terminal = "urxvt" }
`additionalKeys`
[ ( (mod4Mask,xK_r), compileRestart True)
, ( (mod4Mask,xK_q), restart "xmonad" True ) ]
compileRestart resume = do
dirs <- asks directories
whenX (recompile dirs True) $ do
when resume writeStateToFile
catchIO
( do
args <- getArgs
executeFile (cacheDir dirs </> compiledConfig) False args Nothing
)
main = getDirectories >>= launch myConfig
--------------------------------------------
{- For versions before 0.17.0 use this instead -}
--------------------------------------------
-- compileRestart resume =
-- whenX (recompile True) $
-- when resume writeStateToFile
-- *> catchIO
-- ( do
-- dir <- getXMonadDataDir
-- args <- getArgs
-- executeFile (dir </> compiledConfig) False args Nothing
-- )
--
-- main = launch myConfig
--------------------------------------------
''services.xserver.windowManager.xmonad.enable
Whether to enable xmonad.
booleanfalsetrueservices.xserver.windowManager.xmonad.enableConfiguredRecompile
Enable recompilation even if {option}config is set to a
non-null value. This adds the necessary Haskell dependencies (GHC with
packages) to the xmonad binary's environment.
booleanfalseservices.xserver.windowManager.xmonad.enableContribAndExtras
Enable xmonad-{contrib,extras} in Xmonad.
booleanfalseservices.xserver.windowManager.xmonad.extraPackages
Extra packages available to ghc when rebuilding Xmonad. The
value must be a function which receives the attrset defined
in {var}haskellPackages as the sole argument.
function that evaluates to a(n) list of packageself: []haskellPackages: [
haskellPackages.xmonad-contrib
haskellPackages.monad-logger
]services.xserver.windowManager.xmonad.ghcArgs
Command line arguments passed to the compiler (ghc) invocation when xmonad.config is set.
list of string[ ]services.xserver.windowManager.xmonad.haskellPackages
haskellPackages used to build Xmonad and other packages.
This can be used to change the GHC version used to build
Xmonad and the packages listed in
{var}extraPackages.
attribute setpkgs.haskellPackagespkgs.haskell.packages.ghc810services.xserver.windowManager.xmonad.xmonadCliArgs
Command line arguments passed to the xmonad binary.
list of string[ ]Test Options
test.extraLuaPackages
A function which returns a list of extra needed lua packages
function that evaluates to a(n) list of package<function>ps: [ ps.jsregexp ]