diff --git a/neovim-basics/search-replace/index.html b/neovim-basics/search-replace/index.html
index 7477e142..9ed99de3 100644
--- a/neovim-basics/search-replace/index.html
+++ b/neovim-basics/search-replace/index.html
@@ -2522,42 +2522,51 @@
 
 
 <h1 id="search-and-replace">Search and Replace<a class="headerlink" href="#search-and-replace" title="Permanent link">λ︎</a></h1>
-<p>Search and replace within the current line or buffer:</p>
+<p>Search and replace within the current buffer:</p>
 <ul>
-<li><code>g m A</code> will match text under curor allowing in-place editing with visual-multi plugin </li>
+<li>use multipe cursors for in-place editing (visual-multi plugin) </li>
 <li><code>:%substitue</code> vim-style search and replace</li>
 </ul>
 <p>Search and replace across a project:</p>
 <ul>
-<li><code>SPC s</code> AstroNvim search and replace commands using Spectre (community plugin)</li>
-<li>Clojure LSP for symbols, etc.</li>
+<li><span class="keys"><kbd class="key-space">Space</kbd></span> <span class="keys"><kbd>s</kbd></span> search and replace commands using Spectre (AstroNvim community plugin)</li>
+<li><span class="keys"><kbd class="key-space">Space</kbd></span> <span class="keys"><kbd>l</kbd></span> <span class="keys"><kbd>r</kbd></span> to rename symbols using Clojure LSP (AstroNvim) </li>
 </ul>
-<details class="hint">
-<summary>Multiple cursors for multiple substitutions</summary>
-<p><span class="keys"><kbd>g</kbd></span> <span class="keys"><kbd>m</kbd></span> <span class="keys"><kbd>A</kbd></span> with the cursor on a word will start <a href="multiple-cursors.md">multiple cursors</a> with a cursor on each occurance.  Vim-editing tools can be used to replace the text at all cursors simultaneously</p>
-</details>
 <h2 id="buffer-wide">Buffer wide<a class="headerlink" href="#buffer-wide" title="Permanent link">λ︎</a></h2>
+<div class="tabbed-set tabbed-alternate" data-tabs="1:2"><input checked="checked" id="__tabbed_1_1" name="__tabbed_1" type="radio" /><input id="__tabbed_1_2" name="__tabbed_1" type="radio" /><div class="tabbed-labels"><label for="__tabbed_1_1">AstroNvim</label><label for="__tabbed_1_2">Neovim commands</label></div>
+<div class="tabbed-content">
+<div class="tabbed-block">
+<p><span class="keys"><kbd>g</kbd></span> <span class="keys"><kbd>m</kbd></span> <span class="keys"><kbd>A</kbd></span> uses visual-multi multiple curses to match all instances of the selected text and in-place editing</p>
+<p>Vim-editing tools can be used to replace the text at all cursors simultaneously.</p>
+<blockquote>
+<p><a href="multiple-cursors.md">multiple cursors in more detail</a> </p>
+</blockquote>
+</div>
+<div class="tabbed-block">
 <p>Replace all occurances of the current-pattern with the new pattern within the buffer.</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="p">:</span>%s<span class="sr">/current-pattern/</span><span class="k">new</span><span class="p">-</span>pattern/<span class="k">g</span>
 </code></pre></div>
+<p>Add the <code>c</code> option to confirm each replacement</p>
 <blockquote>
 <p>Further examples of <a href="substitue.md"><code>:substitue</code> neovim command</a></p>
 </blockquote>
+</div>
+</div>
+</div>
 <h2 id="project-wide">Project wide<a class="headerlink" href="#project-wide" title="Permanent link">λ︎</a></h2>
 <div class="admonition info">
 <p class="admonition-title">Evaluating...</p>
 </div>
-<div class="tabbed-set tabbed-alternate" data-tabs="1:2"><input checked="checked" id="__tabbed_1_1" name="__tabbed_1" type="radio" /><input id="__tabbed_1_2" name="__tabbed_1" type="radio" /><div class="tabbed-labels"><label for="__tabbed_1_1">AstroNvim</label><label for="__tabbed_1_2">Neovim commands</label></div>
+<div class="tabbed-set tabbed-alternate" data-tabs="2:2"><input checked="checked" id="__tabbed_2_1" name="__tabbed_2" type="radio" /><input id="__tabbed_2_2" name="__tabbed_2" type="radio" /><div class="tabbed-labels"><label for="__tabbed_2_1">AstroNvim</label><label for="__tabbed_2_2">Neovim commands</label></div>
 <div class="tabbed-content">
 <div class="tabbed-block">
 <p><a href="https://github.com/nvim-pack/nvim-spectre" target="_blank">Spectre</a> is available via the AstroNvim Community project pack and included in the Practicalli astronvim-config    </p>
 <p><span class="keys"><kbd class="key-space">Space</kbd></span> <span class="keys"><kbd>s</kbd></span> is the search and replace menu</p>
+<p><a class="glightbox" href="https://github.com/windwp/nvim-spectre/wiki/assets/demospectre.gif" data-type="image" data-width="100%" data-height="auto" data-desc-position="bottom"><img alt="nvim-spectr" src="https://github.com/windwp/nvim-spectre/wiki/assets/demospectre.gif" /></a></p>
 <p><a href="https://github.com/BurntSushi/ripgrep" target="_blank">ripgrep</a> and <a href="https://www.gnu.org/software/sed/">sed</a> are required.</p>
 <p><a class="md-button" href="https://github.com/nvim-pack/nvim-spectre" target="_blank">Spectre</a>    </p>
 </div>
-<div class="tabbed-block"></div>
-</div>
-</div>
+<div class="tabbed-block">
 <p><a class="md-button" href="https://chrisarcand.com/vims-new-cdo-command/" target="_blank">Vims new :cdo command</a></p>
 <details class="info">
 <summary>Neovim :help :cdo</summary>
@@ -2623,6 +2632,9 @@ <h2 id="project-wide">Project wide<a class="headerlink" href="#project-wide" tit
 <a id="__codelineno-1-60" name="__codelineno-1-60" href="#__codelineno-1-60"></a>            Otherwise it works the same <span class="k">as</span> `:ldo`.
 </code></pre></div>
 </details>
+</div>
+</div>
+</div>
 <!-- TODO: review :cdo and similar commands
 
     use ack.vim/ag.vim with the :cdo command, an intuitive and near-native project-wide find-and-replace solution is now available. 
diff --git a/search/search_index.json b/search/search_index.json
index 73aa0460..2d10712c 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Neovim for Clojure development","text":"<p>coding at the speed of thought</p> <p>Neovim is incredibly fast and efficient, so thoughts flow from brain to editor without unnecessary delay.</p> <p>Touch typing is fast, Neovim and multi-modal editing makes it even faster.</p> <p>Neovim is a highly extensible and powerful editor, supporting multi-modal editing and Vim-style sequential key bindings. Highly responsive and low resource use makes Neovim ideal for development on any computer or  mobile device, e.g. tablet, smartphone.</p> <p>Neovim has  a diverse set of plugins and  Practicalli curated configurations use these plugins to provide a  rich set of features for Clojure development and wider engineering tasks.</p> <p>Practicalli Neovim provides install &amp; user guide focused on a simple, powerful and satisfying REPL Driven workflow for Clojure.</p> <p></p>"},{"location":"#quick-start","title":"Quick Start","text":"<p>Install Clojure, Neovim and choose a community configuration</p> <ul> <li>[Lua] AstroNvim</li> <li>[Fennel] Practicalli Neovim Config Redux</li> </ul>"},{"location":"#external-reverences","title":"External reverences","text":"<p>Getting started with Neovim and Conjure</p> <p>Neovim user guide</p> <p>This Week In Neovim - community update</p> <p>Conjure install guide Conjuring Clojure in Vim</p>"},{"location":"#navigate-the-book","title":"Navigate the book","text":"<p>Use the mouse or built-in key bindings to navigate the pages of the book</p> <ul> <li>P , , : go to previous page</li> <li>N , . : go to next page</li> </ul> <p>Use the search box to quickly find a specific topic</p> <ul> <li>F , S , / : open search dialog</li> <li>Down , Up : select next / previous result</li> <li>Esc , Tab : close search dialog</li> <li>Enter : follow selected result</li> </ul>"},{"location":"#sponsor-my-work","title":"Sponsor my work","text":"<p>All sponsorship recieved is used to maintain and further develop the Practicalli series of books and videos, although most of the work is still done with my own time and cost.</p> <p>Thank you to Cognitect, Nubank and a wide range of other sponsors from the Clojure community for your continued support</p>"},{"location":"#creative-commons-license","title":"Creative commons license","text":"This work is licensed under a Creative Commons Attribution 4.0 ShareAlike License (including images &amp; style sheets)."},{"location":"api-tools/","title":"API Tools","text":"<p>Astrocommunity proivdes plugins to support working with APIs and the JSON format</p> <ul> <li> nvim-jqx</li> <li> rest-nvim</li> </ul> <p>Included in Practicalli Astronvim Config</p> <p>Practicalli Astronvim Config includes nvim-jqx and rest.nvim plugins</p>"},{"location":"api-tools/#inspect-json","title":"Inspect JSON","text":"<p>Browse and preview json files in neovim.</p> <p><code>:JqxList</code> prettify JSON and start the inspector</p> <p><code>JqxQuery</code> to run complex <code>jq</code> commands</p> jq binary required <p><code>jq</code> binary should be available on the command line as nvim-jqx runs jq queries internally</p> <p></p> <p> nvim-jqx</p>"},{"location":"api-tools/#call-apis","title":"Call APIs","text":"<p>Space r r to run an http request under the cursor from within an <code>*.http</code> file.</p> <p>A fast Neovim http client written in Lua, providing a curl wrapper.</p>"},{"location":"api-tools/#http-file","title":"http file","text":"<p>Open a file with an <code>*.http</code> extension</p> <p>Write a call to an API, e.g. a call to a local server health care endpoint</p> <p>Call locally running API</p> health-check.http<pre><code>GET http://localhost:8080/system-admin/status\n</code></pre> <p>A new window opens with the result of the API call</p> Result of API call with rest.nvim <pre><code>GET http://localhost:8080/system-admin/status\nCommand :curl -sSL --compressed -X 'GET' --data-raw '' 'http://localhost:8080/system-admin/status'\n#+END\nHTTP/1.1 200 OK\nContent-Type: application/json; charset=utf-8\nContent-Length: 66\nServer: http-kit\nDate: Mon, 10 Jul 2023 16:21:33 GMT\n\n#+RESPONSE\n{\"application\":\"practicalli hole-in-one Service\",\"status\":\"Alive\"}\n#+END\n</code></pre> <p>The <code>Content-Type</code> can be explicitly set, especially useful when not using JSON</p> <p>API call returning EDN data</p> <pre><code>GET http://localhost:8080/api/v1/scoreboard\naccept: application/edn\n</code></pre> <p> rest.nvim test examples </p> <p> rest.nvim</p>"},{"location":"assets/images/social/","title":"Social Cards","text":"<p>Social Cards are visual previews of the website that are included when sending links via social media platforms.</p> <p>Material for MkDocs is configured to generate beautiful social cards automatically, using the colors, fonts and logos defined in <code>mkdocs.yml</code></p> <p>Generated images are stored in this directory.</p>"},{"location":"configuration/","title":"Neovim Configuration","text":"<p>Practicalli Neovim covers the following configurations.</p> <ul> <li>AstroNvim - thoughtful configuration, supports Neovim 0.9 onward, polished UI, many community extensions</li> <li>Practicalli Neovim Config Redux - mnemonic key bindings, packer, telescope selector, written in Fennel</li> </ul>"},{"location":"configuration/#multiple-configurations","title":"Multiple Configurations","text":"<p>Install multiple configurations, e.g. AstroNvim, lazyvim, Nvchad, etc. in the <code>$HOME/.config</code> directory using unique directory names.</p> <p>Set <code>NVIM_APPNAME</code> to specific the configuration to use when running nvim.</p> <pre><code>NVIM_APPNAME=astronvim nvim\n</code></pre> <p><code>NVIM_APPNAME</code> variable should be set to the directory name containing the configuration, relative to the <code>.config</code> directory.</p> <p>The configuration directory name is used to hold <code>share</code>, <code>state</code> and <code>cache</code> files for that specific configuration.</p> <p>Create shell aliases for each configuration. Optionalliy, define a terminal UI selection to choose a configuration.</p> Shell AliasesTerminal UI Selector <p>Create a Shell alias for each configuration that will be used, to avoid setting the <code>NVIM_APPNAME</code> variable each time.</p> <p>Define Shell Aliases to run each configuration</p> <pre><code>alias astro=\"NVIM_APPNAME=astronvim nvim\"\nalias lazyvim=\"NVIM_APPNAME=lazyvim nvim\"\nalias practicalli-redux=\"NVIM_APPNAME=neovim-config-redux nvim\"\n</code></pre> <p>Create an nvim configuration selector script, with items listing the directory name of each configuration</p> <p>Z Shell nvim-selector script</p> .local/bin/nvim-selector<pre><code>function nvim-selector() {\n  items=(\"astronvim\" \"neovim-config-redux\" \"lazyvim\")\n  config=$(printf \"%s\\n\" \"${items[@]}\" | fzf --prompt=\"\ue62b Neovim Config \uf63d \" --height=~50% --layout=reverse --border --exit-0)\n  if [[ -z $config ]]; then\n    echo \"Nothing selected\"\n    return 0\n  elif [[ $config == \"default\" ]]; then\n    config=\"\"\n  fi\n  NVIM_APPNAME=$config nvim $@\n}\n</code></pre>"},{"location":"configuration/astronvim/","title":"AstroNvim","text":"<p> AstroNvim is a community configuration with an engaging UI, using Lazy for plugin management (Neovim packages) and Mason for package management (LSP, DAP, format and lint tools)</p> <p> Practicalli AstroNvim Config is a user configuration that extends AstroNvim and imports packages from the  AstroNvim Community.</p>"},{"location":"configuration/astronvim/#prerequisits","title":"Prerequisits","text":"<ul> <li>Nerd Fonts version 3 - download a full font or only the symbols</li> <li>fzf fuzzy finder (ubuntu archive)</li> <li>gtu (Ubuntu package archive)</li> <li>btm from GitHub repository releases</li> <li>node.js (version 20) for Mason install of many LSP servers</li> </ul> <p>AstroNvim requires node.js</p> <p>AstroNvim uses Mason to install LSP servers, format and lint tools.  Many LSP servers require node.js to install and function.</p> <p>Node.js install - Practicalli Engineering Playbook </p> Kitty Terminal with Nerd Fonts <p> Kitty Terminal - Practicalli Engineering Playbook provides examples of using Nerd Fonts or Nerd Font symbols with the Kitty terminal.</p>"},{"location":"configuration/astronvim/#clone-astronvim","title":"Clone AstroNvim","text":"<p>Clone AstroNvim repository to <code>$HOME/.config/astronvim/</code></p> <pre><code>git clone --depth 1 https://github.com/AstroNvim/AstroNvim ~/.config/astronvim\n</code></pre> <p><code>$HOME/.config/nvim</code> can be used instead if only ever using one configuration for Neovim.</p>"},{"location":"configuration/astronvim/#clone-astronvim-user-config","title":"Clone AstroNvim user config","text":"<p>AstroNvim provides a  template repository to create a user configuration. The template includes  AstroNvim Community configuration to make it easier to extend the feature of AstroNvim.</p> <p> Practicalli AstroNvim Config is a clone of the AstroNvim user config with additional configuration to support Clojure development.</p> Practicalli AstroNvim ConfigAstroNvim User Config <p>Clone the  Practicalli AstroNvim config which provides a user configuration with Clojure support</p> <pre><code>git clone http://github.com/practicalli/astronvim-config $HOME/.config/astronvim/lua/user\n</code></pre> <p>Or clone to a separate directory and create a symbolic link</p> <pre><code>git clone http://github.com/practicalli/astronvim-config $HOME/.config/astronvim-config &amp;&amp; \\\nln -s $HOME/.config/astronvim-config/ $HOME/.config/astronvim/lua/user\n</code></pre> <p>Create your own user configuration using the AstroNvim user configuration template repository.</p> <p>Create a repository from the AstroNvim/user_example repository template</p> <p></p> <p>Clone the newly created repository into the existing AstroNvim configuration, in a <code>user</code> directory <pre><code>git clone git@github.com/&lt;github-account&gt;/&lt;new-repository&gt; $HOME/.config/astronvim/lua/user\n</code></pre></p>"},{"location":"configuration/astronvim/#configure-shell-alias","title":"Configure shell alias","text":"<p>Create a shell alias that sets <code>NVIM_APPNAME</code> to the location of the AstroNvim community config</p> <p>Add alias to <code>.bashrc</code> for Bash shell or <code>.zshenv</code> for Zsh</p> <pre><code>alias astro=\"NVIM_APPNAME=astronvim nvim\"\n</code></pre> <p> Configure shell alias</p>"},{"location":"configuration/astronvim/#post-install","title":"Post install","text":"<p>Open a terminal and use the <code>astro</code> alias to run Neovim.</p> <pre><code>astro\n</code></pre> <p><code>NVIM_APPNAME=astronvim nvim</code> to run Neovim with astronvim without setting a shell alias.</p> <p>Neovim will open and display the Lazy plugin manager UI, showing the progress of plugin installation.  This should only happen on the first run.</p> Unattended post install <p>Plugins can be installed without running the Neovim editor UI</p> <pre><code>nvim --headless -c 'autocmd User LazyDone quitall'\n</code></pre>"},{"location":"configuration/astronvim/#check-health","title":"Check Health","text":"<p>Run the Neovim <code>:checkhealth</code> command to report on the general Neovim install and supporting tools</p>"},{"location":"configuration/astronvim/#add-lsp-dap-lint-and-format-tools","title":"Add LSP DAP Lint and Format tools","text":"<p><code>SPC p m</code> to launch Mason which manages LSP servers, linters, filters ...</p> <p></p>"},{"location":"configuration/astronvim/#configure-format-rules","title":"Configure format rules","text":"<p>The configuration files for each lint and format tool should be used by Neovim.</p> <p>Setting a different location for these files has proved challenging.  <code>plugin/null-ls.lua</code> has a section to override its builtin configuration for each lint and format tool, however, in tests Practicalli was unable to succeffuly set a different location.</p>"},{"location":"configuration/astronvim/config-design/","title":"\ud83d\udce6 Practicalli AstroNvim Config Design","text":"<p>A guide to the AstroNvim Config user configuration created by Practicalli to support Clojure development.</p> AstroCommunity used where possible <p>Plugins and configuration is added vial AstroCommunity were possible, to minimise the code size and maintenance of the configuration</p>"},{"location":"configuration/astronvim/config-design/#user-config-overview","title":"User Config overview","text":"<p><code>core.lua</code> is for tuning plugins shipped with astronvim config</p> <p><code>plugins/</code> for additional plugins organised logically. All <code>.lua</code> files are read from this directory </p> <ul> <li><code>user.lua</code> for general user defined plugins</li> <li><code>clojure.lua</code> adds Conjure and parinf, ensuring Clojure treesitter parser and Clojure LSP</li> </ul>"},{"location":"configuration/astronvim/config-design/#clojure-support","title":"Clojure support","text":"<p>The  AstroCommunity provides a Clojure language pack that adds Conjure and nvim-parinfer, along with <code>clojure</code> Treesitter parser and <code>clojure-lsp</code> support.</p> AstroCommunity PackManually add plugins <p>Edit the <code>plugins/community.lua</code> file and import the Clojure pack.  The <code>\"AstroNvim/astrocommunity\",</code> repository is already added to to the file.</p> <pre><code>-- Packs\n-- Treesitter: clojure , Lsp: clojure-lsp, Lint/format:\n{ import = \"astrocommunity.pack.clojure\" },\n</code></pre> Override AstroCommunity Pack <p>Create a <code>plugins/clojure.lua</code> file and add the AstroCommunity repository, Clojure pack and additional configuration to your own preferences</p> <p>Clojure configuration with user configration overrides</p> <pre><code>return {\n  \"AstroNvim/astrocommunity\",\n  { import = \"astrocommunity.pack.clojure\" },\n  {\n    \"Olical/conjure\",\n    -- load plugin on filetypes\n    ft = { \"clojure\", \"fennel\" },\n    config = function()\n      -- HUD\n      -- Example: Set to `\"SE\"` and HUD width to `1.0` for full width HUD at bottom of screen\n      vim.g[\"conjure#log#hud#width\"] = 1 -- Width of HUD as percentage of the editor width, 0.0 and 1.0.\n      vim.g[\"conjure#log#hud#enabled\"] = false -- Display HUD\n      vim.g[\"conjure#log#hud#anchor\"] = \"SE\" -- Preferred corner position for the HUD\n      vim.g[\"conjure#log#botright\"] = true -- Open log at bottom or far right of editor\n      -- REPL\n      vim.g[\"conjure#extract#context_header_lines\"] = 100 -- Number of lines to check for `ns` form\n      vim.g[\"conjure#client#clojure#nrepl#connection#auto_repl#enabled\"] = false -- ;; Start \"auto-repl\" process, eg. babashka\n      vim.g[\"conjure#client#clojure#nrepl#connection#auto_repl#hidden\"] = true -- ;; Hide auto-repl buffer when triggered\n      vim.g[\"conjure#client#clojure#nrepl#connection#auto_repl#cmd\"] = nil -- ;; Command to start the auto-repl\n      -- ;; Automatically require namespace of new buffer or current buffer after connection\n      vim.g[\"conjure#client#clojure#nrepl#eval#auto_require\"] = false\n      -- Reloading code\n      -- Function to call on refresh (reloading) the log, namespace-qualified name of a zero-arity\n      -- vim.g[\"conjure#client#clojure#nrepl#refresh#after\"] = nil\n      -- The namespace-qualified name of a zero-arity function to call before reloading.\n      -- vim.g[\"conjure#client#clojure#nrepl#refresh#before\"] = nil\n      -- List of directories to scan. If no directories given, defaults to all directories on the classpath.\n      -- vim.g[\"conjure#client#clojure#nrepl#refresh#dirs\"] = nil\n      -- Testing\n      -- ;; Test runner called from the test key mappings\n      vim.g[\"conjure#client#clojure#nrepl#test#runner\"] = \"kaocha\"\n      -- Print raw test evaluation result, suppressing prefix for stdout lines `; (out)`\n      -- vim.g[\"conjure#client#clojure#nrepl#test#raw_out\"] = nil\n      -- Override string appended to the end of the test runner calls\n      -- vim.g[\"conjure#client#clojure#nrepl#test#call_suffix\"] = nil\n    end\n  },\n  {\n    \"gpanders/nvim-parinfer\",\n    ft = { \"clojure\" },\n    config = function()\n      vim.g.parinfer_force_balance = true\n      vim.g.parinfer_comment_chars = \";;\"\n    end,\n  },\n}\n</code></pre> <p>Add Conjure and parinfer plugin that will load when Clojure or Fennel file is opened.</p> <p>Clojure Packages in AstroNvim user configuration</p> <pre><code>```lua title=\".config/astronvim-config/plugins/clojure.lua\"\n-- Lazy Package manager configuration\nreturn {\n  {\n    \"Olical/conjure\",\n    -- load plugin on filetypes\n    ft = { \"clojure\", \"fennel\" },\n  },\n\n  {\n    \"gpanders/nvim-parinfer\",\n    ft = { \"clojure\", \"fennel\" },\n    config = function()\n      vim.g.parinfer_force_balance = true\n      vim.g.parinfer_comment_chars = \";;\"\n    end,\n  },\n}\n```\n</code></pre> <p>Improve syntax highlighting by installing the Clojure parser for Treesitter.</p> <p>Treesitter Parser for clojure in AstroNvim user configuration</p> .config/astronvim-config/plugins/treesitter.lua<pre><code>return {\n  \"nvim-treesitter/nvim-treesitter\",\n  opts = function(_, opts)\n    -- add more things to the ensure_installed table protecting against community packs modifying it\n    opts.ensure_installed = require(\"astronvim.utils\").list_insert_unique(opts.ensure_installed, {\n      -- \"lua\"\n    \"clojure\"\n    })\n  end,\n}\n</code></pre> <p>Install Treesitter Clojure Parser manually</p> <p><code>:TSInstall clojure</code> in Neovim will install the parser. A parser not included in the <code>opts.ensure_installed</code> configuration must be updated manually each time treesitter plugin is updated</p> Switch to Parinfer Parens mode for Paredit structural editing <p>Changing the Parinfer mode to <code>paren</code> gives a structured editing experience similar to Paredit (or Smartparens).</p> <p>Add the following configuration within the <code>return {}</code> table in the <code>plugins/community.lua</code> file to set the parinfef mode, i.e. <code>paren</code>, <code>smart</code> or <code>indent</code> (default</p> plugins/community.lua<pre><code>  {\n    \"gpanders/nvim-parinfer\",\n    ft = { \"clojure\" },\n    config = function()\n      vim.g.parinfer_force_balance = true\n      vim.g.parinfer_comment_chars = \";;\"\n      vim.g.parinfer_mode = \"paren\"\n    end,\n  },\n</code></pre>"},{"location":"configuration/astronvim/config-design/#clojure-mappings","title":"Clojure Mappings","text":"<p>Conjure mappings are defined respective to a <code>&lt;localleader&gt;</code> value. Define a local leader in the AstroNvim user configuration, e.g. <code>,</code> and all Conjure mappings become available.</p> AstroNvim 3.17.0 has localleader <p>AstroNvim 3.17.0 release sets <code>localleader</code> to <code>,</code> so a separate setting is not required in the user configuration (unless a different localleader is preferred)</p> Set localleader in user config <p><code>options.lua</code> in the user configuration provides a consistent way to set Neovim options.</p> .config/astronvim-config/options.lua<pre><code>-- set vim options here (vim.&lt;first_key&gt;.&lt;second_key&gt; = value)\nreturn {\n  opt = {\n    -- set to true or false etc.\n    relativenumber = true, -- sets vim.opt.relativenumber\n    number = true,         -- sets vim.opt.number\n    spell = false,         -- sets vim.opt.spell\n    signcolumn = \"auto\",   -- sets vim.opt.signcolumn to auto\n    wrap = false,          -- sets vim.opt.wrap\n  },\n  g = {\n    mapleader = \" \",                 -- sets vim.g.mapleader\n    maplocalleader = \",\",            -- Set local leader key binding (supports Conjure key bindings)\n    autoformat_enabled = true,       -- enable or disable auto formatting at start (lsp.formatting.format_on_save must be enabled)\n    cmp_enabled = true,              -- enable completion at start\n    autopairs_enabled = true,        -- enable autopairs at start\n    diagnostics_mode = 3,            -- set the visibility of diagnostics in the UI (0=off, 1=only show in status line, 2=virtual text off, 3=all on)\n    icons_enabled = true,            -- disable icons in the UI (disable if no nerd font is available, requires :PackerSync after changing)\n    ui_notifications_enabled = true, -- disable notifications when toggling UI elements\n    VM_leader = \"gm\"                 -- Visual Multi Leader (multiple cursors)\n  },\n}\n</code></pre>"},{"location":"configuration/astronvim/config-design/#clojure-lsp","title":"Clojure LSP","text":"<p>Clojure LSP support is enabled via the AstroCommunity Clojure pack.</p> <p><code>clojure_lsp</code> can be added using Mason UI, <code>SPC p m</code> or in the <code>plugins/mason.lua</code> file</p> Manual user config of clojure lsp server <pre><code>-- customize mason plugins\nreturn {\n  -- use mason-lspconfig to configure LSP installations\n  {\n    \"williamboman/mason-lspconfig.nvim\",\n    -- overrides `require(\"mason-lspconfig\").setup(...)`\n    opts = function(_, opts)\n      -- add more things to the ensure_installed table protecting against community packs modifying it\n      opts.ensure_installed = require(\"astronvim.utils\").list_insert_unique(opts.ensure_installed, {\n        -- \"clojure_lsp\",  -- provide by Clojure pack\n        \"marksman\", -- Markdown structure (also in markdown pack)\n        \"yamlls\",\n      })\n    end,\n  },\n}\n</code></pre>"},{"location":"configuration/astronvim/config-design/#snippets","title":"Snippets","text":"<p>The AstroNvim user example includes a commented LuaSnip configuration</p> .config/astronvim-config/plugins/core.lua<pre><code>  -- {\n  --   \"L3MON4D3/LuaSnip\",\n  --   config = function(plugin, opts)\n  --     require \"plugins.configs.luasnip\" (plugin, opts)  -- include the default astronvim config that calls the setup call\n  --     -- add more custom luasnip configuration such as filetype extend or custom snippets\n  --     local luasnip = require \"luasnip\"\n  --     luasnip.filetype_extend(\"javascript\", { \"javascriptreact\" })\n  --   end,\n  -- },\n</code></pre> <p>AstroNvim includes a Recipe for custom snippets</p> <pre><code>return {\n  plugins = {\n    {\n      \"L3MON4D3/LuaSnip\",\n      config = function(plugin, opts)\n        require \"plugins.configs.luasnip\"(plugin, opts) -- include the default astronvim config that calls the setup call\n        require(\"luasnip.loaders.from_vscode\").lazy_load { paths = { \"./lua/user/snippets\" } } -- load snippets paths\n      end,\n    },\n  },\n}\n</code></pre> <p>Practicalli AstroNvim Config combines the two examples to get</p> <p>AstroNvim config with custom VS Code style snippets</p> .config/astronvim-config/plugins/core.lua<pre><code>{\n  \"L3MON4D3/LuaSnip\",\n  config = function(plugin, opts)\n    require \"plugins.configs.luasnip\" (plugin, opts) -- include the default astronvim config that calls the setup call\n    -- add more custom luasnip configuration such as filetype extend or custom snippets\n    require(\"luasnip.loaders.from_vscode\").lazy_load { paths = { \"./lua/user/snippets\" } } -- load snippets paths\n    local luasnip = require \"luasnip\"\n    luasnip.filetype_extend(\"javascript\", { \"javascriptreact\" })\nend,\n},\n</code></pre>"},{"location":"configuration/astronvim/config-design/#astronvim-community-packages","title":"AstroNvim Community packages","text":"<p> AstroNvim Community provides a large number of packages currated by the community.</p> <p>Visit the AstroNvim Community repository on GitHub and browse the packages available.</p> <p><code>import</code> each package of interest to the <code>plugins/community.lua</code> file in the AstroNvim user configuration.</p> <p>AstroNvim Community Packages in AstroNvim user configuration</p> .config/astronvim-config/plugins/community.lua<pre><code>return {\n  -- Add the community repository of plugin specifications\n  \"AstroNvim/astrocommunity\",\n  -- Import each plugin from the Astro Community as required\n  { import = \"astrocommunity.editing-support.todo-comments\" },\n  { import = \"astrocommunity.git.neogit\" },\n  { import = \"astrocommunity.git.octo\" },\n  { import = \"astrocommunity.git.openingh\" },\n}\n</code></pre> <p>AstroCommunity packs set up support for each language</p> <p>Language packs enabled in Practicalli AstroNvim Config</p> .config/astronvim-config/plugin/community.lua<pre><code>  -- Packs\n  -- Treesitter: dockerfile , Lsp: dockerls &amp; docker_compose_language_service, Lint/format: hadolint\n  { import = \"astrocommunity.pack.docker\" },\n  -- Treesitter: json &amp; jsonc, Lsp: jsonls, Lint/format: stylua\n  { import = \"astrocommunity.pack.json\" },\n  -- Treesitter: lua, Lsp: lua_ls, Lint/format: stylua\n  { import = \"astrocommunity.pack.lua\" },\n  -- Treesitter: markdown &amp; markdown_inline, Lsp: marksman, Lint/format: prettierd\n  -- Pack disabled as prettierd too agressive with format\n  -- { import = \"astrocommunity.pack.markdown\" },\n  -- Treesitter: markdown &amp; markdown_inline, Lsp: marksman, Lint/format: prettierd\n  { import = \"astrocommunity.pack.yaml\" },\n</code></pre>"},{"location":"configuration/astronvim/config-design/#themes","title":"Themes","text":"<p>Themes are a collection of one or more colorschemes to affect the apperance of text, icons, highlights, etc.</p> <p>Themes supporting <code>vim.opt.background</code> can change between dark and light colorscheme (<code>SPC u b</code> UI &gt; background in AstroNvim)</p> <p><code>SPC f t</code> selector shows themes colorschemes, as long as the themes are configured to disable lazy loading</p> <p>The default <code>astrodark</code> theme is set via the <code>colorscheme</code> option in <code>init.lua</code></p> <p>Everforest provides a good dark and light theme and supports the background option to toggle between each colorscheme.</p> <p>Practicalli AstroNvim Config - default theme</p> <pre><code>colorscheme = \"everforest\",\n</code></pre> <p> AstroCommunity themes</p> <p>Practicalli AstroNvim Config themes</p> <pre><code>return {\n{\n\"AstroNvim/astrotheme\", -- default AstroNvim theme\nlazy = false,\n},\n  -- Add the community repository of plugin specifications\n  \"AstroNvim/astrocommunity\",\n  { import = \"astrocommunity.colorscheme.everforest\" },\n  {\n    \"sainnhe/everforest\",\n    lazy = false,\n  },\n  { import = \"astrocommunity.colorscheme.nightfox-nvim\" },\n  {\n    \"EdenEast/nightfox.nvim\",\n    lazy = false,\n  },\n  { import = \"astrocommunity.colorscheme.kanagawa-nvim\" },\n  {\n    \"rebelot/kanagawa.nvim\",\n    lazy = false,\n  },\n  { import = \"astrocommunity.colorscheme.github-nvim-theme\" }, -- no background support\n  {\n    \"projekt0n/github-nvim-theme\",\n    lazy = false,\n  },\n</code></pre>"},{"location":"configuration/astronvim/config-design/#configure-lazy-plugins","title":"Configure Lazy plugins","text":"<p> Lazy.nvim Plugin specification</p>"},{"location":"configuration/astronvim/config-design/#config-format-and-lint-tools","title":"Config Format and Lint tools","text":"<p>Disable format on save when tools provide unexpected results</p> <p><code>SPC u f</code> toggles if the respective format tool should run for the current buffer.  <code>SPC u F</code> for all buffers of the current kind.</p> <p><code>init.lua</code> lsp section can enable or disable format on save for specific file types.</p> <p>Mason is responsible for installing lint and format tools</p> <p>null-ls is responsible for running each tool and provides default configuration for code_actions, completion, diagnostics, formatting and hover.</p> <p> null-ls built-in configuration</p> <p>Override config file unconsistent</p> <p>The configuration file defined by <code>-config-path</code> does not always seem to be used when running astronvim.  Quit and start Neovim again seems to use the configuration file.</p> Override null-ls builtin configuration <p>Specify configuration files to use that override the null-ls builtin configuration</p> <pre><code>return {\n  \"jose-elias-alvarez/null-ls.nvim\",\n  opts = function(_, config)\n    -- config variable is the default configuration table for the setup function call\n    local null_ls = require \"null-ls\"\n    config.sources = {\n      null_ls.builtins.formatting.markdownlint.with {\n        -- pass arguments to modify/override the null-ls builtin configuration\n        extra_args = { \n          \"--config-path\", \n          vim.fn.expand(\"~/.config/astro-config/tool-config/markdownlint.yaml\") },\n      },\n    }\n    return config -- return final config table\n  end,\n}\n</code></pre> <p><code>vim.fn.expand()</code> reports luacheck error <code>accessing undefined variable</code> but seems to work regardless</p> General configuration for LSP Servers .config/astronvim-config/init.lua<pre><code>  lsp = {\n    -- customize lsp formatting options\n    formatting = {\n      -- control auto formatting on save\n      format_on_save = {\n        enabled = true,     -- format on save globally\n        allow_filetypes = { -- format on save for specified filetypes only\n          -- \"go\",\n        },\n        ignore_filetypes = { -- turn off format on save for specified filetypes\n          -- \"python\",\n        },\n      },\n      disabled = { -- switch off formatting capabilities for the listed language servers\n        -- turn off lua_ls formatting capability if you want to use StyLua to format your lua code\n        -- \"lua_ls\",\n        \"markdownlint\",\n      },\n      timeout_ms = 1000, -- default format timeout\n      -- filter = function(client) -- fully override the default formatting function\n      --   return true\n      -- end\n    },\n    -- enable servers that you already have installed without mason\n    servers = {\n      -- \"pyright\"\n    },\n  },\n</code></pre>"},{"location":"configuration/astronvim/config-design/#override-key-binding","title":"Override Key binding","text":"<p>AstroNvim uses Lazy package manager to set keys for packages.  </p> <p>Astrocommunity configuration defines a <code>keys</code> table that is used by Lazy.</p> <p>In the user configuration, return a function that sets key bindings to overide the <code>keys</code> table provided by astrocommunity</p> Override Key bindings for vim highlighter .config/astronvim-config/plugins/community.lua<pre><code>{\n    \"vim-highlighter\",\n    keys = function() \n        return {\n            { \"&lt;leader&gt;nn\", \"&lt;cmd&gt;Hi&gt;&lt;CR&gt;\", desc = \"Next Recently Set Highlight\" },\n            { \"&lt;leader&gt;ng\", \"&lt;cmd&gt;Hi&lt;&lt;CR&gt;\", desc = \"Previous Recently Set Highlight\" },\n            { \"&lt;leader&gt;n[\", \"&lt;cmd&gt;Hi{&lt;CR&gt;\", desc = \"Next Nearest Highlight\" },\n            { \"&lt;leader&gt;n]\", \"&lt;cmd&gt;Hi}&lt;CR&gt;\", desc = \"Previous Nearest Highlight\" },\n        }\n    end,\n}\n</code></pre>"},{"location":"configuration/astronvim/config-design/#plugin-key-binding","title":"Plugin Key binding","text":"<p>Add key binding if a plugin is available wrapped in an if statement, when defining keys in a different place to adding the plugin, e.g whichkey mappings.lua</p> <pre><code>if is_available \"plugin-name\" then\n  ,,,\nelse\n</code></pre>"},{"location":"configuration/practicalli/","title":"Neovim Config Redux","text":"<p>practicalli/neovim-config-redux</p> <p>practicalli/neovim-config-redux is a Fennel based configuraion with a wide range of plugins and telescope extensions.</p> <p>Clone practicalli/neovim-config-redux or create a fork if intending to customise that configuration</p> Multiple Neovim ConfigsSingle Neovim Configs <pre><code>git clone https://github.com/practicalli/neovim-config-redux.git ~/.config/neovim-config-redux\n</code></pre> <pre><code>git clone https://github.com/practicalli/neovim-config-redux.git ~/.config/nvim\n</code></pre>"},{"location":"configuration/practicalli/#screenshots","title":"Screenshots","text":"<p>Dashboard using the startup plugin</p> <p></p> <p>Mnemonic menu with which-key</p> <p></p> <p>Telescope buffer selection</p> <p></p> <p>Neogit Git client with diffview panel</p> <p></p>"},{"location":"configuration/practicalli/config-design/","title":"Config Design","text":"<p>The overall design of the Practicalli Neovim Config Redux</p>"},{"location":"configuration/practicalli/config-design/#initlua","title":"<code>init.lua</code>","text":"<ul> <li>bootstrap the aniseed package which compiles the Fennel configuration into Lua, which is then read by Neovim. Defines the entry point to the Fennel configuration as <code>fnl/config/init.fnl</code></li> <li>installs packer.nvim for package management</li> <li>examples to disable language providers if programming language support is not required (node, perl, python3, ruby)</li> </ul>"},{"location":"configuration/practicalli/config-design/#fnlconfiginitfnl","title":"<code>fnl/config/init.fnl</code>","text":"<ul> <li>load plugin configuration namespace <code>config.plugin</code></li> <li>load <code>config.util</code> namespace to streamline key binding definitions</li> <li>set the leader key as <code>space</code> and local-leader as <code>,</code></li> <li>define key bindings - uses config.util  (mapping to be moved to their own namespace)</li> <li>set global Neovim options</li> </ul>"},{"location":"configuration/practicalli/config-design/#fnlconfigpluginfnl","title":"<code>fnl/config/plugin.fnl</code>","text":"<p>Define plugins to add functionality to Neovim.</p> <p><code>use</code> is a private function that searches the plugin configuration map for the keyword <code>:mod</code> and loads the associated namespace (namespace defined with a keyword with the same name)</p> <p>e.g. in the telescope plugin configuration <code>:mod</code> has a value of <code>:telescope</code> which will load the file <code>fnl/config/plugin/telescope.fnl</code></p> <pre><code>  :nvim-telescope/telescope.nvim\n  {:requires [:nvim-lua/popup.nvim\n              :nvim-lua/plenary.nvim]\n   :mod :telescope}\n</code></pre> <p>Packer downloads the <code>nvim-telescope/telescope.nvim</code> plugin and all the plugins in <code>:requires</code> section and search for the namespace <code>telescope</code> in file located in the following path <code>fnl/config/plugin/telescope</code></p>"},{"location":"configuration/practicalli/config-design/#fnlconfigpluginconjurefnl","title":"<code>fnl/config/plugin/conjure.fnl</code>","text":"<p>The majority of default configuration settings are used for Conjure, with the exception of a few commonly used key bindings from Emacs CIDER &amp; Spacemacs.  The Heads Up Display (HUD) is also configured to be less intrusive, relying on mostly on inline results.</p> <p>Include the conjure and aniseed namespaces</p> <pre><code>(module config.plugin.conjure\n  {autoload {nvim aniseed.nvim}})\n</code></pre> <p>Configure keybindings to be closer to Spacemacs</p> <pre><code>;; Set e register for evaluation result\n(set nvim.g.conjure#eval#result_register :e)\n\n;; Evaluate root form (top level form) under the cursor\n;; Default: `\"er\"`\n(set nvim.g.conjure#mapping#eval_root_form \"ef\")\n\n;; Evaluate root form under the cursor &amp; insert result as comment\n;; Default: `\"ecr\"`\n(set nvim.g.conjure#mapping#eval_comment_root_form \"e;\")\n\n;; Evaluate file loaded from disk\n;; Default: `\"ef\"`\n(set nvim.g.conjure#mapping#eval_file \"el\")\n</code></pre> <p>Configure the HUD to be less intrusive.</p> <pre><code>;; Width of HUD as percentage of the editor width\n;; A float between 0.0 and 1.0.\n;; Default: `0.42`\n(set nvim.g.conjure#log#hud#width 1)\n\n;; Display HUD\n;; Default: `true`\n(set nvim.g.conjure#log#hud#enabled false)\n\n;; Preferred corner position for the HUD, over-ridden by HUD cursor detection\n;; Example: Set to `\"SE\"` and HUD width to `1.0` for full width HUD at bottom of screen\n;; Default: `\"NE\"`\n(set nvim.g.conjure#log#hud#anchor \"SE\")\n\n;; Open log at bottom or far right of editor, using full width or height\n;; Default: `false`\n(set nvim.g.conjure#log#botright true)\n</code></pre> <p>Practicalli encourages header comments at the start of each file to describe the purpose of the namespace, so the Clojure ns lookup is extended</p> <pre><code>;; Number of lines to check for `ns` form, used for setting evaluation context\n;; `b:conjure#context` to override a specific buffer that isn't finding the context\n;; Default: `24`\n(set nvim.g.conjure#extract#context_header_lines 100)\n</code></pre> <p>Disable the auto-repl as practicalli prefers manage repl connections themselves</p> <pre><code>;; Start \"auto-repl\" process, eg. babashka\n;; when Conjure unable to find candidate REPL process via to an existing nREPL connection\n;; Default: `true`\n(set nvim.g.conjure#client#clojure#nrepl#connection#auto_repl#enabled false)\n\n;; Hide auto-repl buffer when triggered, to avoid the need to interact with that buffer\n;; Default: `false`\n(set nvim.g.conjure#client#clojure#nrepl#connection#auto_repl#hidden true)\n\n;; Command to start the auto-repl\n;; Default: `\"bb nrepl-server localhost:8794\"`\n(set nvim.g.conjure#client#clojure#nrepl#connection#auto_repl#cmd nil)\n\n;; Print raw evaluation result, suppressing prefix for stdout lines `; (out)`\n;; Default: `false`\n(set nvim.g.conjure#client#clojure#nrepl#eval#raw_out true)\n\n;; Automatically require namespace of new buffer or current buffer after connection\n;; Ensures buffers are loaded, required code to compile and (re)loadable.\n;; Default: `true`\n(set nvim.g.conjure#client#clojure#nrepl#eval#auto_require false)\n</code></pre> <p>Use lambdaisland/kaocha as the test runner rather, which has a fail fast feature which can be more effective when adding or changing functionality</p> <pre><code>;; Test runner called from the test key mappings\n;; Default: `\"clojure\"`\n(set nvim.g.conjure#client#clojure#nrepl#test#runner \"kaocha\")\n\n;; Print raw test evaluation result, suppressing prefix for stdout lines `; (out)`\n;; Default: `true`\n(set nvim.g.conjure#client#clojure#nrepl#test#raw_out true)\n</code></pre>"},{"location":"configuration/practicalli/config-design/#fnlconfigplugintelescopefnl","title":"<code>fnl/config/plugin/telescope.fnl</code>","text":"<p>Settings like ignore <code>node_modules</code> and everything in <code>.gitignore</code> to be listed in the file finder.</p> <p>Defines a ripgrep command to set parameters for searching files</p> <p>Add <code>--hidden</code> to see all dotfiles (regardless of .gitignore patterns)</p> <p>Keymaps:</p> <ul> <li><code>&lt;leader&gt;ff</code> open the find files</li> <li><code>&lt;leader&gt;fg</code> open the fuzzy finder</li> <li><code>&lt;leader&gt;fb</code> open the find open buffer</li> <li><code>&lt;leader&gt;fh</code> open the nvim help fuzzy finder</li> </ul>"},{"location":"configuration/practicalli/config-design/#fnlconfigplugintreesitterfnl","title":"<code>fnl/config/plugin/treesitter.fnl</code>","text":"<p>Defines which language parsers and modules to use.</p> <ul> <li>automatically use <code>clojure</code>, <code>fennel</code> and <code>markdown</code> parsers (and compile on first run of Neovim)</li> <li>automatically update language parsers when nvim-treesitter plugin updated</li> <li>enable highlight module</li> <li>enable indent module</li> </ul> <pre><code>(treesitter.setup\n  {:ensure_installed [\"clojure\" \"fennel\" \"markdown\"]\n   :sync_install true\n   :highlight {:enable true}\n   :indent    {:enable true}})\n</code></pre>"},{"location":"configuration/practicalli/config-design/#fnlconfigpluginlspconfigfnl","title":"<code>fnl/config/plugin/lspconfig.fnl</code>","text":"<p>Language Server Protocol for static analysis of code, to provide common formatting, linting and refactoring tooling across all programming languages.</p> <p>Define which symbols to show for lsp diagnostics</p> <pre><code>(defn define-signs\n  [prefix]\n  (let [error (.. prefix \"SignError\")\n        warn  (.. prefix \"SignWarn\")\n        info  (.. prefix \"SignInfo\")\n        hint  (.. prefix \"SignHint\")]\n  (vim.fn.sign_define error {:text \"\uf057\" :texthl error})\n  (vim.fn.sign_define warn  {:text \"\uf071\" :texthl warn})\n  (vim.fn.sign_define info  {:text \"\uf05a\" :texthl info})\n  (vim.fn.sign_define hint  {:text \"\uf059\" :texthl hint})))\n</code></pre> <ul> <li>features and server settings to enable/customize.</li> <li>Handler defines features and how we want to render the server outputs.</li> <li>Capabilities we link with our autocompletion plugin (nvim-cmp), to say to the lsp servers that we have this feature enabled.</li> <li>On_Attach we customize our interaction with the LSP server, here we define the following keymaps:</li> <li>configure all settings above in clojure-lsp server instance.</li> </ul>"},{"location":"configuration/practicalli/config-design/#fnlconfigplugincmpfnl","title":"<code>fnl/config/plugin/cmp.fnl</code>","text":"<p>Configure sources to show in the autocomple menu (i.e. conjure, lsp, buffer) and key bindings to navigate the autocomplete popup menu.</p>"},{"location":"configuration/practicalli/config-design/#fnlconfigpluginthemefnl","title":"<code>fnl/config/plugin/theme.fnl</code>","text":"<p>Add the Neovim GitHub theme which gives 3 dark and 3 light themes to choose from.  Individual colors and styles can be configured to change specific parts of the theme.</p> <p>The light theme is used by default, with a custom softer background colour that is slightly red-shifted.</p> <p>Options are specified in the <code>theme.setup</code> function, where the option names are keywords and the values are strings, boolean or hash-map of more option keywords and values.</p> <pre><code>(theme.setup {:theme_style \"light\"\n              :colors {:bg \"#f8f2e6\"}\n              :comment_style \"italic\"})\n</code></pre> <p>The colors (Hex values) for each theme are in the github-nvim-theme/lua/github-theme/palette with the overal theme definition in github-nvim-theme/lua/github-theme/theme.lua</p>"},{"location":"configuration/practicalli/config-design/#fnlconfigpluginsexpfnl","title":"<code>fnl/config/plugin/sexp.fnl</code>","text":"<p>Settings for vim-sexp like enabling it for another lisp languages like Fennel and Jannet</p>"},{"location":"configuration/practicalli/config-design/#fnlconfigpluginlualinefnl","title":"<code>fnl/config/plugin/lualine.fnl</code>","text":"<p>Configure the status line (lualine) that shows at the bottom of Neovim, defining colors and elements that appear on that line.</p> <p>The Neovim GitHub theme includes definitions to set the look of the status line.</p>"},{"location":"configuration/practicalli/packer/","title":"Package Manager","text":"<p>Packer is a <code>use-package</code> inspired package management for Neovim.</p> <p>Packer is used as the package manager in this guide as it is built on native Neovim packages and supports Luarocks dependencies, use the <code>:help packages</code> command in Neovim for more details.</p> <p>Packer is written in Lua and is installed via the <code>init.lua</code> configuration file, although Practicalli Neovim configuration uses Fennel to configure each package added by Packer.</p>"},{"location":"configuration/practicalli/packer/#install","title":"Install","text":"<p><code>init.lua</code> is the entry point to the configuration and is the only part that is written in Lua language.</p> <p>The configuration bootstraps the Packer package manager and installs the Aniseed compiler required to process the fennel configuration.</p> <p>Aniseed compiles and loads <code>fnl/config/init.fnl</code> and all the required namespaces in that file.</p> <p>Packer will process the <code>use</code> form in <code>fnl/config/plugin.fnl</code> and install all the packages defined in that form, along with any package specific configuration defined in that package <code>{:mod :namespace-name}</code> file.</p> <pre><code>local execute = vim.api.nvim_command\nlocal fn = vim.fn\n\nlocal pack_path = fn.stdpath(\"data\") .. \"/site/pack\"\nlocal fmt = string.format\n\nfunction ensure (user, repo)\n  -- Ensures a given github.com/USER/REPO is cloned in the pack/packer/start directory.\n  local install_path = fmt(\"%s/packer/start/%s\", pack_path, repo, repo)\n  if fn.empty(fn.glob(install_path)) &gt; 0 then\n    execute(fmt(\"!git clone https://github.com/%s/%s %s\", user, repo, install_path))\n    execute(fmt(\"packadd %s\", repo))\n  end\nend\n\n-- Bootstrap essential plugins required for installing and loading the rest.\nensure(\"wbthomason\", \"packer.nvim\")\nensure(\"Olical\", \"aniseed\")\n\n-- Enable Aniseed's automatic compilation and loading of Fennel source code.\nvim.g[\"aniseed#env\"] = {\n  module = \"config.init\",\n  compile = true\n}\n</code></pre>"},{"location":"configuration/practicalli/packer/#packages","title":"Packages","text":"<p>Neovim packages add extra functionality to Neovim, e.g. conjure package provides an excellent Clojure REPL experience (and supports several other languages too).</p> <p>See the packages section for details of the packages used and a breakdown of their configuration.</p>"},{"location":"configuration/practicalli/packages/","title":"Add Neovim Packages","text":"<p>Evolving Packages in Practicalli config</p> <p>Check the practicalli/neovim-config-reduct configuration. Many packages have been added to the configuration and <code>fnl/config/package.fnl</code> is the most up to date list of packages currently used.</p> <p>List of packages and their purpose</p> Package Description conjure Clojure REPL Driven Development (and other language REPLs) sexp Structured Editing newpaper theme Clean and simple UI &amp; colour scheme, aimed at readably lualine Fast and configurable statusline nvim-treesitter Parse code highly efficiently, client for LSP servers telescope Completion tool, e.g. select files, buffers tabs, packages, etc nvim-tree Visual file manager - open, create, delete, etc. files &amp; directories neogit Magit style visual Git client Octo Git Issues and Pull Requests gitsigns Show diff changes in buffer gutter and status line <p>Any specific package configuration &amp; key bindings (on sub page if significant content)</p>"},{"location":"configuration/practicalli/packages/#package-selection-criteria","title":"Package selection criteria","text":"<p>Packages are more likely to be adopted if:</p> <ul> <li>provide valuable (or fun) features</li> <li>work reliably, without generating errors</li> <li>do not conflict with other valuable packages in this configuration</li> <li>written in fennel or lua to aid maintenance</li> <li>provides a <code>setup</code> or <code>config</code> function for setting package options</li> <li>use features provided by Neovim (e.g treesitter)</li> <li>are well documented</li> <li>are easy to configure</li> <li>are easy to use</li> <li>work well with themes (where relevant)</li> </ul>"},{"location":"configuration/practicalli/packages/#package-updates","title":"Package Updates","text":"<p>This Week In Neovim - community update</p>"},{"location":"configuration/practicalli/packages/lualine/","title":"Lualine - modeline theme","text":"<p>nvim-lualine/lualine.nvim is a fast and configurable statusline for neovim</p> <p>Example status line: evil_lualine</p> <p></p>"},{"location":"configuration/practicalli/packages/lualine/#lualine-configuration-in-fennel","title":"Lualine configuration in Fennel","text":"<p><code>nvim/fnl/config/plugin/lualine.fnl</code></p> <pre><code>(module config.plugin.lualine\n  {autoload {core aniseed.core\n             lualine lualine\n             lsp config.plugin.lspconfig}})\n\n(defn lsp_connection []\n  (if (vim.tbl_isempty (vim.lsp.buf_get_clients 0)) \"\uf096\" \"\uf0c8\"))\n\n(def github-lua-theme\n  (core.assoc\n    (require :lualine.themes.auto)\n    :inactive {:a {:bg \"#19181e\" :fg \"#a4a3a6\"}\n               :b {:bg \"#19181e\" :fg \"#a4a3a6\"}\n               :c {:bg \"#19181e\" :fg \"#a4a3a6\"}}\n    :normal {:a {:bg \"#131217\" :fg \"#24292e\"}\n             :b {:bg \"#131217\" :fg \"#3b8eea\"}\n             :c {:bg \"#19181e\" :fg \"#d1d5da\"}}\n    :command {:a {:bg \"#131217\" :fg \"#24292e\"}\n              :b {:bg \"#131217\" :fg \"#ccbed8\"}\n              :c {:bg \"#19181e\" :fg \"#d1d5da\"}}\n    :visual {:a {:bg \"#131217\" :fg \"#24292e\"}\n             :b {:bg \"#131217\" :fg \"#ced4b1\"}\n             :c {:bg \"#19181e\" :fg \"#d1d5da\"}}\n    :replace {:a {:bg \"#131217\" :fg \"#24292e\"}\n              :b {:bg \"#131217\" :fg \"#d1b6bd\"}\n              :c {:bg \"#19181e\" :fg \"#d1d5da\"}}\n    :insert {:a {:bg \"#131217\" :fg \"#24292e\"}\n             :b {:bg \"#131217\" :fg \"#a8d1c9\"}\n             :c {:bg \"#19181e\" :fg \"#d1d5da\"}}))\n\n(lualine.setup\n  {:options {:theme github-lua-theme\n             :icons_enabled true\n             :section_separators [\"\" \"\"]\n             :component_separators [\"\uf44a\" \"\uf438\"]}\n   :sections {:lualine_a []\n              :lualine_b [[:mode {:upper true}]]\n              :lualine_c [[\"FugitiveHead\"]\n                          [:filename {:filestatus true\n                                      :path 1}]]\n              :lualine_x [[:diagnostics {:sections [:error\n                                                    :warn\n                                                    :info\n                                                    :hint]\n                                         :sources [:nvim_lsp]}]\n                          [lsp_connection]\n                          :location\n                          :filetype]\n              :lualine_y [:encoding]\n              :lualine_z []}\n   :inactive_sections {:lualine_a []\n                       :lualine_b []\n                       :lualine_c [[:filename {:filestatus true\n                                               :path 1}]]\n                       :lualine_x []\n                       :lualine_y []\n                       :lualine_z []}})\n</code></pre>"},{"location":"configuration/practicalli/packages/nvim-treesitter/","title":"Nvim Treesitter","text":"<p>Treesitter provides language specific parsing, highlight and indent features and so is a fundamental plugin to use with Neovim.</p> <p><code>clojure</code>, <code>fennel</code>, <code>markdown</code> and <code>org</code> parsers are automatically installed in the practicalli/neovim-config-redux configuration.</p> <ul> <li><code>:TSInstallInfo</code> lists language parsers and install status</li> <li><code>:TSUpdate {language}</code> to update a parser to the latest compatible version (specified in nvim-treesitter lockfile.json).</li> <li><code>:TSInstall {language}</code> compiles and installs a parser for the given language.</li> <li><code>:TSUpdateSync</code> to update all parsers to the latest available versions</li> </ul>"},{"location":"configuration/practicalli/packages/nvim-treesitter/#nvim-treesitter-configuration","title":"nvim-treesitter configuration","text":"<p><code>clojure</code>, <code>fennel</code>, <code>markdown</code> and <code>org</code> parsers are automatically installed if not already available.</p> <p><code>:sync_install true</code> automatically updates the parsers when the nvim-treesitter plugin is updated.  Treesitter and its parsers are actively developed, so its important to ensure parsers are kept up to date.  This is the equivalent of manually running <code>:TSUpdateSync</code>.</p> <p>Parser highlight and indent modules are enabled by default</p> <p>In <code>fnl/config/plugin/treesitter.fnl</code></p> <pre><code>(module config.plugin.treesitter\n  {autoload {treesitter nvim-treesitter.configs}})\n\n(treesitter.setup\n  {:ensure_installed [\"clojure\" \"fennel\" \"markdown\" \"org\"]\n   :sync_install true\n   :highlight {:enable true}\n   :indent    {:enable true}})\n</code></pre>"},{"location":"configuration/practicalli/packages/nvim-treesitter/#manually-install-parsers","title":"Manually Install Parsers","text":"<p>nvim-treesitter provides the <code>TSInstall</code> command to generate a parser for a specific language, assuming that language is supported.</p> <p>A compiler (gcc, clang, etc) should be installed in the operating system on which nvim is running</p> <pre><code>:TSInstall {language}\n</code></pre> <p><code>TAB</code> completion lists the available language parsers, <code>TAB</code> and <code>S-TAB</code> to navigate the auto-completion popup.</p>"},{"location":"install/","title":"Install Overview","text":"<p>Practicalli Neovim provides a feature rich configuration for Neovim and all the tools required for effective Clojure development (and other Lisp dialects too).</p> <ul> <li>Clojure tooling and a Java SDK (Java Virtual Machine)</li> <li>Neovim 0.9.x or nightly build</li> <li>Neovim package manager and packages</li> <li>NerdFonts for icon support in themes and status line</li> <li>Optional: Neovide GUI for neovim</li> </ul> <p>Neovim 0.9.x latest stable release</p> <p>Content and configuration in this book has been tested against Neovim 0.9.x over the summer of 2023</p>"},{"location":"install/#install-summary","title":"Install summary","text":"<p>If you are familiar with most of the tools required, then the quick start list below provides an ultra-terse version on how to get started with Neovim and Clojure development.</p> <ul> <li>Install Neovim 0.9.x or greater<ul> <li>Linux AppImage</li> <li><code>brew install --HEAD neovim</code> for Homebrew install of development version</li> </ul> </li> <li>Install supporting tools<ul> <li><code>tar</code> &amp; <code>curl</code> and a C compiler, e.g. <code>gcc</code> for Linux or <code>clang</code> for android/termix (required by nvim-treesitter)</li> <li><code>ripgrep</code> &amp; <code>fd</code> to search for files (used by telescope)</li> <li><code>luarocks</code> for LSP support in AstroNvim</li> </ul> </li> <li>Optionally add a community configuration, e.g. AstroNvim or Practicalli Neovim Config</li> <li>Run <code>nvim</code> in a terminal </li> <li>Install Clojure CLI and supporting tools</li> <li>Clone / fork practicalli/clojure-deps-edn or add an alias with the required config to use nrepl and cider-nrepl</li> <li>Run a Clojure REPL process - in a terminal session with nREPL, e.g. using one of the REPL aliases from practicalli/clojure-cli-config<ul> <li><code>clojure -M:repl/rebel</code> for a rich REPL UI with auto-completion &amp; docs</li> <li><code>clojure -M:repl/headless</code> - headless REPL process when working exclusively in a Clojure connected editor . Open a Clojure file in Neovim - Conjure will automatically connect</li> </ul> </li> </ul>"},{"location":"install/#next-steps","title":"Next Steps","text":"<p>Learn how to use Neovim and how to use Conjure for REPL driven development</p>"},{"location":"install/clojure/","title":"Install Clojure","text":"<p>A rich Clojure REPL workflow is provided by the Conjure package, which works with Clojure CLI and Leiningen projects, assuming the respective tool is installed.</p> <p>Clojure LSP is highly recommended and packages to use an installed clojure-lsp tool are in the practicalli/neovim-config-redux configuration</p>"},{"location":"install/clojure/#clojure-cli","title":"Clojure CLI","text":"<p> Practicalli Clojure install guide</p> <p> Clojure CLI provides a way to run Clojure code, packaged Clojure (jar) and run a Clojure REPL.</p> <p> Practicalli Clojure install guide details prerequisites, Clojure install options and supporting tools for an enhanced developer workflow.</p> <p>Visit the  Clojure Getting Started guide for the Clojure CLI or to check the latest release version.</p> <p> Practicalli Clojure CLI Config provides a wide range of community tools that extend the features of Clojure CLI, creating a rich development environment for use across all projects.</p> <p>Aliases are required for many examples</p> <p>Without  Practicalli Clojure CLI Config many commands provided in this book are not available unless similar alias definitions are added to a either a project or user level <code>deps.edn</code> configuration.</p>"},{"location":"install/clojure/#language-server-protocol","title":"Language Server Protocol","text":"<p>Neovim Treesitter surfaces information from Language Server Protocol (LSP) servers to assist with development and refactor of Clojure code.</p> <p> Clojure LSP installation guide shows how to install the Clojure LSP binary for the relevant operating system.</p> <p>Once installed, run <code>clojure-lsp -v</code> in a terminal to ensure the command is working.</p> <p>practicalli/clojure-lsp-config</p> <p> practicalli/clojure-lsp-config provides a complete configuration for clojure-lsp (<code>config.edn</code>), including a wide range of snippets and less restrictive formatting rules (<code>cljfmt.edn</code>)</p> <p>clj-kondo provides static analysis of source code files, providing subtle warnings as Clojure code is written to help the developer follow idioms and avoid syntatic errors.</p> <p>Clojure LSP includes clj-kondo to provide  an implementation of the Language Server Protocol for the Clojure Language.</p> <p> Clojure LSP installation guide  Treesitter Fennel Configuration</p>"},{"location":"install/clojure/#leiningen","title":"Leiningen","text":"<p>Many existing Clojure projects use Leiningen build automation tool (although many new projects use Clojure CLI as well or instead of Leiningen).  </p> <p>The code is the same regardless of tooling choice.  The overall workflow is the same, although Clojure CLI may provide more workflow options.</p> <p>Follow the install instructions at Leiningen.org if required.</p>"},{"location":"install/neovim/","title":"Install Neovim","text":"<p>Neovim releases</p> <p>Neovim 8 is the minimum version for this configuration and Neovim 0.9.0 is currently being tested.</p> <p>Follow the install Neovim guide for the specific operating system.</p>"},{"location":"install/neovim/#suppoting-tools","title":"Suppoting Tools","text":"<p>Neovim uses several external tools for searching for files, search file contents and using the operating system clipbaord.</p> <p>AstroNvim requires node.js</p> <p>AstroNvim uses Mason to install LSP servers, format and lint tools.  Many LSP servers require node.js to install and function.</p> <p>Node.js install - Practicalli Engineering Playbook </p> Debian / Ubuntu <p>Install the following packages to support Neovim</p> <ul> <li><code>ripgrep</code> fast file contents search (used by telescope)</li> <li><code>find-fd</code> advanced search tool</li> <li><code>xclip</code> clipboard as a provider tools for Neovim copy/paste</li> <li><code>luarocks</code> for LSP servers (AstroNvim)</li> </ul> <pre><code>sudo apt install find-fd xclip luarocks\n</code></pre> <p>Add <code>set clipboard+=unnamedplus</code> to the Neovim configuration to use the Linux clipboard tool</p> Wayland requires wl-clipboard <p>Install the <code>wl-clipboard</code> package to use the Wayland desktop clipboard with Neovim <pre><code>sudo apt install wl-clipboard\n</code></pre></p>"},{"location":"install/neovim/#install-neovim_1","title":"Install Neovim","text":"Linux AppImageUbuntu/DebianBuild from Source <p>Download the AppImage from the Neovim Release page and place the file on the executable path, e.g. <code>$HOME/.local/bin</code></p> <p>Make the AppImage executable</p> <pre><code>chmod u+x nvim.appimage\n</code></pre> <p>Run neovim from the AppImage</p> <pre><code>nvim.appimage\n</code></pre> <p>Create a symbolic link called <code>nvim</code> to the nvim.appimage</p> <pre><code>ln -s $HOME/.local/bin/nvim.appimage $HOME/.local/bin/nvim\n</code></pre> <p>Download the Linux AppImage from the Neovim Releases page</p> <p>Or build Neovim from source and generate a <code>.deb</code> file from the build.</p> Linux version only packaged as AppImage from Neovim 0.9 onward <p>Neovim Build Prerequisites for each operating system</p> Ubuntu/Debian Packages <p>Install packages to support building Neovim <pre><code>sudo apt-get install ninja-build gettext cmake unzip curl\n</code></pre></p> <p>Clone the Neovim GitHub repository</p> <p><pre><code>git clone --origin neovim https://github.com/neovim/neovim.git\n</code></pre> Change into the cloned directory and change to the <code>stable</code> release to build version 0.9.0</p> <pre><code>git checkout stable\n</code></pre> <p>Build a release</p> <pre><code>make CMAKE_BUILD_TYPE=Release                                                                                                              \u2500\u256f\n</code></pre> <p>Once the nvim release has been built, create a debian package for use with Ubuntu and Debian systems</p> <pre><code>cpack -G DEB\n</code></pre>"},{"location":"install/neovim/#post-install-checks","title":"Post Install checks","text":"<p>Ensure supporting tools and binaries are available in the operating system by running the Neovim Heath Check.</p> <p><code>nvim</code> in a terminal to run NeoVim and check the installation is working without error.</p> <p></p> <p><code>:checkhealth</code> to run a check supporting tools are available to NeoVim.</p> <p>A report is generated and shown in NeoVim</p> <p><code>j</code> / <code>k</code> to scroll through the checkhealth report</p> <p>Review the warnings and install tooling that is required for languages that will be used.</p> <p></p> <p>Ignore Provider Warnings</p> <p>It is safe to ignore language provider warnings.</p> <p>Language Providers can be disabled in the Neovim configuration to remove the warnings from <code>:checkhealth</code> report.  Examples of disabling language provders are in the practicalli/neovim-config-redux configuration, covered in the Neovim Config install step</p>"},{"location":"introduction/community-projects/","title":"Community Configuration Projects","text":"<p>Practicalli Neovim book covers the following configurations:</p>"},{"location":"introduction/community-projects/#practicalli-neovim-config-redux","title":"Practicalli Neovim Config Redux","text":"<p> Practicalli Neovim Config Redux</p> <ul> <li>Fennel configuration</li> <li>Packer package manager &amp; Treesitter support</li> <li>Mnemonic key bindings</li> <li>Telescope selectors</li> <li>Autocompletion (cmp) &amp; snippets (luasnip)</li> <li>Esc with center row keys, e.g. \"fd\"</li> </ul>"},{"location":"introduction/community-projects/#astronvim-and-practicalli-astronvim-config","title":"AstroNvim and Practicalli AstroNvim Config","text":"<p> AstroNvim and Practicalli AstroNvim Config organised configuration with a polished UI</p> <ul> <li>Neovim 9 support</li> <li>Lazy for plugins (packages for Neovim)</li> <li>Mason to manage install for LSP, DAP, lint and format tools</li> <li>Treesitter and language parser support</li> <li>Telescope selectors</li> <li>Notification dialogs</li> <li>Autocompletion (cmp) &amp; snippets (luasnip)</li> <li>Neovim 9 background switch (live toggle light &amp; dark theme)</li> <li>Hidden command line <code>cmdheight=0</code> (Neovim 0.8 onward)</li> <li>Esc with center row keys, e.g. \"fd\" (user: <code>plugins/core.lua</code>)</li> </ul>"},{"location":"introduction/community-projects/#alternative-configurations","title":"Alternative configurations","text":"<p>Practicalli Neovim does not cover the following Community configurations.</p> <ul> <li>Magit Kit fennel configuration from the author of Conjure</li> <li>cajus-nvim inspiration for practicalli/neovim-config-redux</li> <li>LazyVim lazy &amp; mason configuration</li> <li>NvChad polished UI with Lazy optomisations</li> </ul> <p>Long term project: Fennel config with AstroNvim-like UI experience</p> <p>A very long term goal for Practicalli is to create a Neovim configuration written predominatly in Fennel, providing a rich user experience on par with the very polished experience of AstroNvim.</p> <p>Lazy and Mason should be used to manage packages and tools (LSP &amp; DAP servers, lint &amp; format tools).</p> <p>Which-key should provide a mnemonic menu system similar to the Spacemacs experience.</p>"},{"location":"introduction/contributing/","title":"Contributing to Practicalli","text":"<p>Practicalli books are written in markdown and use MkDocs to generate the published website via a GitHub workflow.  MkDocs can also run a local server using the <code>make docs</code> target from the <code>Makefile</code></p> <p>By submitting content ideas and corrections you are agreeing they can be used in this book under the Creative Commons Attribution ShareAlike 4.0 International license.  Attribution will be detailed via GitHub contributors.</p> <p>All content and interaction with any persons or systems must be done so with respect and within the Practicalli Code of Conduct.</p>"},{"location":"introduction/contributing/#book-status","title":"Book status","text":""},{"location":"introduction/contributing/#submit-and-issue-or-idea","title":"Submit and issue or idea","text":"<p>If something doesnt seem quite right or something is missing from the book, please raise an issue via the GitHub repository explaining in as much detail as you can.</p> <p>Raising an issue before creating a pull request will save you and the maintainer time.</p>"},{"location":"introduction/contributing/#considering-a-pull-request","title":"Considering a Pull request?","text":"<p>Before investing any time in a pull request, please raise an issue explaining the situation.  This can save you and the maintainer time and avoid rejected pull requests.</p> <p>Please keep pull requests small and focused, as they are much quicker to review and easier to accept.  Ideally PR's should be for a specific page or at most a section.</p> <p>A PR with a list of changes across different sections will not be merged, it will be reviewed eventually though.</p>"},{"location":"introduction/contributing/#thank-you-to-everyone-that-has-contributed","title":"Thank you to everyone that has contributed","text":"<p>A huge thank you to Rich Hickey and the team at Cognitect for creating and continually guiding the Clojure language.  Special thank you to Alex Miller who has provided excellent advice on working with Clojure and the CLI tooling.</p> <p>The Clojure community has been highly supportive of everyone using Clojure and I'd like to thank everyone for the feedback and contributions.  I would also like to thank everyone that has joined in with the London Clojurins community, ClojureBridgeLondon, Clojurians Slack community, Clojurians Zulip community and Clojureverse community.</p> <p>Thank you to everyone who sponsors the Practicalli websites and videos and for the Clojurists Together sponsorship, it helps me continue the work at a much faster pace.</p> <p>Special thanks to Bruce Durling for getting me into Cloure in the first place.</p> <p></p>"},{"location":"introduction/features/","title":"Neovim features","text":"<p>A clean UI provides for a distraction free development experience, with only the essential information presented in the Neovim statusline or inline with the code</p> <ul> <li>Conjure - automatic Clojure REPL connection, evaluation, test runners</li> <li>Treesitter</li> <li>Plug-in Manager (e.g. Lazy.nvim) </li> <li>LSP - auto-completion, snippets, inline linting, reference navigation, refactor and unit test coverage</li> <li>statusline - LSP status, diff changes, filetype, cursor position</li> <li>Selection narrowing completion of files, packages, colour schemes, etc</li> <li>File browser - telescope selection narrowing and visual file system navigation</li> <li>Version Control gutter indicators for changed lines</li> <li>todo comments todo, fix, notes, indicators with gutter icons</li> <li>relative line numbers for vim-style navigation</li> </ul>"},{"location":"introduction/features/#conjure","title":"Conjure","text":"<p> Conjure An interactive environment for evaluating code, e.g. a Clojure REPL.  Conjure automatically connects to an nREPL process running in the current project.</p> <p>Evaluate Clojure code as its developed for an instant feedback workflow.</p> <p>Run unit tests with Kaocha test runner (Cognitect Labs and ClojureScript runners also available)</p> <p>Fireplace has been a long-standing plugin for Vim to support Clojure REPL connection.</p>"},{"location":"introduction/features/#lazy-plugin-manager","title":"Lazy Plugin manager","text":"<p>Lazy.nvim manages neovim plugins with a rich UI that provides an enjoyable user experience.  Plugins are automatically installed during startup and lists the status of each plugins. </p> <p>Plugins are automatic cached &amp; bytecode compiled and can be lazy loaded to streamline startup time and resource usage based on events, commands, filetypes, and key mappings.  Efficient plugin downlaods using partial blobless clones of plugin repositories, i.e. <code>--filter=blob:none</code></p> <p></p> <p> Lazy.nvim</p>"},{"location":"introduction/features/#treesitter","title":"Treesitter","text":"<p>Neovim provides highly effective syntax highlighting of source code due to Treesitter.</p> <p>Tree-sitter parses files opened in Neovim and builds a concrete syntax tree that any Neovim plugin can use to efficiently provide feedback. Treesitter uses incremental parsing to efficiently update the syntax tree as a file is edited. </p> <ul> <li>parse on every keystroke in a text editor</li> <li>provide useful results even in the presence of syntax errors</li> </ul> <p> Treesitter </p>"},{"location":"introduction/features/#language-server-protocol","title":"Language Server Protocol","text":"<p>Neovim includes an LSP client which uses the information recieved from a language specific LSP server in real-time to provide a range of services:</p> <ul> <li>auto-completion of function and symbol names</li> <li>live linting as code is typed or opened from a file</li> <li>formatting</li> <li>function signatures and help documentation</li> <li>diagnostics (syntax errors &amp; idioms)</li> <li>symantic analysis providing rename through project, go-to-definition &amp; find-references</li> </ul> <p>LSP feedback is often presented in the buffer, file browser and status line of Neovim.</p> <p>LSP Server implementation is not universal</p> <p>LSP is a relatively new specification and many server implmentations are still evolving or are yet to be created.</p> <p>Lint tools tend to be more prevelent and may be required in concert with or in the absence of an LSP server.</p> LSP related Plugins <ul> <li>neovim/nvim-lspconfig - connect Neovim lsp client to lsp servers</li> <li>jose-elias-alvarez/null-ls.nvim - hook format and lint tools into the Neovim LSP client</li> <li>jayp0521/mason-null-ls.nvim - automatically install formatters/linters to be used by null-ls</li> <li>williamboman/mason - install and manage LSP servers, DAP servers, linters, and formatters</li> <li>williamboman/mason-lspconfig - register LSP configs with neovim so LSP client can connect to  servers</li> </ul>"},{"location":"introduction/features/#lint-and-format-tools","title":"Lint and format tools:","text":"<p>Linters check code for common problems and provide hints on how to correct any detected issues.</p> <p>Format tools suppor code to conforming to a specified coding style, typically these run when save-file is run.</p> <p>null-ls provides extensive builtin configuration for programming languages and configuration formats.  null-ls also passes lint and format tool information to the Neovim LSP client, extending the range of language support.</p>"},{"location":"introduction/features/#selection-narrowing","title":"Selection Narrowing","text":"<p> telescope.nvim is a highly extendable fuzzy finder over lists with community driven pickers, sorters and previewers.</p> <p>Navigate and narrow lists of files, packages, environment variables, ports, colour schemes (themes) and any other list of items effectively. </p> <p>Telescope File browser popup also explores the file system and in Normal mode can be used to create files and directories</p> <p>The telescope list narrows matches as characters are typed</p>"},{"location":"introduction/features/#version-control","title":"Version Control","text":"<p>Gitsigns hightlights buffer changes in the gutter</p> <p>Lualine shows number of Git changes in status line</p> <p>Diffview to review all changes for any git revision</p> <p>Neogit provides a rich git client to add, stash, commit, push &amp; pull changes.</p> <p>Octo provides a GitHub specific client to manage issues and pull requests, using GitHub CLI authentication.</p> <p>LazyGit UI</p>"},{"location":"introduction/features/#file-browser","title":"File Browser","text":"<p>neo-tree provides a visual file system explorer that can also create and delete files and directories</p>"},{"location":"introduction/features/#todo-comments","title":"TODO Comments","text":"<p>Highlight tasks, fixes, notes and dragons comments, including icons in the gutter.  Use Telescope to navigate TODO comments in the current project.</p>"},{"location":"introduction/features/#status-line","title":"Status Line","text":"<p>LSP feedback</p>"},{"location":"introduction/features/#markdown","title":"Markdown","text":"<ul> <li>LSP server</li> <li>Marksman: select anchors and pages for links</li> </ul>"},{"location":"introduction/fennel/","title":"Fennel","text":"<p>Lua is the defacto language for Neovim plugin development and configuration.</p> <p>Fennel can be used to write Neovim packages and configuration, using  nfnl to generate the equivalent Lua code that Neovim runs.</p> <p>Although Neovim fully supports Vimscript, Practicalli encourages Fennel or Lua, as Vimscript is a niche language with quite complex syntax.</p>"},{"location":"introduction/fennel/#overview","title":"Overview","text":"<p> Fennel is a programming language that brings together the speed, simplicity, and reach of  Lua with the flexibility of a  lisp syntax and macro system.</p> <ul> <li>Full Lua compatibility: Easily call any Lua function or library from Fennel and vice-versa.</li> <li>Zero overhead: Compiled code should be just as efficient as hand-written Lua.</li> <li>Compile-time macros: Ship compiled code with no runtime dependency on Fennel.</li> <li>Embeddable: Fennel is a one-file library as well as an executable. Embed it in other programs to support runtime extensibility and interactive development.</li> </ul> <p>Anywhere you can run Lua code, you can run Fennel code.</p> <p>Translate Lua to Fennel</p> <p> See Fennel is an online antifennel tool to convert Lua to Fennel or Fennel to Lua.</p> <p>practicalli/neovim-config-redux configuration provides helper functions to minimise the translation required.</p>"},{"location":"introduction/fennel/#fennel-packages","title":"Fennel Packages","text":"<p>The Conjure package which provides the Clojure REPL (and much more) is written in Fennel.</p>"},{"location":"introduction/fennel/#nfnl","title":"nfnl","text":"<p> nfnl generates Lua code from Fennel code.  Neovim runs the generated Lua code.</p> <p>nfnl loads only when working in directories containing a <code>.nfnl.fnl</code> configuration file, so has zero overhead when not working with fennel.</p> <p><code>*.fnl</code> files are automatically compiled to <code>*.lua</code> when changes are saved, showing any compilation errors to provide an effective feedback loop.</p> <p>nfnl standard library</p> <p>nfnl plugin example</p>"},{"location":"introduction/fennel/#development-tooling","title":"Development tooling","text":"<p>Neovim support</p> <ul> <li>Anti-fennel - convert from Lua code to Fennel code.</li> <li>nfnl - write plugins or configuration for Neovim with great runtime performance</li> <li>hotpot - seamless Fennel inside Neovim</li> </ul> <p> See Fennel is an online antifennel tool to convert between Lua and Fennel.</p> <p> Guide to plugin development with fennel</p> <p>Emacs support:</p> <ul> <li> technomancy/fennel-mode and Emacs mirror repository</li> </ul>"},{"location":"introduction/fennel/#playing-games","title":"Playing Games","text":"<p> TIC-80 is a simulated computer environment to to write code, design art, compose music and retro style game games.</p> <p> L\u00d6VE is a framework for making games with the Lua programming language, allows import from external resources and can use any resolution or memory resources required.</p> <p>TIC-80 and L\u00d6VE provide cross-platform support across Windows, Mac and Linux systems. TIC-80 games can also be played in the browser.</p>"},{"location":"introduction/repl-workflow/","title":"REPL Driven Development","text":"<p>Always be REPL'ing</p> <p>Coding without a REPL feels limiting. The REPL provides fast feedback from code as its crafted, testing assumptions and design choices every step of the journey to a solution  - John Stevenson, Practical.li</p> <p>Clojure is a powerful, fun and highly productive language for developing applications and services.  The clear language design is supported by a powerful development environment known as the REPL (read, evaluate, print, loop).  The REPL gives you instant feedback on what your code does and enables you to test either a single expression or run the whole application (including tests).</p> <p>REPL driven development is the foundation of working with Clojure effectively</p> <p>An effective Clojure workflow begins by running a REPL process.  Clojure expressions are written and evaluated immediately to provide instant feedback. The REPL feedback helps test the assumptions that are driving the design choices.</p> <ul> <li>Read - code is read by the Clojure reader, passing any macros to the macro reader which converts those macros into Clojure code.</li> <li>Evaluate - code is compiled into the host language (e.g. Java bytecode) and executed</li> <li>Print - results of the code are displayed, either in the REPL or as part of the application.</li> <li>Loop - the REPL is a continuous process that evaluates code, either a single expression or the whole application.</li> </ul> <p>Design decisions and valuable data from REPL experiments can be codified as specifications and unit tests</p> <p>Practicalli REPL Reloaded Workflow</p> <p>The principles of REPL driven development are implemented in practice using the Practicalli REPL Reloaded Workflow and supporting tooling.  This workflow uses Portal to inspect all evaluation results and log events, hot-load libraries into the running REPL process and reloads namespaces to support major refactor changes.</p>"},{"location":"introduction/repl-workflow/#evaluating-source-code","title":"Evaluating source code","text":"<p>A REPL connected editor is the primary tool for evaluating Clojure code from source code files, displaying the results inline.</p> <p>Source code is automatically evaluated in its respective namespace, removing the need to change namespaces in the REPL with (<code>in-ns</code>) or use fully qualified names to call functions.</p> <p>Evaluate Clojure in Neovim with Conjure</p> <p><code>, e b</code> evaluates the code in the current buffer</p> <p> </p> Evaluate Clojure in a Terminal UI REPL <p>Entering expressions at the REPL prompt evaluates the expression immediately, returning the result directly underneath  </p>"},{"location":"introduction/repl-workflow/#rich-comment-blocks-living-documentation","title":"Rich Comment blocks - living documentation","text":"<p>The <code>(comment ,,,)</code> function wraps code that is only run directly by the developer using a Clojure aware editor.</p> <p>Expressions in rich comment blocks can represent how to use the functions that make up the namespace API.  For example, starting/restarting the system, updating the database, etc.  Expressions provide examples of calling functions with typical arguments and make a project more accessible and easier to work with.</p> <p>Clojure Rich Comment to manage a service</p> <pre><code>(ns practicalli.gameboard.service)\n\n(defn app-server-start [port] ,,,)\n(defn app-server-start [] ,,,)\n(defn app-server-restart [] ,,,)\n\n(defn -main\n  \"Start the service using system components\"\n  [&amp; options] ,,,)\n\n(comment\n  (-main)\n  (app-server-start 8888)\n  (app-server-stop)\n  (app-server-restart 8888)\n\n  (System/getenv \"PORT\")\n  (def environment (System/getenv))\n  (def system-properties (System/getProperties))\n  ) ; End of rich comment block\n</code></pre> <p>Rich comment blocks are very useful for rapidly iterating over different design decisions by including the same function but with different implementations.  Hide clj-kondo linter warnings for redefined vars (<code>def</code>, <code>defn</code>) when using this approach.</p> <pre><code>;; Rich comment block with redefined vars ignored\n#_{:clj-kondo/ignore [:redefined-var]}\n(comment\n  (defn value-added-tax []\n    ;; algorithm design - first idea)\n\n  (defn value-added-tax []\n    ;; algorithm design - second idea)\n\n  ) ;; End of rich comment block\n</code></pre> <p>The \"Rich\" in the name is an honourary mention to Rich Hickey, the author and benevolent dictator of Clojure design.</p>"},{"location":"introduction/repl-workflow/#design-journal","title":"Design Journal","text":"<p>A journal of design decisions makes the code easier to understand and maintain.  Code examples of design decisions and alternative design discussions are captured, reducing the time spent revisiting those discussions.</p> <p>Journals simplify the developer on-boarding processes as the journey through design decisions are already documented.</p> <p>A Design Journal is usually created in a separate namespace, although it may start as a rich comment at the bottom of a namespace.</p> <p>A journal should cover the following aspects</p> <ul> <li>Relevant expressions use to test assumptions about design options.</li> <li>Examples of design choices not taken and discussions why (saves repeating the same design discussions)</li> <li>Expressions that can be evaluated to explain how a function or parts of a function work</li> </ul> <p>The design journal can be used to create meaningful documentation for the project very easily and should prevent time spent on repeating the same conversations.</p> <p>Example design journal</p> <p>Design journal for TicTacToe game using Reagent, ClojureScript and Scalable Vector Graphics</p>"},{"location":"introduction/repl-workflow/#viewing-data-structures","title":"Viewing data structures","text":"<p>Pretty print shows the structure of results from function calls in a human-friendly form, making it easier for a developer to parse and more likely to notice incorrect results.</p> <p>Tools to view and navigate code</p> <ul> <li> Cider inspector is an effective way to navigate nested data and page through large data sets.</li> <li> Portal Inspector to visualise many kinds of data in many different forms.</li> </ul> <p></p>"},{"location":"introduction/repl-workflow/#code-style-and-idiomatic-clojure","title":"Code Style and idiomatic Clojure","text":"<p>Clojure aware editors should automatically apply formatting that follows the  Clojure Style guide.</p> <p>Live linting with clj-kondo suggests common idioms and highlights a wide range of syntax errors as code is written, minimizing bugs and therefore speeding up the development process.</p> <p> </p> <p>Clojure LSP is build on top of clj-kondo</p> <p> Clojure LSP uses clj-kondo static analysis to provide a standard set of development tools (format, refactor, auto-complete, syntax highlighting, syntax &amp; idiom warnings, code navigation, etc).</p> <p>Clojure LSP can be used with any Clojure aware editor that provides an LSP client, e.g.  Spacemacs,  Doom Emacs,  Neovim, VSCode.</p> <p>Clojure Style Guide</p> <p>The  Clojure Style guide provides examples of common formatting approaches, although the development team should decide which of these to adopt.  Emacs <code>clojure-mode</code> will automatically format code and so will Clojure LSP (via cljfmt).  These tools are configurable and should be tailored to the teams standard.</p>"},{"location":"introduction/repl-workflow/#data-and-function-specifications","title":"Data and Function specifications","text":"<p> Clojure spec is used to define a contract on incoming and outgoing data, to ensure it is of the correct form.</p> <p>As data structures are identified in REPL experiments, create data specification to validate the keys and value types of that data.</p> <pre><code>;; ---------------------------------------------------\n;; Address specifications\n(spec/def ::house-number string?)\n(spec/def ::street string?)\n(spec/def ::postal-code string?)\n(spec/def ::city string?)\n(spec/def ::country string?)\n(spec/def ::additional string?)\n\n(spec/def ::address   ; Composite data specification\n  (spec/keys\n   :req-un [::street ::postal-code ::city ::country]\n   :opt-un [::house-number ::additional]))\n;; ---------------------------------------------------\n</code></pre> <p>As the public API is designed, specifications for each functions arguments are added to validate the correct data is used when calling those functions.</p> <p> Generative testing provides a far greater scope of test values used incorporated into unit tests. Data uses clojure.spec to randomly generate data for testing on each test run.</p>"},{"location":"introduction/repl-workflow/#test-driven-development-and-repl-driven-development","title":"Test Driven Development and REPL Driven Development","text":"<p>Test Driven Development (TDD) and REPL Driven Development (RDD) complement each other as they both encourage incremental changes and continuous feedback.</p> <p>Test Driven Development fits well with Hammock Time, as good design comes from deep thought</p> <ul> <li>RDD enables rapid design experiments so different approaches can easily and quickly be evaluated .</li> <li>TDD focuses the results of the REPL experiments into design decisions, codified as unit tests.  These tests guide the correctness of specific implementations and provide critical feedback when changes break that design.</li> </ul> <p> Unit tests should support the public API of each namespace in a project to help prevent regressions in the code.  Its far more efficient in terms of thinking time to define unit tests as the design starts to stabilize than as an after thought.</p> <p><code>clojure.test</code> library is part of the Clojure standard library that provides a simple way to start writing unit tests.</p> <p> Clojure spec can also be used for generative testing, providing far greater scope in values used when running unit tests.  Specifications can be defined for values and functions.</p> <p>Clojure has a number of  test runners available.  Kaocha is a test runner that will run unit tests and function specification checks.</p> <p>Automate local test runner</p> <p>Use  kaocha test runner in watch mode to run tests and specification check automatically (when changes are saved) <pre><code>clojure -X:test/watch\n</code></pre></p>"},{"location":"introduction/repl-workflow/#continuous-integration-and-deployment","title":"Continuous Integration and Deployment","text":"<p>Add a  continuous integration service to run tests and builds code on every shared commit.  Spin up testable review deployments when commits pushed to a pull request branch, before pushing commits to the main deployment branch, creating an effective pipeline to gain further feedback.</p> <ul> <li> CircleCI provides a simple to use service that supports Clojure projects.</li> <li> GitHub Workflows and GitHub actions marketplace to quickly build a tailored continuous integration service, e.g. Setup Clojure GitHub Action.</li> <li> GitLab CI</li> </ul> <p></p>"},{"location":"introduction/repl-workflow/#live-coding-with-data-stuart-halloway","title":"Live Coding with Data - Stuart Halloway","text":"<p>There are few novel features of programming languages, but each combination has different properties. The combination of dynamic, hosted, functional and extended Lisp in Clojure gives developers the tools for making effective programs. The ways in which Clojure's unique combination of features can yield a highly effective development process.</p> <p>Over more than a decade we have developed an effective approach to writing code in Clojure whose power comes from composing many of its key features. As different as Clojure programs are from e.g. Java programs, so to can and should be the development experience. You are not in Kansas anymore!</p> <p>This talk presents a demonstration of the leverage you can get when writing programs in Clojure, with examples, based on my experiences as a core developer of Clojure and Datomic.</p> <p> </p>"},{"location":"introduction/writing-tips/","title":"Writing tips for MkDocs","text":"<p>Making the docs more engaging using the mkdocs-material theme reference guide</p> Configuring Colors <p>Material for MkDocs - Changing the colors lists the primary and accent colors available.</p> <p>HSL Color Picker for codes to modify the theme style, overriding colors in <code>docs/assets/stylesheets/extra.css</code></p>"},{"location":"introduction/writing-tips/#hypertext-links","title":"Hypertext links","text":"<p>Links open in the same browser window/tab by default.</p> <p>Add <code>{target=_blank}</code> to the end of a link to configure opening in a new tab</p> <pre><code>[link text](url){target=_blank}\n</code></pre>"},{"location":"introduction/writing-tips/#buttons","title":"Buttons","text":"<p>Convert any link into a button by adding <code>{.md-button}</code> class names to end of the markdown for a link, which uses <code>.md-button-primary</code> by default.  Include <code>target=_blank</code> for buttons with links to external sites.</p> <pre><code>[link text](http://practical.li/blog){.md-button target=_blank}\n</code></pre> <p>Or specify a different class</p> <pre><code>[link text](http://practical.li/blog){.md-button .md-button-primary}\n</code></pre> <p>Add an icon to the button</p> <p> Practicalli Issues  Practicalli Blog</p> <pre><code>[:fontawesome-brands-github: Practicalli Issues](http://practical.li/blog){ .md-button .md-button-primary }\n[:octicons-heart-fill-24: Practicalli Blog](http://practical.li/blog){ .md-button .md-button-primary }\n</code></pre> <p>Search all supported icons</p>"},{"location":"introduction/writing-tips/#youtube-video","title":"YouTube video","text":"<p>Use an iframe element to include a YouTube video, wrapping in a paragraph tag with center alignment to place the video in a centered horizontal position</p> <pre><code>&lt;p style=\"text-align:center\"&gt;\n&lt;iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/rQ802kSaip4\" title=\"YouTube video player\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen&gt;&lt;/iframe&gt;\n&lt;/p&gt;\n</code></pre> <p>mkdocs material does not have direct support for adding a YouTube video via markdown.</p>"},{"location":"introduction/writing-tips/#admonitions","title":"Admonitions","text":"<p>Supported admonition types</p> <p>Note</p> <p>Use <code>!!!</code> followed by <code>NOTE</code></p> <p>Adding a title</p> <p>Use <code>!!!</code> followed by <code>NOTE</code> and a <code>\"title in double quotes\"</code></p> <p>Shh, no title bar just the text... Use <code>!!!</code> followed by <code>NOTE</code> and a <code>\"\"</code> empty double quotes</p> <p>Abstract</p> <p>Use <code>!!!</code> followed by <code>ABSTRACT</code></p> <p>Info</p> <p>Use <code>!!!</code> followed by <code>INFO</code></p> <p>Tip</p> <p>Use <code>!!!</code> followed by <code>TIP</code></p> <p>Success</p> <p>Use <code>!!!</code> followed by <code>SUCCESS</code></p> <p>Question</p> <p>Use <code>!!!</code> followed by <code>QUESTION</code></p> <p>Warning</p> <p>Use <code>!!!</code> followed by <code>WARNING</code></p> <p>Failure</p> <p>Use <code>!!!</code> followed by <code>FAILURE</code></p> <p>Danger</p> <p>Use <code>!!!</code> followed by <code>DANGER</code></p> <p>Bug</p> <p>Use <code>!!!</code> followed by <code>BUG</code></p> <p>Example</p> <p>Use <code>!!!</code> followed by <code>EXAMPLE</code></p> <p>Quote</p> <p>Use <code>!!!</code> followed by <code>QUOTE</code></p>"},{"location":"introduction/writing-tips/#collapsing-admonitions","title":"Collapsing admonitions","text":"Note <p>Collapse those admonitions using <code>???</code> instead of <code>!!!</code></p> Replace with a title <p>Use <code>???</code> followed by <code>NOTE</code> and a <code>\"title in double quotes\"</code></p> Expanded by default <p>Use <code>???+</code>, note the <code>+</code> character,  followed by <code>NOTE</code> and a <code>\"title in double quotes\"</code></p>"},{"location":"introduction/writing-tips/#inline-blocks","title":"Inline blocks","text":"<p>Inline blocks of text to make a very specific callout within text</p> <p>Info</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Adding something to then end of text is probably my favourite</p> <p>Info</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p>"},{"location":"introduction/writing-tips/#code-blocks","title":"Code blocks","text":"<p>Code blocks include a copy icon automatically</p> <p>Syntax highlighting in code blocks</p> <pre><code>(defn my-function  ; Write a simple function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n</code></pre> <p>Give the code block a title using <code>title=\"\"</code> after the backtics and language name</p> src/practicalli/gameboard.clj<pre><code>(defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n</code></pre> <p>We all like line numbers, especially when you can set the starting line</p> src/practicalli/gameboard.clj<pre><code>(defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n</code></pre> <p>Add <code>linenums=42</code> to start line numbers from 42 onward</p> <pre><code>clojure linenums=\"42\" title=\"src/practicalli/gameboard.clj\"\n</code></pre>"},{"location":"introduction/writing-tips/#annotations","title":"Annotations","text":"<p>Annotations in a code block help to highlight important aspects.  Use the comment character for the language followed by a space and a number in brackets</p> <p>For example, in a shell code block, use <code># (1)</code> where 1 is the number of the annotation</p> <p>Use a number after the code block to add the text for the annotation, e.g. <code>1.</code>. Ensure there is a space between the code block and the annotation text.</p> <pre><code>ls -la $HOME/Downloads  # (1)\n</code></pre> <ol> <li> I'm a code annotation! I can contain <code>code</code>, formatted text, images, ... basically anything that can be written in Markdown.</li> </ol> <p>Code blocks with annotation, add <code>!</code> after the annotation number to suppress the <code>#</code> character</p> <pre><code>(defn helper-function\n  \"Doc-string with description of function purpose\" ; (1)!\n  [data]\n  (merge {:fish 1} data)\n  )\n</code></pre> <ol> <li>Always include a doc-string in every function to describe the purpose of that function, identifying why it was added and what its value is.</li> </ol> <p>GitHub action example with multiple annotations</p> <pre><code>name: ci # (1)!\non:\n  push:\n    branches:\n      - master # (2)!\n      - main\npermissions:\n  contents: write\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-python@v4\n        with:\n          python-version: 3.x\n      - run: pip install mkdocs-material # (3)!\n      - run: mkdocs gh-deploy --force\n</code></pre> <ol> <li> <p>You can change the name to your liking.</p> </li> <li> <p>At some point, GitHub renamed <code>master</code> to <code>main</code>. If your default branch     is named <code>master</code>, you can safely remove <code>main</code>, vice versa.</p> </li> <li> <p>This is the place to install further [MkDocs plugins] or Markdown     extensions with <code>pip</code> to be used during the build:</p> <pre><code>pip install \\\n  mkdocs-material \\\n  mkdocs-awesome-pages-plugin \\\n  ...\n</code></pre> </li> </ol>"},{"location":"introduction/writing-tips/#highlight-lines-in-code-blocks","title":"Highlight lines in code blocks","text":"<p>Add highlight line meta data to a code block after the opening backticks and code block language.</p> <p><code>hl_lines=\"2\"</code> highlights line 2 in the codeblock</p> <p><code>hl_lines=\"2 3 4\"</code> highlights line 2, 3 and 4 in the codeblock</p> <pre><code>(defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map\n   inc\n   [1 2 3]))\n</code></pre>"},{"location":"introduction/writing-tips/#embed-external-files","title":"Embed external files","text":"<p><code>--8&lt;--</code> in a code block inserts code from a source code file or other text file</p> <p>Specify a local file from the root of the book project (the directory containing mkdocs.yml)</p> Scheduled Version Check GitHub Workflow from source code file scheduled version check<pre><code>\n</code></pre> Practicalli Project Templates Emacs project configuration - .dir-locals.el<pre><code>((clojure-mode . ((cider-preferred-build-tool . clojure-cli)\n                  (cider-clojure-cli-aliases . \":test/env:dev/reloaded\"))))\n</code></pre> <p>Code example reuse</p> <p>Use an embedded local or external file (URL) when the same content is required in more than one place in the book.</p> <p>An effective way of sharing code and configuration mutliple times in a book or across multiple books.</p>"},{"location":"introduction/writing-tips/#content-tabs","title":"Content tabs","text":"<p>Create in page tabs that can also be</p> <p>Setting up a project</p> Clojure CLILeiningen <pre><code>clojure -T:project/new :template app :name practicalli/gameboard\n</code></pre> <pre><code>lein new app practicalli/gameboard\n</code></pre> <p>Or nest the content tabs in an admonition</p> <p>Run a terminal REPL</p> Clojure CLILeiningen <pre><code>clojure -T:repl/rebel\n</code></pre> <pre><code>lein repl\n</code></pre>"},{"location":"introduction/writing-tips/#diagrams","title":"Diagrams","text":"<p>Neat flow diagrams</p> <p>Diagrams - Material for MkDocs</p> <pre><code>graph LR\n  A[Start] --&gt; B{Error?};\n  B --&gt;|Yes| C[Hmm...];\n  C --&gt; D[Debug];\n  D --&gt; B;\n  B ----&gt;|No| E[Yay!];</code></pre> <p>UML Sequence Diagrams</p> <pre><code>sequenceDiagram\n  Alice-&gt;&gt;John: Hello John, how are you?\n  loop Healthcheck\n      John-&gt;&gt;John: Fight against hypochondria\n  end\n  Note right of John: Rational thoughts!\n  John--&gt;&gt;Alice: Great!\n  John-&gt;&gt;Bob: How about you?\n  Bob--&gt;&gt;John: Jolly good!</code></pre> <p>state transition diagrams</p> <pre><code>stateDiagram-v2\n  state fork_state &lt;&lt;fork&gt;&gt;\n    [*] --&gt; fork_state\n    fork_state --&gt; State2\n    fork_state --&gt; State3\n\n    state join_state &lt;&lt;join&gt;&gt;\n    State2 --&gt; join_state\n    State3 --&gt; join_state\n    join_state --&gt; State4\n    State4 --&gt; [*]</code></pre> <p>Class diagrams - not needed for Clojure</p> <p>Entity relationship diagrams are handy though</p> <pre><code>erDiagram\n  CUSTOMER ||--o{ ORDER : places\n  ORDER ||--|{ LINE-ITEM : contains\n  LINE-ITEM {\n    customer-name string\n    unit-price int\n  }\n  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses</code></pre>"},{"location":"introduction/writing-tips/#keyboard-keys","title":"Keyboard keys","text":"<p>Represent key bindings with Keyboard keys. Each number and alphabet character has their own key.</p> <ul> <li>1 <code>++1++</code> for numbers</li> <li>l <code>++\"l\"++</code> for lowercase character</li> <li>U <code>++u++</code> for uppercase character or <code>++\"U\"++</code> for consistency</li> </ul> <p>Punctionation keys use their name</p> <ul> <li>Space <code>++spc++</code></li> <li>, <code>++comma++</code></li> <li>Left <code>++arrow-left++</code></li> </ul> <p>For key sequences, place a space between each keyboard character</p> <ul> <li>Space g s <code>++spc++ ++\"g\"++ ++\"s\"++</code></li> </ul> <p>For key combinations, use join they key identifies with a <code>+</code></p> <ul> <li>Meta+X <code>++meta+x++</code></li> <li>Ctrl+Alt+Del <code>++ctrl+alt+del++</code></li> </ul> <p>MkDocs keyboard keys reference</p>"},{"location":"introduction/writing-tips/#images","title":"Images","text":"<p>Markdown images can be appended with material tags to set the size of the image, whether to appear on light or dark theme and support lazy image loading in browsers</p> SizeLazy LoadingAlignTheme SpecificAll Image Attributes <p><code>{style=\"height:150px;width:150px\"}</code> specifies the image size <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){style=\"height:150px;width:150px\"}\n</code></pre></p> <p></p> <p><code>{loading=lazy}</code> specifies an image should lazily load in the browser <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png){loading=lazy}\n</code></pre></p> <p><code>{aligh=left}</code> or <code>{aligh=right}</code> specifies the page alignment of an image. <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right}\n</code></pre></p> <p>  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p><code>![Kitty Logo](image/kitty-light.png#only-dark)</code> or <code>![Kitty Logo](image/kitty-light.png#only-light)</code>  specifies the theme the image should be shown, allowing different versions of images to be shown based on the theme. <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){style=\"height:150px;width:150px\"}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){style=\"height:150px;width:150px\"}\n</code></pre> Use the theme toggle in the top nav bar to see the icon change between light and dark.  </p> <p>Requires the color pallet toggle</p> <p>Alight right, lazy load and set image to 150x150</p> <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right loading=lazy style=\"height:64px;width:64px\"}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right loading=lazy style=\"height:64px;width:64px\"}\n</code></pre> <p>  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p>"},{"location":"introduction/writing-tips/#lists","title":"Lists","text":"<p>Task lists</p> <ul> <li> Lorem ipsum dolor sit amet, consectetur adipiscing elit</li> <li> Vestibulum convallis sit amet nisi a tincidunt</li> <li> In hac habitasse platea dictumst</li> <li> In scelerisque nibh non dolor mollis congue sed et metus</li> <li> Praesent sed risus massa</li> <li> Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque</li> </ul> <p>Task List example</p> <pre><code>- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit\n- [ ] Vestibulum convallis sit amet nisi a tincidunt\n    * [x] In hac habitasse platea dictumst\n    * [x] In scelerisque nibh non dolor mollis congue sed et metus\n    * [ ] Praesent sed risus massa\n- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque\n</code></pre>"},{"location":"introduction/writing-tips/#tooltips","title":"Tooltips","text":"<p>The humble tool tip</p> <p>Hover me</p> <p>with references</p> <p>Hover me</p> <p>Icon tool tip with a title</p> <p></p>"},{"location":"introduction/writing-tips/#abreviations","title":"Abreviations","text":"<p>The HTML specification is maintained by the W3C.</p> <p>[HTML]: Hyper Text Markup Language [W3C]: World Wide Web Consortium</p>"},{"location":"introduction/writing-tips/#magic-links","title":"Magic links","text":"<p>MagicLink can auto-link HTML, FTP, and email links. It can auto-convert repository links (GitHub, GitLab, and Bitbucket) and display them in a more concise, shorthand format.</p> <p>Email Practicalli</p> <p>Practicalli Neovim</p>"},{"location":"neovim-basics/","title":"Using Neovim","text":"<p>The fundamental controls of Neovim which apply across all editing tasks.</p>"},{"location":"neovim-basics/#fundamentals","title":"Fundamentals","text":"<p> File Buffer Window and Tab page  Multi-modal Editing</p>"},{"location":"neovim-basics/#keyboard-mappings","title":"Keyboard mappings","text":"<p><code>:verbose map</code> followed by a key binding shows the location of the configuration that was last used to set the key mapping.  Use when its not clear what command a key mapping is calling or if a plugin is over-riding an expected mapping. </p> <p>Space f n to list all notifications and Enter on the relevant notification to see the details.</p> <p><code>:verbose map &lt;C-Up&gt;</code> shows the last place in the neovim config that defines a mapping for Ctrl+Up.</p> <p>Map Listing: Neovim docs Key Notation: Neovim docs</p>"},{"location":"neovim-basics/#editing-tools","title":"Editing Tools","text":"<p> Multiple Cursors</p>"},{"location":"neovim-basics/#writing-tools","title":"Writing Tools","text":"<p> Snippets</p>"},{"location":"neovim-basics/#development-tools","title":"Development Tools","text":"<p> Comments  Clojure Development  Version Control</p> <p>Format and Lint tools are installed via Mason</p>"},{"location":"neovim-basics/#spellcheck","title":"Spellcheck","text":"AstroNvim <p><code>SPC u s</code> toggles spellcheck, marking misspelt words with a rew wavy underline</p> <p><code>] s</code> jumps to next misspelt word, <code>[ s</code> jumps to previous misspelt word, </p> <p><code>z =</code> shows numbered list of possible words, enter the number next to the work to replace the misspelt word.</p> <p><code>z g</code> to add the current word to the spell list, infroming spellcheck that this is a correct word.</p>"},{"location":"neovim-basics/comments/","title":"Comments","text":"<p>comment.nvim toggles a comment for lines, visual selections or for motions</p> <p><code>gcc</code> comment current line, <code>4gcc</code> comment current line and next 4 lines</p> <p><code>gc</code> comment region or use with motion e.g. <code>gcap</code> comment paragraph,</p> <p>gc in operator pending mode to target a comment TODO: what is operator pending mode</p> <p><code>:7,17Commentary</code> comment a range</p> <p><code>:g/TODO/Commentary</code> as part of a :global invocation</p> <p><code>gcgc</code> removes comments from a set of adjacent commented lines.</p>"},{"location":"neovim-basics/file-buffer-window-tab/","title":"Files Buffers Windows and Tabs","text":"<p>Files are text written to perminant storage, e.g. disk or usb drive and are names with an extension that represents the file type, e.g. <code>.clj</code> for clojure, <code>.md</code> for markdown, etc.</p> <p>A Buffer hold the contents of a file or any other information from processes, e.g. the REPL evaluation log.</p> <p>Windows are a view on a buffer and windows can swap which buffer they show.  Multiple windows, also known as splits, can be present in a Neovim frame.  </p> <p>A tab page (or tab) can hold one or more windows and multiple tab pages can be shown on a tab-line. </p>"},{"location":"neovim-basics/file-buffer-window-tab/#files","title":"Files","text":"<p>Use Neo-tree.nvim to visually navigate and manage files using a tree view of the current project. Files and directories can be added, renamed, moved and deleted.</p> <p>Use Telescope to select files, typing a name narrows the file list.</p>"},{"location":"neovim-basics/file-buffer-window-tab/#using-neo-tree","title":"Using Neo-tree","text":"AstronvimPracticalli Neovim Config Redux <p>Space e toggles neo-tree file browser</p> <p>Space o toggles between buffer and neo-tree</p> <p>Configure hidden files</p> <p>Configure Neotree to display hidden files and directories by default.  They are shown with a different visual style (subtle color) compared to the other files and directories.  </p> <p><code>H</code> with the cursor in neotree window will still toggle the display of hidden files and directories.</p> <p>Optionally, specify files or directories to never show. Practicalli Astronvim-config: plugins/core.lua<pre><code>  {\n    \"nvim-neo-tree/neo-tree.nvim\",\n    opts = {\n      filesystem = {\n        filtered_items = {\n          -- when true, they will just be displayed differently than normal items\n          visible = true,\n          -- remains hidden even if visible is toggled to true, this overrides always_show\n          never_show = {\n            \".DS_Store\",\n            \"thumbs.db\",\n          },\n        },\n      },\n    },\n  },\n</code></pre></p> <p>Space f t t to open file explorer</p> <p>Within Neo-tree:</p> <p>h j k l to navigate the file tree hierachy</p> <p>&lt; and &gt; to navigate between File, Bufs and Git sources tabs</p> <p>? shows neotree help, listing key bindings</p> <p>a adds a file, prompting for a name relative to the directory where a was pressed. The name can include new directories to be created. A name ending with ++forward-slash++ will create a directory rather than a file.</p> <p>d deletes the current file or directory (including sub-directories), a conformation prompt is shown</p> <p>r to rename a file or directory (use move to change the path)</p> <p>m to move a file or directory, optionally renaming too</p> <p>Neotree icons</p> <ul> <li>yellow dot - unsaved changes</li> <li>pencil - git added changes</li> <li>cross - git deleted changes</li> <li>Warning triangle - lsp diagnostics issues</li> </ul>"},{"location":"neovim-basics/file-buffer-window-tab/#telescope","title":"Telescope","text":"<p>Telescope provides a selector which will narrow the list of matches as a pattern is typed, providing a fast way to find an item in a list.</p> <p>Telescope provides a preview of the selected file (only if there is sufficient space in the Neovim frame)</p> <p>File lists are relative to the directory Neovim was opened from (or Path subsequently set in Neovim).</p> AstroNvimPracticalli Neovim Config Redux <p><code>SPC f f</code> selector for files within the scope of the current directory path. <code>SPC f F</code> to also show hidden files from the current directory path. </p> <p><code>SPC f a</code> selector for AstroNvim user configuration files</p> <p><code>SPC f p</code> selector for previously opened files (oldfiles)</p> <p><code>SPC f f</code> to list files within the scope of the current directory path.</p> <p><code>SPC f b</code> provides a file browser to open files, navigate the file space and create new files and directories</p>"},{"location":"neovim-basics/file-buffer-window-tab/#save-file","title":"Save File","text":"<p>Files and directories are created in the path given, relative to the directory in which Neovim was opened.</p> <p>A file must exist for Neovim to write to it.  Neo-tree and Telescope can be used to create files and directories, as can a terminal and the command line integration (!)</p> AstronvimPracticalli Neovim Config ReduxNeovim <p>Space w will write all buffer changes to the associate file.</p> <p>Space n creates a new buffer that can be written to a given file using <code>:write path/to/filename</code></p> <p><code>:write path/to/filename</code> will write the current buffer to a new file.</p> <p><code>SPC f b ESC C</code> to create a new file or directory. The base path is shown in the command bar.  Type the name of directories and file name as required. <code>RTN</code> to create or <code>ESC</code> to cancel.  The newly created directories or file name appears n the Telescope list and scan be selected for opening.</p> <p>Telescope Normal mode and help</p> <p><code>ESC</code> in Telescope to switch to Normal mode and use comannds, <code>c</code> for Create, <code>r</code> to rename.</p> <p><code>?</code> to show all the commands available in Telescope</p> <p><code>:lcd</code> to set the current local directory</p> <p><code>:write path/to/filename</code> will write the current buffer to a new file</p> <p><code>:!mkdir path/to/directory</code> will create a new directory</p> <p>If a file is already opened, i.e. with <code>:edit</code>, there is some short-hand syntax to simplify the typing</p> <p><code>:!mkdir -p %:h</code></p> <p><code>-p</code> option createst any parts of the path required to make the full path</p> <p><code>%</code> is the neovim name of the current file</p> <p><code>:h</code> for the current directory (the \u201chead\u201d of the path).</p> <p><code>!</code> is the NeoVim terminal shell command, e.g. <code>:!mkdir -p path/to/new/directory</code> creates a new directory and any intermediate path</p>"},{"location":"neovim-basics/file-buffer-window-tab/#swap-file","title":"Swap file","text":"<p>Neovim creates a swap file, <code>.swp</code>, containing the changes made in a buffer to minimise loss should there be an issue with the computer or Neovim.  Changes are written to the swap file after 200 characters or after 4 seconds pause. </p> Swap file location <p><code>:swapname</code> shows the full path to the swap file for the current buffer, e.g.  <pre><code>/home/practicalli/.local/state/astronvim/swap//%home%practicalli%projects%practicalli%books%neovim%docs%neovim-basics%files-buffers-windows.md.swp`\n</code></pre></p> <p><code>:preserve</code> command will write all text from current buffer to the swap file.</p> <p><code>:recover</code> command overwrites the current buffer with the data from the swap file.  <code>:recover!</code> command must be use if the buffer has newer changes than the swap file.  Add a filename after the command to recover to a different file than that contained in the current buffer. </p> <p>Opening a file checks if there is an associated swap file and prompts the user </p> <ul> <li>(A)bort opening the file</li> <li>(D)elete the swap file</li> <li>(E)dit anyway, select if the file is newer than the swap file</li> <li>(R)ecover the data in the swap file into the file buffer</li> </ul> <p><code>:edit</code> after the file is open also prompts if there is a swap file.  Selecting (D)elete will delete the swap file without changing the current buffer</p>"},{"location":"neovim-basics/file-buffer-window-tab/#buffers","title":"Buffers","text":"AstroNvimPracticalli Neovim Config Redux <p><code>SPC f b</code> selector for currently open buffers</p> <p><code>SPC b b</code> to select a buffer from the tab line, pressing the character that appears next to the buffer tab (case sensitive)</p> <p><code>SPC b D</code> to delete a buffer from the tab line, pressing the character that appears next to the buffer tab (case sensitive)</p> <p>Open multiple buffers when starting Neovim by specifying multiple files to open</p> <pre><code>astro README.md deps.edn src/practicalli/playground.clj test/practicalli/playground.clj\n</code></pre> <p><code>SPC b b</code> switch between buffers in the current window, using a Telescope popup that lists all current buffers (includes files, Conjure REPL Log, etc.).</p> <p><code>SPC b n</code> (<code>:next</code>) and <code>SPC b n</code> (<code>:previous</code>) to cycle through buffers in the current window</p> <p><code>SPC TAB</code> (<code>C-^</code>) opens the previous buffer, useful to toggle between two buffers in the same window</p> <p>Use Telescope to switch between buffers</p> <p></p> <p>Open multiple buffers when starting Neovim by specifying multiple files to open</p> <pre><code>nvim README.md deps.edn src/practicalli/playground.clj test/practicalli/playground.clj\n</code></pre>"},{"location":"neovim-basics/file-buffer-window-tab/#buffer-text-wrapping","title":"Buffer text wrapping","text":"<p>The test in a buffer is not wrapped by default. Set and unset soft text wrapping in a buffer</p> AstroNvimPracticalli Neovim Config ReduxNeovim <p><code>SPC u w</code> toggles wrapping of text</p> <p>line wrap not enabled in configuration by default.</p> fnl/config/init.fnl<pre><code>(nvim.ex.set :nowrap)\n</code></pre> <p><code>:set wrap</code> to set soft wrapping on current buffer</p> <p><code>:set nowrap</code> to show lines in full (scroll sideways to see lines longer than the window)</p>"},{"location":"neovim-basics/file-buffer-window-tab/#windows","title":"Windows","text":"<p>Windows can be active (contains the cursor), hidden (open but not shown) or inactive.</p> AstroNvimPracticalli Neovim Config ReduxNeovim <p><code>\\</code> creates an horizontal split</p> <p><code>SPC q</code> removes the current split</p> <p><code>SPC h</code> / <code>SPC l</code> to jump to left / right buffer,  <code>SPC j</code> / <code>SPC k</code> to jump to buffer below / above</p> <p><code>SPC b b</code> to list current buffers and switch between them using telescope</p> <p><code>C-w</code> and <code>hjkl</code> to navigate windows is the classic Vim approach</p> <p><code>C-w</code> menu to manage Windows, also known as splits.</p> <p><code>C-w</code> with one of <code>hjkl</code> will move the cursor to the next window in that direction.  Also works with arrow keys.</p> <p><code>C-w w</code> toggle between open windows</p> <p><code>:q</code> or <code>C-w q</code> closes the active window, closing Neovim if it is the last active window.</p> <p><code>:wincmd</code> can be used as an alternative to the Normal mode key bindings</p> <p>Open file in a new window</p> <pre><code>:sp relative-or-full-filename-path\n</code></pre> <p>Resize windows</p> <p><code>C-w</code> <code>-</code>, <code>+</code>, <code>&lt;</code> or <code>&gt;</code> for vertical or horizontal size adjustment</p>"},{"location":"neovim-basics/file-buffer-window-tab/#tab-pages","title":"Tab pages","text":"<p>A Tab page can hold one or more tabs and are useful for grouping different types of files and information. </p> <p>A Tab page holds one or more windows, each window is a view on a buffer, a buffer holds the contents of a file or any other information in the editor memory (repl log, etc).</p> <p>A tab page can provide a logical grouping of windows, e.g. Clojure source code in one tab, tests in a second tab and REPL log in a third.</p> <p>Neovim window commands may be constrained within the bounds of a tab page (without using the :tab modifier)</p> <p>Tab pages are often referred to as tabs.</p> AstroNvim <p>g Tab jump to previously selected tab, commonly used to toggle between two tabs  (Practicalli AstroNvim mapping)</p> <p>g t jump to next tab page</p> <p>g T jump to previous tab page</p>"},{"location":"neovim-basics/multi-modal-editing/","title":"Multi-modal Editing","text":"<p>TODO: Add multi-modal editing in Neovim guide</p> <p>Practicalli Spacemacs has useful reference content on multi-modal editing (Evil mode).</p> <p>Most of this content is the same in Neovim with a few exceptions</p>"},{"location":"neovim-basics/multi-modal-editing/#selecting-text","title":"Selecting text","text":"<p><code>vi)</code> selects all the text within <code>()</code>, e.g. <code>(http://oldwebsite.doh)</code></p>"},{"location":"neovim-basics/multi-modal-editing/#surround","title":"Surround","text":"<p><code>viw</code> selects the current word, using j/k to modify the selection where required. <code>o</code> toggles which end of the selection is expanded/shrunk</p> <p><code>s</code> substitues the selection, type the characters to surround the selection.</p> <p><code>p</code> to pase the original text</p>"},{"location":"neovim-basics/multi-modal-editing/#nvim-surround","title":"nvim-surround","text":"<p>nvim-surround provides enhancments over the neovim surround command.</p> <p>nvim-surround included in Practicalli AstroNvim Config</p>"},{"location":"neovim-basics/multi-modal-editing/#visual-mode","title":"Visual Mode","text":"<p><code>viw</code> to select the current word (visual in word)</p> <p>S  on a visual selection to surround with next that character, e.g. <code>S)</code> to surround with parens.</p> <p>Closing paren surrounds without spaces</p> <p><code>)</code>, <code>]</code>, <code>}</code> surrounds the selected text without spaces between the text and the open and closing parens.</p> <p><code>(</code>, <code>[</code>, <code>{</code> surrounds the selected text with a space between the text and the open and closing parens.</p>"},{"location":"neovim-basics/multi-modal-editing/#normal-mode","title":"Normal mode","text":"<p><code>cs</code> inside an existing pair of characters to change them to another pair of surrounding characters, e.g. <code>cs(}</code> to change (text) to {text}</p> <p><code>ds</code> inside a pair of surrounding characters to delete them, e.g. <code>ds(</code> to change (text) to text</p> <p><code>ys</code> you surround followed by motion and character, e.g. <code>ysw)</code> surrounds word with (parens)</p> <p><code>yS</code> to surround current line</p> <p><code>ySS</code> to surround current line, placing characters on new lines, e.g. <code>ySS{</code> will change \"Olical/conjure\" to:</p> <pre><code>{\n    \"Olical/conjure\"\n}\n</code></pre> <p>The three \"core\" operations of add/delete/change can be done with the keymaps ys{motion}{char}, ds{char}, and cs{target}{replacement}, respectively. For the following examples, * will denote the cursor position:</p> <pre><code>Old text                    Command         New text\n----------------------------------------------------\nsurr*ound_words             ysiw)           (surround_words)\n*make strings               ys$\"            \"make strings\"\n[delete ar*ound me!]        ds]             delete around me!\nremove &lt;b&gt;HTML t*ags&lt;/b&gt;    dst             remove HTML tags\n'change quot*es'            cs'\"            \"change quotes\"\n&lt;b&gt;or tag* types&lt;/b&gt;        csth1&lt;CR&gt;       &lt;h1&gt;or tag types&lt;/h1&gt;\ndelete(functi*on calls)     dsf             function calls\n</code></pre> <p>Neovim help provides details on using nvim-surround</p> <pre><code>:help nvim-surround.usage\n</code></pre>"},{"location":"neovim-basics/multi-modal-editing/#web-links","title":"Web Links","text":"<p>g x on a URL to open in the default browser</p>"},{"location":"neovim-basics/multi-modal-editing/#markdown","title":"Markdown","text":"<p><code>s</code> in visual mode substitues the selection with the next character typed</p> <p><code>v</code> to create visual selection, <code>s</code> to substitute the current selection, <code>****</code> to create a bold style, <code>P</code> with the cursor on the second <code>*</code> pastes the text that was visually selected. </p>"},{"location":"neovim-basics/multi-modal-editing/#text-style","title":"Text style","text":"<p><code>ysiw*</code> surrounds current word with <code>*</code> to create italic text, <code>.</code> repeats to make bold text style.</p> <p><code>ds*</code> removes <code>*</code> from current word.</p>"},{"location":"neovim-basics/multi-modal-editing/#nvim-surround_1","title":"nvim-surround","text":"<p>nvim-surround plugin assists with adding style characters around text, e.g adding links, italic or bold text, etc.</p> <p><code>S</code> on a visual selection will surround the text with the next character.  <code>.</code> repeat not supported.</p> <p>Create a link</p> <p><code>v</code> and motion keys to select text, <code>S [</code> to surround text with <code>[]</code> creating the text of a link anchor.  Use <code>S (</code> to surround the URL of the link.</p>"},{"location":"neovim-basics/multiple-cursors/","title":"Multiple cursors","text":"<p>Visual-Multi (VM) is a multiple selections/cursors plugin that uses modal editing and provide visual feedback when editing multiple lines simultaneously.</p> <p>Mulitple cursors is generally useful when editing smilarly structured lines with diffferent content.  Cursors are moved by column position or by using vim motions.</p> AstroNvimPracticalli Neovim Config Redux <p>Space g m opens the visual-multi menu</p> <p>Using visual select is a simple way to edit multiple lines as the same time.</p> <p>Space g m c on visually selected lines creates a cursor on each line.</p> <p>Esc or f d to close multiple cursors.</p> <p><code>\\ \\ c</code> creates a cursor at the start of every visual selection line</p> <p><code>\\ \\ \\</code> toggle cursor at position</p>"},{"location":"neovim-basics/multiple-cursors/#search-and-replace","title":"Search and Replace","text":"<p>Select a text pattern to search for and use multiple cursors to add a cursor each match, then change each selected occurance concurrently.</p> AstroNvimPracticalli Neovim Config Redux <p>Select the pattern with visual select</p> <p>Space g m a on each matching text pattern in the buffer</p> <p><code>c</code> to change the original text and type the new pattern.  All cursors will update concurrently.</p> <p>Esc or f d to close multiple cursors.</p> <p><code>\\ \\ a</code> creates a cursor at the start of every visual selection line</p> <p><code>\\ \\ \\</code> toggle cursor at position</p> <p><code>c</code> to change the original text and type the new pattern.  All cursors will update concurrently.</p> <p>Esc or f d to close multiple cursors.</p>"},{"location":"neovim-basics/multiple-cursors/#command-quick-reference","title":"Command quick reference","text":"<p><code>:help g:VM_maps</code> for a reference of all mappings and instructions on how to change them</p> AstroNvim <p><code>SPC g m</code> opens the Visual-Multi menu in normal mode</p> <p><code>g m</code> opens the Visual-Multi menu in visual mode</p> <p><code>c</code> to add a cursor to every line in the visually selected region</p> Practicalli Neovim Config Redux <p><code>\\ \\</code> is the leader for multiple cursors and will show the visual-multi menu in which-key.</p> <p>These commands cover the large majority of use cases for multiple cursors.</p> Action Key Command Add Cursor at Position <code>\\\\\\</code> <code>vm-add-cursor</code> Alignm VM cursors with cursor <code>\\\\a</code> <code>vm-align</code> Select All Words <code>\\\\A</code> <code>vm-select-all</code> Transposition <code>\\\\t</code> <code>vm-transpose</code> Toggle Mappings <code>\\\\&lt;Space&gt;</code> <code>vm-mappings-toggle</code> Find with Regex <code>\\\\/</code> <code>vm-regex-search</code> Reselect Last <code>\\\\gS</code> <code>vm-reselect-last</code> <p>Once visual-multi has started the vm-mappings-buffer mappings are available:</p> Action Key Command Find Word <code>&lt;C-n&gt;</code> vm-find-word Next/Previous/Skip <code>n</code> / <code>N</code> / <code>q</code> vm-find-next Remove Region <code>Q</code> vm-remove-region Add Cursors Down/Up <code>&lt;C-Down&gt;</code> / <code>&lt;C-Up&gt;</code> vm-add-cursors Select Right/Left <code>&lt;S-Right&gt;</code>, <code>&lt;S-Left&gt;</code> vm-shift-select Slash motion <code>g/</code> vm-slash Select Operator <code>s</code> vm-select-operator Find Operator <code>m</code> vm-find-operator <p>NOTE: <code>C-n</code> conflicts with the Termux binding for naming a session</p>"},{"location":"neovim-basics/multiple-cursors/#searching","title":"Searching","text":"<p><code>g/</code> to search for a match to add when visual-multi is active, rather than the usual <code>/</code> vim search.</p> <p><code>n</code> and <code>N</code> can't be used to repeat the search, as they are used to get the next visual-multi match.</p>"},{"location":"neovim-basics/multiple-cursors/#find-with-regex","title":"Find with Regex","text":"<p><code>\\ \\ /</code> followed by a regex pattern will create a selection with that pattern.</p> <p><code>n</code> and <code>N</code> finds the next occurrence of the regex pattern</p>"},{"location":"neovim-basics/multiple-cursors/#smart-case-change","title":"Smart case change","text":"<p><code>gc</code> In extend-mode will use smartcase to change a selection</p> <ul> <li>at main cursor, text is always inserted as typed</li> <li>at other cursors, if region text was fully uppercased, replacement will be uppercased as well</li> <li>if the region text was capitalized, the replacement will be as well</li> </ul>"},{"location":"neovim-basics/multiple-cursors/#filter-regions","title":"Filter regions","text":"<p><code>\\ \\ f</code> filter out (remove) regions based on pattern or expression.</p> <p><code>C-x</code> to cycle filtering method:</p> <ul> <li>pattern: remove regions that don't match the pattern</li> <li>!pattern:  remove regions that match the pattern</li> <li>expression: remove regions that don't match the expression (same as below)</li> </ul>"},{"location":"neovim-basics/multiple-cursors/#transform-regions-with-expression","title":"Transform regions with expression","text":"<p><code>\\ \\ e</code> to transform a region with a vim expression, run on each region</p> <p>Placeholders can be used in the expression</p> <ul> <li>`%t~ region's text as a string (as-is)</li> <li>`%f~ region's text evaluated as a floating point number</li> <li>`%n~ region's text evaluated as an integer number</li> <li>`%i~ region's index</li> <li>`%N~ total number of regions</li> </ul> <p>Examples: - <code>%f * 0.5</code> divide text of all regions by 2 - <code>%t .\" \". %i .\" / \". %n</code>  append index / total to text of each region - <code>%i%2 ? %t : toupper(%t)</code>  uppercase all odd regions (1,3,5...) - <code>%i%3-2 ? %t : ''</code>  delete every third region</p>"},{"location":"neovim-basics/multiple-cursors/#vm-motions","title":"VM Motions","text":"<p>visual-multi supports vim motions although they behave differently as their result is dependent on the mode:</p> <ul> <li><code>cursor mode</code> will move cursors</li> <li><code>extend mode</code> motions extend selections</li> </ul> <p>Unless multiline-mode is enabled motions are restricted to the current line and cannot cross line boundaries</p> <p>Some object-motions and various-motions require multiline-mode and aliased to avoid conflict with VM mappings:</p> vim VM~ Description / g/ to next match (for all regions) ( ( [count] sentences backward ) ) [count] sentences forward { { [count] paragraphs backward } } [count] paragraphs forward [( g( go to [count] previous unmatched '(' [{ g{ go to [count] previous unmatched '{' ]) g) go to [count] next unmatched ')' ]} g} go to [count] next unmatched '}'"},{"location":"neovim-basics/multiple-cursors/#vm-operators","title":"vm-operators","text":"<p>Visual-Multi supports several operators by default:</p> <ul> <li><code>y</code> / <code>d</code> / <code>c</code> to yank / delete / change</li> <li><code>gu</code> / <code>gU</code> to change text case</li> </ul> <p>Visual-Multi uses its own registers that are lists of strings. One element for each region that is yanked/deleted.</p> <p>There is also built-in support for:</p> <ul> <li>vim-surround  e.g. <code>ysiw(</code> to enclose in parentheses</li> <li>vim-abolish e.g. <code>cr_</code> to change current word to snake case</li> </ul> <p>`:help g:VM_user_operators to disccover how to doefine other operators</p>"},{"location":"neovim-basics/multiple-cursors/#vm-multiline-mode","title":"vm-multiline-mode","text":"<p>In normal and insert mode, cursors and selections are kept within their own line.  Cursors are blocked from moving off the current line to the next line.</p> <p><code>M</code> enables multiline-mode that allows cuursors to move onto another line.</p> <p>Multiline mode must be enabled for an object motions, or they will fail. See |vm-motions|.</p>"},{"location":"neovim-basics/multiple-cursors/#alignment","title":"Alignment","text":"<p><code>\\\\a</code> aligns by setting the minimum column to the highest of all regions <code>\\\\&lt;</code> aligns by character, or [count] characters <code>\\\\&gt;</code> aligns by regex pattern</p> <p>In extend-mode selections are collapsed to cursors first, although will work regardless.</p>"},{"location":"neovim-basics/multiple-cursors/#replace-pattern-in-regions","title":"Replace pattern in regions","text":"<p><code>R</code> to replace with a pattern and then the replacement text</p> <p>substitution will take place in all selected regions, leaving unselected text untouched.</p> <p>Only working in |extend-mode|. When |R| is pressed in |cursor-mode|, it will start |vm-replace-mode| instead.</p>"},{"location":"neovim-basics/multiple-cursors/#subtract-pattern-from-regions","title":"Subtract pattern from regions","text":"<p><code>\\\\s</code> subtract the entered pattern from regions, splitting them. Only working in |extend-mode|.</p>"},{"location":"neovim-basics/multiple-cursors/#transposition","title":"Transposition","text":"<p><code>\\ \\ t</code> swaps the contents of selections, cycling them if there are more than two.</p> <p>If there is an equal number of selections in each line, swapping takes place within the same line only. Only in |extend-mode|.</p>"},{"location":"neovim-basics/multiple-cursors/#duplication","title":"Duplication","text":"<p><code>\\ \\ d</code> duplicates in place the contents of the selections, reselecting the original ones. Only in extend-mode.</p>"},{"location":"neovim-basics/multiple-cursors/#shift-selections","title":"Shift Selections","text":"<p> and  move the selections right or left, preserving the surroundings."},{"location":"neovim-basics/multiple-cursors/#case-conversion","title":"Case conversion","text":"<p><code>\\\\C</code> runs on inner words in cursor mode</p> <ul> <li><code>u</code> lowercase</li> <li><code>U</code> UPPERCASE</li> <li><code>C</code> Captialize</li> <li><code>t</code> Title Case</li> <li><code>c</code> camelCase</li> <li><code>P</code> PascalCase</li> <li><code>s</code> snake_case</li> <li><code>S</code> SNAKE_UPPERCASE</li> <li><code>-</code> dash-case</li> <li><code>.</code> dot.case</li> <li><code>&lt;space&gt;</code> space case</li> </ul>"},{"location":"neovim-basics/multiple-cursors/#modes","title":"Modes","text":"<p>cursor-mode and extend-mode are two Visual-Multi modes, roughly corresponding to normal-mode and visual-mode</p> <p><code>TAB</code> switches between cursor-mode and extended-mode</p>"},{"location":"neovim-basics/multiple-cursors/#vm-cursor-mode","title":"VM Cursor Mode","text":"<p>cursor-mode commands expect a motion, e.g. <code>c</code> should be followed by a text object to be changed.</p> Key Description <code>operators</code> see vm-operators <code>motions</code> see vm-motions <code>|</code> set column for all cursors (to current column or [count]) <code>r</code> replace single character <code>R</code> enter vm-replace-mode <code>~</code> change case of single character <code>&amp;</code> repeat last substitution <code>&lt;C-A&gt;</code> increase numbers <code>&lt;C-X&gt;</code> decrease numbers <code>g&lt;C-A&gt;</code> progressively increase numbers (<code>v_g_CTRL-A</code>) <code>g&lt;C-X&gt;</code> progressively decrease numbers (<code>v_g_CTRL-X</code>) <p>You can enter |insert-mode| with <code>i</code>, <code>I</code>, <code>a</code>, <code>A</code>, and only from cursor mode also with <code>o</code> and <code>O</code>.</p> <p>Also see <code>vm-motions</code> for supported motions in VM (some with differences).</p>"},{"location":"neovim-basics/multiple-cursors/#vm-extend-mode","title":"VM Extend Mode","text":"<p>extend-mode is like having multiple visual selections.  motions extend the slections and change / yank / delete commands don't wait for a motion, just like in visual mode.</p> <p>Even the key <code>o</code> works as in visual mode, inverting the anchor of the selections.</p> <p>Some commands are specific to |extend-mode|, such as:</p> <ul> <li><code>s</code> vim-surround</li> <li><code>R</code> replace pattern in regions</li> <li><code>\\\\s</code> split regions by pattern</li> <li><code>\\\\e</code> transform regions text with vim expression</li> </ul> <p>Some commands enforce cursor-mode when run from extend-mode:</p> <ul> <li><code>&lt;C-A&gt;</code> increase numbers</li> <li><code>&lt;C-X&gt;</code> decrease numbers</li> </ul> <p>Others can use a different mapping:</p> <ul> <li><code>gu/gU</code> change case (instead of vim <code>u</code> / <code>U</code>)</li> <li><code>o</code> and <code>O</code> mappings are used to invert the facing of the selected regions and not to start insert mode.</li> </ul>"},{"location":"neovim-basics/notifications/","title":"Notifications","text":"Notifications only in AstroNvim, not the Practicalli Neovim configuration <p>Space f n lists the history of notifications for the current sesion</p> <p>Enter to open the highlighted item in the list in its own popup</p> <p> </p> <p>Notification popups show information, warnings and errors.</p> <p></p>"},{"location":"neovim-basics/notifications/#configure-notifications","title":"Configure notifications","text":"<p>Notifications are controlled by  nvim-notify</p> <p> Practicalli astronvim-config overrides several default values in <code>plugins/core.lua</code></p> <ul> <li><code>top_down</code> position of notifications, <code>false</code> shows popups from bottom of screen</li> <li><code>timeout</code> value controls how long a popup displays, defautl <code>3000</code></li> <li><code>level</code> of information displayed, level 3 hides less important information, e.g. file write messages, default 5</li> </ul> <p>Practicalli Configuration for notifications</p> plugins/core.lua<pre><code>  -- Configure notify popups\n  {\n    \"rcarriga/nvim-notify\",\n    opts = {\n      top_down = false,\n      timeout = 1000,\n      -- log level - 3 hide file write messages - default 5\n      level = 3,\n      -- background_color = \"#000000\",\n    },\n  },\n</code></pre> <p>Noice uses nvim-notify configuration</p> <p>Noice replaces the UI for messages, command line and popup menus, although uses the configuration of nvim-notify for position and popup timing.</p>"},{"location":"neovim-basics/plugin-manager/","title":"Plugin Manager","text":"<p>Neovim community provides a wide range of plugins to greatly extend the features of Neovim</p> <p>There is a wide range of plugin managers too, including a built-in plugin manager in Neovim.</p> <ul> <li>Lazy - AstroNvim Config</li> <li>Packer - Practicalli Neovim Config Redux</li> </ul> <p>Lazy plugin manager recommeded</p> <p>Practicalli recommends Lazy plugin manager as it feels much easier to use and has a more engaing and understandable user interface</p> Neovim evolving <p>Neovim and its plugins are evolving quite rapidly, so it is recommended to update plugins if there are issue or when a newer version of Neovim has been installed</p> <p>Plugin issue are not that common and typically fixed quite quickly by the community</p> AstroNvimPracticalli Neovim Config Redux <p>Lazy plugin manager</p> <p> </p> <p><code>SPC P u</code> to update packages to their latest versions (<code>:PackerUpdate</code>).  Details of updated changes will be shown at the end of the update.</p> <p></p> <p><code>r</code> in the package update screen gives the option to revert an update if something has gone wrong (although this seem to be a rare issue).</p> <p>When packages are all at the latest available version, Packer update reports packages already up to date.</p> <p></p> <p>Packer downloads packages and documentation from the Internet, so a connection is required</p>"},{"location":"neovim-basics/plugin-manager/#package-list-and-documentation","title":"Package List and documentation","text":"AstroNvimPracticalli Neovim Config Redux <p>Lazy plugin manager</p> <p><code>SPC P l</code> to list the current packages added to the configuration</p> <p></p> <p>Selecting a package will display the website documentation for the package (although this may be in HTML so not the cleanest way to read the docs).</p>"},{"location":"neovim-basics/plugin-manager/#adding-packages","title":"Adding packages","text":"AstroNvimPracticalli Neovim Config Redux <p>Lazy plugin manager</p> <p>Add package names as keywords in the <code>use</code> expression in <code>fnl/config/plugin.fnl</code> file.</p> <p><code>:requires</code> to add a package that is a dependency for the package being added</p> <p><code>:mod</code> defines the namespace that contains the package configuration, typically a <code>setup</code> function with options.  The namespace matches the file name under <code>fnl/config/plugin</code></p> <p><code>SPC P i</code> to install packages that have been added to <code>fnl/config/plugin.fnl</code></p> <p><code>q</code> to quit once all packages are up to date</p>"},{"location":"neovim-basics/snippets/","title":"Snippets","text":"<p>LuaSnip can use several different sources for snippets</p> <ul> <li>VSCode JSON snippets (Friendly-snippets)</li> <li>LSP style snippets </li> </ul> LuaSnip Configuration <p>Practicalli Neovim Config Redux includes the LuaSnip package which also adds friendly-snippets and cmp_luasnip. <pre><code>  ; snippets\n  :L3MON4D3/LuaSnip \n  {:requires [:rafamadriz/friendly-snippets\n              :saadparwaiz1/cmp_luasnip]\n   :mod :lua-snip}\n</code></pre> Configure LSP snippet locations <pre><code>{\n  \"name\": \"practicalli-snippets\",\n  \"engines\": {\n    \"vscode\": \"^1.11.0\"\n  },\n  \"contributes\": {\n    \"snippets\": [\n      {\n        \"language\": [\n          \"markdown\",\n          \"global\",\n          \"all\"\n        ],\n        \"comment\": \"snippets accross several languages\",\n        \"path\": \"./global.json\"\n      },\n      {\n        \"language\": \n          \"markdown\",\n        \"path\": \"./markdown.json\"\n      }\n    ]\n  }\n}\n</code></pre></p>"},{"location":"neovim-basics/snippets/#snippet-definitions","title":"Snippet Definitions","text":"<p><code>snippets</code> directory contains snippet definitions, with a JSON file for each language, e.g. <code>markdown.json</code></p> <p>Practicalli Neovim Config Redux contains several groups of snippet definitions</p> <ul> <li>MkDocs format and icons (<code>markdown.json</code> VSCode syntax)</li> </ul> <p>Restart Neovim to load new defintions</p> <p>Snippets added to VSCode JSON snippets are only loaded when Neovim starts, so newly added snippets will only be available after Neovim is restarted.</p>"},{"location":"neovim-basics/terminal/","title":"Terminal","text":"<p>akinsho/toggleterm.nvim plugin provides a terminal session within Neovim, using a float, split or tab.</p> AstroNvim <p><code>SPC t</code> for the Terminal sub-menu </p> <p><code>SPC t f</code> opens a terminal in a floating window, useful for one-off commands</p> <p><code>SPC t h</code> opens a terminal in a horizontal split, useful for a process that prints valuable feedback, e.g. a test runner in watch mode</p> <p><code>SPC t t</code> opens a terminal in a tab, useful for background processes that do not need attendtion </p> <p> </p>"},{"location":"neovim-basics/zen-mode/","title":"Focus Modes","text":"<p>Focus on the code or text being created, without distractions</p> <p><code>zZ</code> toggles Zen mode</p> <p><code>SPC z a</code> ataraxis focus mode</p> <p><code>SPC z f</code> focus current buffer</p> <p><code>SPC z n</code> narrow to current buffer</p> <p><code>SPC z n</code> remove status bar and window decorations</p> <p><code>v SPC z n</code> narrow to selection</p>"},{"location":"neovim-basics/zen-mode/#zen-mode","title":"Zen Mode","text":"<p>Zen Mode distraction-free coding for Neovim</p> <p>Available via the Astrocommunity repository.</p> <p>Zen Mode configuration for AstroNvim</p> .config/astronvim-config/plugins/community.lua<pre><code>  { import = \"astrocommunity.editing-support.zen-mode-nvim\" },\n  {\n    \"folke/zen-mode.nvim\",\n    opts = {\n      -- override default configuration\n      -- https://github.com/folke/zen-mode.nvim#%EF%B8%8F-configuration\n      plugins = {\n        options = {\n          enabled = true,\n        },\n        kitty = {\n          enabled = true,\n          font = \"+4\", -- font size increment\n        },\n      },\n    },\n  },\n</code></pre> <p>kitty configuration enables Zen Mode to resize kitty fonts.</p>"},{"location":"neovim-basics/zen-mode/#true-zen","title":"True Zen","text":"<p>true-zen.nvim clean and elegant distraction-free writing for NeoVim</p> <p>True Zen Mode configuration for AstroNvim</p> <pre><code>  {\n    \"Pocco81/true-zen.nvim\",\n    lazy = false,\n    opts = {\n      integrations = {\n        kitty = {\n          -- increment font size in Kitty.\n          enabled = true,\n          font = \"+4\",\n        },\n      },\n    },\n  },\n</code></pre> <p>See kitty configuration to enable Zen Mode to resize kitty fonts.</p>"},{"location":"neovim-basics/zen-mode/#kitty-configuration","title":"Kitty configuration","text":"<p>Add <code>allow_remote_control socket-only</code> and <code>listen_on unix:/tmp/kitty</code> to the kitty config</p> <p>Kitty support for Zen Mode</p> .config/kitty/kitty.config<pre><code># ---------------------------------------------------------\n#  Neovim zen-mode-nvim\n#  - change the font size on kitty when in zen mode\nallow_remote_control socket-only\nlisten_on unix:/tmp/kitty\n# ---------------------------------------------------------\n</code></pre>"},{"location":"neovim-basics/search-replace/","title":"Search and Replace","text":"<p>Search and replace within the current line or buffer:</p> <ul> <li><code>g m A</code> will match text under curor allowing in-place editing with visual-multi plugin </li> <li><code>:%substitue</code> vim-style search and replace</li> </ul> <p>Search and replace across a project:</p> <ul> <li><code>SPC s</code> AstroNvim search and replace commands using Spectre (community plugin)</li> <li>Clojure LSP for symbols, etc.</li> </ul> Multiple cursors for multiple substitutions <p>g m A with the cursor on a word will start multiple cursors with a cursor on each occurance.  Vim-editing tools can be used to replace the text at all cursors simultaneously</p>"},{"location":"neovim-basics/search-replace/#buffer-wide","title":"Buffer wide","text":"<p>Replace all occurances of the current-pattern with the new pattern within the buffer.</p> <pre><code>:%s/current-pattern/new-pattern/g\n</code></pre> <p>Further examples of <code>:substitue</code> neovim command</p>"},{"location":"neovim-basics/search-replace/#project-wide","title":"Project wide","text":"<p>Evaluating...</p> AstroNvimNeovim commands <p>Spectre is available via the AstroNvim Community project pack and included in the Practicalli astronvim-config    </p> <p>Space s is the search and replace menu</p> <p>ripgrep and sed are required.</p> <p>Spectre </p> <p>Vims new :cdo command</p> Neovim :help :cdo <pre><code>EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST:\n                            *:cdo*\n:cdo[!] {cmd}       Execute {cmd} in each valid entry in the quickfix list.\n            It works like doing this:  \n                :cfirst\n                :{cmd}\n                :cnext\n                :{cmd}\n                etc.\n            When the current file can't be |abandon|ed and the [!]\n            is not present, the command fails.\n            When going to the next entry fails execution stops.\n            The last buffer (or where an error occurred) becomes\n            the current buffer.\n            {cmd} can contain '|' to concatenate several commands.\n\n            Only valid entries in the quickfix list are used.\n            A range can be used to select entries, e.g.:  \n                :10,$cdo cmd\n            To skip entries 1 to 9.\n\n            Note: While this command is executing, the Syntax\n            autocommand event is disabled by adding it to\n            'eventignore'.  This considerably speeds up editing\n            each buffer.\n            Also see |:bufdo|, |:tabdo|, |:argdo|, |:windo|,\n            |:ldo|, |:cfdo| and |:lfdo|.\n\n                            *:cfdo*\n:cfdo[!] {cmd}      Execute {cmd} in each file in the quickfix list.\n            It works like doing this:  \n                :cfirst\n                :{cmd}\n                :cnfile\n                :{cmd}\n                etc.\n            Otherwise it works the same as `:cdo`.\n\n                            *:ldo*\n:ld[o][!] {cmd}     Execute {cmd} in each valid entry in the location list\n            for the current window.\n            It works like doing this:  \n                :lfirst\n                :{cmd}\n                :lnext\n                :{cmd}\n                etc.\n            Only valid entries in the location list are used.\n            Otherwise it works the same as `:cdo`.\n\n                            *:lfdo*\n:lfdo[!] {cmd}      Execute {cmd} in each file in the location list for\n            the current window.\n            It works like doing this:  \n                :lfirst\n                :{cmd}\n                :lnfile\n                :{cmd}\n                etc.\n            Otherwise it works the same as `:ldo`.\n</code></pre>"},{"location":"neovim-basics/search-replace/substitute/","title":"Substitute command","text":"<p><code>:substitute</code> or <code>:s</code> command highlights the matches for a text pattern and substitute for a new pattern</p> Neovim :help :substitute <pre><code>:help :substitute\n</code></pre> <p>Subsitute the first matching patterns in the current line</p> <pre><code>:s/current-pattern/new-pattern/\n</code></pre> <p>If the new-pattern text is ommitted, then substitute deletes the current-pattern occurances, e.g <code>:s/current-pattern//</code></p> <p>Subsitute all the matching patterns in the current line,  <code>g</code> representing all occurances in a line</p> <pre><code>:s/current-pattern/new-pattern/g\n</code></pre> <p>Use <code>%</code> to specify the current buffer as the scope to change all matches</p> <pre><code>:%s/current-pattern/new-pattern/g\n</code></pre> <p>An inclusive line range can be specified to narrow the search</p> <pre><code>:4,24s/current-pattern/new-pattern/g\n</code></pre> <p><code>.</code> can be used to represent the current line of buffer</p> <p><code>$</code> to represent the last line of the current buffer</p> <pre><code>:.,$s/current-pattern/new-pattern/g\n</code></pre> <p>Match the whole word </p> <pre><code>:.,$s/\\&lt;current-pattern\\&gt;/new-pattern/g\n</code></pre>"},{"location":"neovim-basics/search-replace/substitute/#substitute-history","title":"Substitute history","text":"<p><code>:s</code> and the Up / Down will navigate through the substitution history for the current session (from when Neovim was last opened if session was not restored)</p>"},{"location":"neovim-basics/search-replace/substitute/#confirm-replacement","title":"Confirm replacement","text":"<p>c option at the end prompt for confirmation to replace each occurance</p> <pre><code>:%s/current-pattern/new-pattern/gc\n</code></pre> <p>y confirms the repacement </p> <p>l confirms the repacement and quits</p> <p>n skips the current occurance and goes to the next one</p> <p>y or Esc to quit substitution</p>"},{"location":"neovim-basics/search-replace/substitute/#regular-expression","title":"Regular expression","text":"<p>regular expressions can be used as a search pattern. </p> <p>To replace all lines starting with \u2018foo\u2019 with \u2018NeoVim Rocks\u2019:</p> <pre><code>:%s/^foo.*/NeoVim rocks/gc\n</code></pre> <p>Replace all instances of \u2018apple\u2019, \u2018orange\u2019, and \u2018mango\u2019 with \u2018fruit\u2019:</p> <pre><code>:%s/apple\\|orange\\|mango/fruit/g\n</code></pre> <p>Remove trailing blank space at the end of each line:</p> <pre><code>:%s/\\s\\+$//e\n</code></pre>"},{"location":"neovim-basics/search-replace/substitute/#matching-case","title":"Matching case","text":"<p><code>i</code> option disables the default case sensitive search</p> <pre><code>:%s/current-pattern/new-pattern/gi\n</code></pre>"},{"location":"neovim-basics/search-replace/substitute/#visual-select","title":"Visual Select","text":"<p>Use a visual select to search and replace, with confirmation</p> <p>Note: <code>'&lt;,'&gt;</code> is automatically included when in visual mode and <code>:</code> is pressed to start a command </p> <pre><code>:'&lt;,'&gt;s/search-text/replace-text/g\n</code></pre> <p>A potentially more effecitve approach:</p> <ul> <li>visually select the text</li> <li><code>*</code> to select all matching occurances</li> <li><code>:%s//replace-text/g</code></li> </ul>"},{"location":"reference/lua-language/","title":"Lua","text":"<p>Lua is the default language for Neovim configuration.</p>"},{"location":"reference/lua-language/#learning-lua","title":"Learning Lua","text":"<p> Neovim Lua introduction</p> <p> Lua.org - Programming in Lua (first edition)</p> <p> Codecademy - learn lua course</p>"},{"location":"reference/lua-language/#reference","title":"Reference","text":"<p> Lua.org 5.4 Reference Manual</p>"},{"location":"reference/neovim/","title":"Neovim Reference","text":"<ul> <li>Language Providers</li> <li>Key mappings</li> </ul>"},{"location":"reference/neovim/language-providers/","title":"Language Providers","text":"<p>Neovim delegates some features to language providers.</p> <p><code>:checkhealth</code> command in Neovim shows if the binaries and tools required by each provider are available in the operating system.</p> <p>Resolve the issue with providers that generate a warning in the checkhealth report, following the ADVICE steps provided.</p>"},{"location":"reference/neovim/language-providers/#disable-language-providers","title":"Disable Language Providers","text":"<p>If a language is not used with Neovim, then its provider can be disabled.  Details on how to disable a provider are included at the end of the ADVICE in the report section for that provider.</p> <p></p> <p>Disable language providers in the <code>init.lua</code> configuration file</p> init.lua<pre><code>-- Disable Language providers\nvim.g.loaded_node_provider = 0       --- (1)!\nvim.g.loaded_perl_provider = 0\nvim.g.loaded_python3_provider = 0\nvim.g.loaded_ruby_provider = 0\n</code></pre> <ol> <li>Example configuration to disable providers is provided in the practicalli/neovim-config-redux configuration</li> </ol> <p>Ignore Language Provider warnings</p> <p>If the programming language is not used, there are no issues with using Neovim if the warnings are simply ignored</p>"},{"location":"reference/neovim/standard-path/","title":"Neovim Standard Path","text":"<p>View the standard paths used by Neovim using the help menu</p> <pre><code>:help standard-path\n</code></pre> <p>Output of command</p> <pre><code>Standard Paths                  *standard-path*\n\nNvim stores configuration, data, and logs in standard locations. Plugins are\nstrongly encouraged to follow this pattern also. Use |stdpath()| to get the\npaths.\n\n                        *base-directories* *xdg*\nThe \"base\" (root) directories conform to the XDG Base Directory Specification.\nhttps://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html\nThe $XDG_CONFIG_HOME, $XDG_DATA_HOME, $XDG_RUNTIME_DIR, and $XDG_STATE_HOME\nenvironment variables are used if defined, else default values (listed below)\nare used.\n\nCONFIG DIRECTORY (DEFAULT) ~\n                  *$XDG_CONFIG_HOME*            Nvim: stdpath(\"config\")\n    Unix:         ~/.config                   ~/.config/nvim\n    Windows:      ~/AppData/Local             ~/AppData/Local/nvim\n\nDATA DIRECTORY (DEFAULT) ~\n                  *$XDG_DATA_HOME*              Nvim: stdpath(\"data\")\n    Unix:         ~/.local/share              ~/.local/share/nvim\n    Windows:      ~/AppData/Local             ~/AppData/Local/nvim-data\n\nRUN DIRECTORY (DEFAULT) ~\n                  *$XDG_RUNTIME_DIR*            Nvim: stdpath(\"run\")\n    Unix:         /tmp/nvim.user/xxx          /tmp/nvim.user/xxx\n    Windows:      $TMP/nvim.user/xxx          $TMP/nvim.user/xxx\n\nSTATE DIRECTORY (DEFAULT) ~\n                  *$XDG_STATE_HOME*             Nvim: stdpath(\"state\")\n    Unix:         ~/.local/state              ~/.local/state/nvim\n    Windows:      ~/AppData/Local             ~/AppData/Local/nvim-data\n\nNote: Throughout the user manual these defaults are used as placeholders, e.g.\n\"~/.config\" is understood to mean \"$XDG_CONFIG_HOME or ~/.config\".\n\nLOG FILE                    *$NVIM_LOG_FILE* *E5430*\nBesides 'debug' and 'verbose', Nvim keeps a general log file for internal\ndebugging, plugins and RPC clients. &gt;\n    :echo $NVIM_LOG_FILE\nBy default, the file is located at stdpath('log')/log unless that path\nis inaccessible or if $NVIM_LOG_FILE was set before |startup|.\n</code></pre>"},{"location":"reference/vim-style/","title":"Reference: Learn Vim-style Editing","text":"<p>Learning vim-style multi-modal editing takes time and practice.  Most importantly this approach can be learned in stages, as insert mode is the same editing experience as using most other editors.</p> <p>Start with the multi-modal concept and the basics of navigation.  Then adopt more normal and visual mode actions, including motions </p>"},{"location":"reference/vim-style/#getting-started","title":"Getting started","text":"<p><code>:Tutor</code> runs the intteractive tutorial built into neovim <code>(:help tutor</code> also runs the tutor)</p> <p>vim adventures isa simple online game to teach you the fundamentals of vim-style editing.</p>"},{"location":"reference/vim-style/#navigation-and-searching","title":"Navigation and searching","text":"<ul> <li>moving the cursor</li> <li>Motions </li> <li>line numbers </li> <li>jumping around a buffer</li> <li>search and replace</li> </ul>"},{"location":"reference/vim-style/#text-wrangling","title":"Text wrangling","text":"<ul> <li>iedit</li> <li>text case</li> </ul>"},{"location":"reference/vim-style/#clojure-editing","title":"Clojure Editing","text":"<p>traversing expressions  structural editing </p>"},{"location":"reference/vim-style/case/","title":"Modifying text case","text":"<p>Convert Characters and regioins to upper or lower case text.</p>"},{"location":"reference/vim-style/case/#toggle-case-with-visual-select","title":"Toggle case with visual select","text":"<p><code>v</code> to visually select a character or use the vim motion keys to select a region</p> <p><code>U</code> to uppercase current character or selected region </p> <p><code>u</code> to lowercase current character or selected region </p> <p><code>~</code> to toggle the case of the text in the selected region</p> <p><code>.</code> will repeat the previous selection size and case toggle</p>"},{"location":"reference/vim-style/case/#toggle-case-menu","title":"Toggle case menu","text":"<p>Toggle the current character using vim motion keys, without needing to select a region.</p> <p><code>g ~</code> opens the toggle case menu</p> <p>TODO: Add screenshot of <code>g ~</code> toggle case menu</p> <p><code>g ~ ~</code> uppercase current line (also works for <code>RET</code> and maybe other none-menu characters, but not <code>SPC</code>)</p>"},{"location":"reference/vim-style/case/#cheatsheet","title":"Cheatsheet","text":"<ul> <li><code>~</code> Changes the case of current character</li> <li><code>guu</code> Change current line from upper to lower.</li> <li><code>gUU</code> Change current LINE from lower to upper.</li> <li><code>guw</code> Change to end of current WORD from upper to lower.</li> <li><code>guaw</code> Change all of current WORD to lower.</li> <li><code>gUw</code> Change to end of current WORD from lower to upper.</li> <li><code>gUaw</code> Change all of current WORD to upper.</li> <li><code>g~~</code> Invert case to entire line</li> <li><code>g~w</code> Invert case to current WORD</li> <li><code>guG</code> Change to lowercase until the end of document.</li> <li><code>gU)</code> Change until end of sentence to upper case</li> <li><code>gu}</code> Change to end of paragraph to lower case</li> <li><code>gU5j</code> Change 5 lines below to upper case</li> <li><code>gu3k</code> Change 3 lines above to lower case</li> </ul>"},{"location":"reference/vim-style/g-menu/","title":"Evil G menu","text":"<p>g` in normal mode opens a menu of convenient utilities.  Practicalli uses this menu to comment existing lines, jumping to top or bottom of the buffer and changing text case.</p>"},{"location":"reference/vim-style/g-menu/#comment-lines-and-regions","title":"Comment lines and regions","text":"<p><code>g c c</code> will comment the current line using the buffer major mode comment character(s).  A prompt will ask if no comment character is set for the major mode.</p> <p><code>g c</code> with a selected region will comment all lines with the major mode comment character(s)</p>"},{"location":"reference/vim-style/g-menu/#jumping-around","title":"Jumping around","text":"<p><code>g g</code> jumps to the top of the buffer, <code>g G</code> to the bottom of the buffer</p> <p><code>g d</code> to jump to the source code of a function definition, <code>g D</code> to open that in a different window.</p> <p><code>g f</code> to jump to file name under cursor (if file exists).</p>"},{"location":"reference/vim-style/g-menu/#changing-text-case","title":"Changing text case","text":"<p><code>g u</code> to change the current character or selection to lowercase, <code>g U</code> for uppercase.</p> <p>Toggle case with <code>~</code></p> <p><code>~</code> will toggle the case of the current character or selected region.</p>"},{"location":"reference/vim-style/key-binding-reference/","title":"Evil Keybinding Reference","text":"<p>An alphabetically ordered reference of Vim-style key bindings.</p>"},{"location":"reference/vim-style/key-binding-reference/#normal-mode-keybindings","title":"Normal mode keybindings","text":"<p>Keybindings available in Evil normal mode and the resultant state they leave you in.</p> Keybinding Description State <code>@</code> execute keyboard macro (defined by <code>q</code>) Normal <code>'</code> jump to mark (defined by <code>m</code>) Normal <code>a</code> append text after cursor Insert <code>a</code> append text after cursor Insert <code>A</code> append text to end of sentence Insert <code>b</code> move cursor back to start of previous word Normal <code>B</code> move cursor back to start of last word Normal <code>c</code> change (use with modifier) Insert <code>C</code> change rest of sentence Insert <code>d</code> delete (use with modifier) Normal <code>D</code> delete rest of sentence Normal <code>e</code> end of word Normal <code>E</code> end of word  (seems same as above) Normal <code>f</code> find character forward (type character) Normal <code>F</code> find character backward (type character) Normal <code>fd</code> Escape (press almost together) Normal <code>g</code> go menu Normal <code>G</code> Jump to end of buffer Normal <code>h</code> move cursor left Normal <code>H</code> move cursor to top of buffer Normal <code>i</code> insert text Insert <code>I</code> insert text at start of sentence Insert <code>j</code> Move cursor down a line Normal <code>J</code> Join next line to end of current Normal <code>k</code> Move cursor up a line Normal <code>K</code> <code>spacemacs/evil-smart-doc-lookup</code> Normal <code>l</code> Move cursor right Normal <code>L</code> Move cursor to bottom of buffer Normal <code>m</code> Create marker (next character is marker name) Normal <code>M</code> Jump to middle of buffer Normal <code>n</code> Next search occurrence Normal <code>N</code> Previous search occurrence Normal <code>o</code> New line below Insert <code>O</code> New line above Insert <code>p</code> Paste (after / below cursor) Insert <code>P</code> Paste (before / above cursor) Insert <code>q</code> Record keyboard macro attached to given character Normal <code>Q</code> undefined Normal <code>r</code> Replace character under cursor Normal <code>R</code> Replace character state Replace <code>s</code> Substitute character Insert <code>S</code> Substitute current line Insert <code>t</code> Find character forward - cursor before character Normal <code>T</code> Find character backward - cursor after character Normal <code>u</code> Undo last change (C-R to redo) Normal <code>U</code> Undefined Normal <code>v</code> Visual select Visual <code>V</code> Visual select sentence Visual <code>w</code> Jump cursor to start of next word Normal <code>W</code> Jump cursor to start of next word Normal <code>x</code> Delete character under cursor Normal <code>X</code> Delete character backwards Normal <code>y y</code> Yank (copy) line Normal <code>Y</code> Yank (copy) line Normal <code>z</code> Menu - code folding / keyboard macros Normal"},{"location":"reference/vim-style/motions/","title":"Motions","text":"<p>Todo</p> <p>Moving the cursor around by context rather than individual characters</p>"},{"location":"reference/vim-style/moving-around/","title":"Moving around the cursor","text":"<p>Scrolling is quite inefficient in most editors and moving (jumping) the curor around is far more effective.</p> <p>Using the <code>h</code> <code>j</code> <code>k</code> <code>l</code> as a common part of navigation provides consistency and keeps fingers on the most convienient part of the keyboard.</p>"},{"location":"reference/vim-style/moving-around/#moving-by-charater","title":"Moving by charater","text":"<p><code>h</code> <code>j</code> <code>k</code> <code>l</code> keys move the cursor once character or can be used with numbers to move further.</p> <ul> <li><code>h</code> move left (often used to move up a path or tree, e.g. a directory path)</li> <li><code>j</code> move down</li> <li><code>k</code> move up</li> <li><code>l</code> move right (often used to move down a path or tree, e.g. a directory path)</li> </ul>"},{"location":"reference/vim-style/moving-around/#moving-with-numbers","title":"Moving with numbers","text":"<p><code>:</code> followed by a number then one of <code>h</code> <code>j</code> <code>k</code> <code>l</code> keys will move the cursor that number in the director of the key.</p> <p><code>3j</code> will move 3 lines down the buffer (or to the end of the fuffer if there are fewer lines remaining)</p> <p>Using Relative line numbers showws how far each line is from the current line.  The practicalli/neovim-config sets <code>:relativenames true</code> in <code>fnl/config/init.fnl</code>.</p> <p><code>42l</code> moves 42 charaters to the right</p> <p>moving by motions avoids the need to count characters</p>"},{"location":"reference/vim-style/moving-around/#moving-around-the-buffer","title":"Moving around the buffer","text":"<p><code>g g</code> to jump to the top of the current buffer </p> <p><code>G</code> to jump to the bottom of the buffer</p> <p><code>z z</code> moves the current line and cursor to the middle of the window</p> <p><code>z t</code> moves the current line and cursor to the top of the window</p> <p><code>z t</code> moves the current line and cursor to the bottom of the window (or as far as the buffer will move in the window)</p>"},{"location":"reference/vim-style/narrowing/","title":"Narrowing","text":"<p>Narrowing to a region enables vim commands to be applied to a specific part of the current buffer, rather than the whole buffer.</p> <p>Common examples include - replacing local variables within a specific function (avoiding affecting other function definitions)</p>"},{"location":"reference/vim-style/narrowing/#nrrwrgn-plugin","title":"NrrwRgn plugin","text":"<p>[NrrwRgn plugin] is inspired by the Narrowing feature of Emacs  and means to focus on a selected region while making the rest inaccessible. </p> <p><code>SPC n r</code> opens a select region in a new split window.  The original buffer is protected from changes. </p> <p><code>:w</code> to write changes in the narrowed window to the original buffer</p>"},{"location":"reference/vim-style/narrowing/#commands","title":"Commands","text":"<p><code>:NR</code>  - Open the selected region in a new narrowed window <code>:NW</code>  - Open the current visual window in a new narrowed window <code>:WR</code>  - (In the narrowed window) write the changes back to the original buffer. <code>:NRV</code> - Open the narrowed window for the region that was last visually selected. <code>:NUD</code> - (In a unified diff) open the selected diff in 2 Narrowed windows <code>:NRP</code> - Mark a region for a Multi narrowed window <code>:NRM</code> - Create a new Multi narrowed window (after :NRP) - experimental! <code>:NRS</code> - Enable Syncing the buffer content back (default on) <code>:NRN</code> - Disable Syncing the buffer content back <code>:NRL</code> - Reselect the last selected region and open it again in a narrowed window</p> <p>Appending <code>!</code> to most commands opens the narrowed part in the current window instead of a new window. </p> <p><code>:WR!</code> closes the narrowed window in addition to writing to the original buffer.</p>"},{"location":"reference/vim-style/narrowing/#documentation","title":"Documentation","text":"<p><code>:help NarrowRegion</code> to view the documetation on the NrrwRgn plug use</p>"},{"location":"reference/vim-style/narrowing/#attention","title":"Attention","text":"<p><code>:NRM</code> is described as experimental by the project readme.</p>"},{"location":"reference/vim-style/speaking-vim/","title":"Learning to speak Vim","text":"<p>Neovim is easier to learn and gain much more benefit from if you learn to speak commands as sentences.</p> <p>First learn some verbs:</p> <ul> <li><code>c</code> change </li> <li><code>d</code> delete</li> <li><code>g</code> go, </li> <li><code>v</code> visual select </li> <li><code>y</code> yank (copy)</li> </ul> <p>Then use those verbs with some modifiers</p> <ul> <li><code>'</code> mark </li> <li><code>{ }</code> beginning/end of paragraph</li> <li><code>0</code> start of line</li> <li><code>^</code> first non white-space character of line</li> <li><code>$</code> end of line</li> <li><code>a</code> around</li> <li><code>f</code> find (includes character)</li> <li><code>i</code> inside a range (e.g. word, paren,)</li> <li><code>s</code> surround </li> <li><code>t</code> till (move just before specified character)</li> </ul> <p>Then learn the text objects you can apply verbs and modifiers too</p> <ul> <li><code>b</code> block/parentheses</li> <li><code>p</code> paragraph, </li> <li><code>s</code> sentence  </li> <li><code>t</code> tag e.g. html/xml </li> <li><code>w</code> word</li> </ul>"},{"location":"reference/vim-style/speaking-vim/#examples-of-speaking-vim","title":"Examples of speaking Vim","text":"<p>Practice speaking evil with these examples</p> Keybinding Description <code>c i s</code> change inside current sentence (change the whole sentence) <code>c i \"</code> change inside double quotes <code>c f )</code> change from cursor to next <code>)</code> character <code>c s ' \"</code> change by the surrounding single quotes with double quotes <code>c t X</code> change till the character <code>X</code> (not including <code>X</code>) <code>c /foo</code> change until the first search result of \u2018foo\u2019 <code>d d</code> delete current line <code>D</code> delete current line from cursor onward <code>d i w</code> delete inside the current word (delete word) <code>v t SPC</code> visual select till the next <code>Space</code> character <code>v s ]</code> visually select and surround with <code>[]</code> without spaces <code>v s [</code> as above with <code>[ ]</code> with spaces between parens and content <code>g v</code> go to last visual selection (select last visual selection) <code>v a p</code> visually select around current paragraph <code>v i w S \"</code> visually select, insert around current word, and surround with quotes <code>y y</code> yank (copy) current line <code>y w</code> yank (copy) current word <code>y @ a</code> yank (copy) to mark <code>a</code> (<code>m a</code> creates a mark called <code>a</code>)"},{"location":"reference/vim-style/vim-quick-reference/","title":"Neovim Quick Reference","text":"<p>A reference of the most common keybindings available in Vim Normal mode. Spacemacs DOCUMENTATION key bindings section contains full details</p> <p><code>.</code> repeats the last keybinding sequence used in Vim Normal mode or a change made within a complete Vim Insert session.</p>"},{"location":"reference/vim-style/vim-quick-reference/#moving-around","title":"Moving around","text":"<p>In Normal mode you can keep your fingers resting on the main row of your keyboard to move around.</p> Key action <code>j</code> move cursor down one line <code>k</code> move cursor up one line <code>l</code> move cursor right one character <code>h</code> move cursor left one character <p>In menus such as helm you can move around using <code>Ctrl</code> and these keybindings.  So <code>C-j</code> will move the cursor down one item in a menu.</p>"},{"location":"reference/vim-style/vim-quick-reference/#navigating-the-current-line","title":"Navigating the current line","text":"Key Action <code>f</code> to next character (you specify) <code>t</code> to just before the next character <code>;</code> repeat <code>f</code> or <code>t</code> search <code>w</code> start of next word <code>W</code> start of next word, white space delimited <code>e</code> end of current word <code>b</code> start of previous word <code>W</code> end of next word, white space delimited <code>*</code> to next matching symbol name <code>$</code> end of current line <code>0</code> start of current line <code>^</code> start of non-whitespace <code>%</code> jump to matching parens or next closed paren"},{"location":"reference/vim-style/vim-quick-reference/#navigating-the-current-buffer","title":"Navigating the current buffer","text":"Key action <code>gg</code> start of buffer <code>G</code> end of buffer <code>H</code> move cursor to head of buffer <code>M</code> move cursor to middle of buffer <code>L</code> move cursor to bottom line of buffer <code>C-u</code> jump up half a page <code>C-d</code> jump down half a page <code>}</code> move cursor forward by paragraph or block <code>{</code> move cursor backward by paragraph or block <code>ma</code> mark a line in a file with marker \"a\" <code>`a</code> after moving around, go back to the exact position of marker \"a\" <code>'a</code> after moving around, go back to line of marker \"a\" <code>:marks</code> view all the marks <code>''</code> go to the last place you were <code>[{</code> jump back to the \"{\" at the beginning of the current code block <code>C-o</code> jump back to previous cursor location (<code>evil-jump-backwards</code>) <code>C-i</code> Go to newer position in jump list (opposite of <code>C-o</code>) <code>: 4</code> go to line 4"},{"location":"reference/vim-style/vim-quick-reference/#text-editing","title":"Text Editing","text":"<p>The following commands put you into the Evil Insert state</p> Key Action <code>i</code> insert state at cursor <code>I</code> insert state at start of line <code>a</code> append - insert state after cursor <code>A</code> append - insert state at end of line <code>o</code> new line after cursor <code>O</code> new line before cursor"},{"location":"reference/vim-style/vim-quick-reference/#return-to-normal-state","title":"Return to Normal state","text":"<p>Regularly switch back to normal state should become common practice.  As soon as you finish typing some new text, it should become second nature to go back to normal state.</p> <p><code>ESC</code> or press <code>fd</code> keys in extremely quick succession.</p> <p><code>fd</code> shortcut for Esc</p> <p>Using <code>f d</code> together is low risk as if you dont get it right it will either add the characters or try find the next <code>d</code> character (as <code>f</code> moves to the next character). Keep trying this key combination as once in normal state you can use <code>u</code> to undo any <code>f d</code> characters inserted.</p>"},{"location":"reference/vim-style/vim-quick-reference/#copy-cut-paste-undo-redo","title":"Copy, cut, paste, undo, redo","text":"<p><code>v</code> in Vim normal mode changes to Visual select mode.  Use the navigation keys or any other movement keys to select text to copy or cut.</p> Key Action <code>y</code> copy (yank) selection and add to kill ring <code>x</code> delete character at point and add to kill ring <code>X</code> delete character before point and add to kill ring <code>p</code> paste (put) <code>u</code> undo <code>Ctrl-r</code> redo <p>Undo tips</p> <p>Undo will revert the last action in normal mode or all the changes you made in insert state</p>"},{"location":"reference/vim-style/vim-quick-reference/#replace-and-changing-text","title":"Replace and changing text","text":"Key Action <code>r</code> replace the character under cursor <code>R</code> replace multiple characters until <code>ESC</code> <code>cw</code> change word from cursor to end <code>4 c w</code> change 4 words <code>v (select) c</code> change region <code>v (select) d</code> delete region <code>v i w c</code> change current word <code>v i d</code> delete current word <code>d w</code> delete from cursor to end of word <code>C</code> change from cursor to end of line <code>D</code> , <code>d $</code> delete from cursor to end of line"},{"location":"reference/vim-style/vim-quick-reference/#delete-commands","title":"Delete commands","text":"Key Action <code>de</code> delete to end of word, not including space <code>dw</code> delete to end of word, including space <code>d$</code> delete to end of line <code>dd</code> delete the current line <code>4 d w</code> delete 4 words <code>4 d $</code> delete 4 lines to end <code>dt</code> delete to a character (not including character) <code>dab</code> delete a whole block / expression <code>dib</code> delete contents of a block / expression <code>cab</code> change all the block / expression <code>cib</code> change inner block contents / expression <code>yab</code> yank all block / expression <code>yib</code> yank inner block contents / expression"},{"location":"reference/vim-style/vim-quick-reference/#repeat-commands","title":"Repeat commands","text":"Key Action <code>.</code> repeat last command again <code>&lt;number&gt; &lt;cmd&gt;</code> repeat command a number of times <p>The <code>.</code> keybinding will repeat the last command in normal mode or the last text edit in insert mode.</p> <p>Type a number before a command and that command will run that number of times.</p> <p>Inserting a comment border</p> <p>Use the number repeat to create a border of 42 <code>;</code> characters.</p> <p>Type <code>42</code> to repeat the command 42 times</p> <p>Press <code>i</code> for insert mode</p> <p>Press <code>;</code> as the character to repeat insert</p> <p>Press <code>ESC</code> or <code>fd</code> to leave insert mode and insert all 42 <code>;</code> characters</p>"},{"location":"reference/vim-style/vim-quick-reference/#transposing-swap","title":"Transposing / swap","text":"Key Description <code>x p</code> transpose the current character with the next character"},{"location":"reference/vim-style/vim-quick-reference/#comments-works-for-all-major-modes","title":"Comments - works for all major modes","text":"<p><code>g c c</code> to comment out the current line</p> <p><code>g c</code> to comment out the currently selected region</p> <p>To comment multiple lines you can use the repeat command style, especially useful if you are using relative line numbers.</p> <p><code>g c 3 j</code> will comment the current line and the following two lines below.  Comment in reverse using <code>g c 3 k</code>.</p> <p>In Visual state, <code>v</code>, select the lines you wish to comment and use <code>g c</code> to comment all the marked lines.  Partially marked lines are not commented.</p>"},{"location":"reference/vim-style/vim-quick-reference/#managing-files","title":"Managing Files","text":"<p>Files in practicalli/neovim-config can be managed with Telescope plugin, although the neovim commands can also be used</p> <p><code>SPC p t</code> toggles a visual file explorer on as a leftmost window, providing a further way to navigate files and directories.</p> Key Description <code>SPC f f</code> find existing file (from current local root of neovim) <code>SPC f /</code> copy file - save current buffer with a new file name <code>SPC f b</code> browse files - <code>Esc</code> to run commands <code>SPC f b Esc r</code> change file name of current buffer <p>Telescope file browser opens in Insert mode to allow typing filenames, to narrow the results in the Telescope popup.</p>"},{"location":"reference/vim-style/vim-quick-reference/#telescope-browser-commands","title":"Telescope browser commands","text":"<p><code>SPC f b</code> opens telescope browser which allows commands to be run over the current file or directory.</p> <p><code>Esc</code> swiches the Telescope popup to normal mode, allowing commands to be used</p> <ul> <li><code>c</code> create file / directory  (any missing parts of a path are created)</li> <li><code>r</code> rename a file / directory</li> <li><code>R</code> replace</li> </ul> <p><code>TAB</code> selects files and directories, allowing for commands (i.e. rename) to be done in batch mode (acting on all selected files / directories)</p>"},{"location":"reference/vim-style/vim-quick-reference/#working-with-buffers","title":"Working with Buffers","text":"<p>To work with files in Neovim they are loaded into a Buffer.</p> <p>Buffers are displayed in a window and you can change the window to show any of the current buffers.</p> <p><code>SPC b</code> displays the buffer menu and the most common commands include:</p> Key Command Description <code>SPC b b</code> :Telescope buffers List current buffers <code>SPC b d</code> :bdelete Kill current buffer <code>SPC b n</code> :bnext Switch to next buffer <code>SPC b p</code> :bprevious Switch to previous buffer <code>SPC b a</code> :ball Switch to previous buffer"},{"location":"reference/vim-style/vim-quick-reference/#quit-or-restart-emacs","title":"Quit or Restart Emacs","text":"<p>I recommend using the Spacemacs menu from normal mode to quit / restart Spacemacs.</p> Key Action <code>SPC q a</code> Quit Neovim (blocked if unsaved change in buffers) <code>SPC q q</code> Quit buffer (blocked if unsaved change in buffers) <code>SPS q Q</code> Force quit of Neovim"},{"location":"reference/vim-style/vim-quick-reference/#external-commands","title":"External commands","text":"<p>run external commands using <code>:!</code> followed by a command.  For example:</p> <p><code>:!ls</code> - run the <code>ls</code> command</p>"},{"location":"reference/vim-style/vim-tips-for-developers/","title":"Vim editing for Clojure developers","text":"<p>Vim keybindings that drive Vim editing tools that are common for developers</p>"},{"location":"reference/vim-style/vim-tips-for-developers/#comments-and-commenting-code","title":"Comments and Commenting code","text":"<ul> <li><code>g c c</code>  comment line</li> <li><code>g c c</code>  comment line</li> <li><code>v (select) g c</code>  comment region</li> <li><code>g c 9 j</code>  comment 9 lines from current, downwards</li> </ul>"},{"location":"reference/vim-style/vim-tips-for-developers/#simulated-structural-editing-with-surround","title":"Simulated structural editing with surround","text":"Keybinding Description <code>v s ]</code> surround with [characters] without spaces <code>v s [</code> surround with [ characters ] without spaces <code>c s ( [</code> change surrounding from ( to [ <code>c i (</code> change in ( <code>c a (</code> change \u201caround\u201d ( <code>%</code> jump forwards to next paren, further <code>%</code> toggles between open and close parens. <code>x p</code> transpose characters (cut current, paste after)"},{"location":"reference/vim-style/vim-tips-for-developers/#moving-around-quickly","title":"Moving around quickly","text":"<p><code>f</code> to jump forward to a given character on the current line. <code>F</code> to jump backwards.</p> <p><code>zt</code>, <code>zz</code>, and <code>zb</code> to pull the current line to the top/middle/bottom of the screen.</p> <p><code>[number] G</code> jump to line number or <code>:22</code> to jump to line 22</p> <p><code>:7j</code> to jump 7 lines down</p> <p><code>gf</code> jump to file name under the cursor - try this in the summary.md file</p>"},{"location":"reference/vim-style/vim-tips-for-developers/#selection-find-and-replace","title":"Selection, find and replace","text":"<p><code>viw</code> to visual-select in (within) the current word </p>"},{"location":"reference/vim-style/vim-tips-for-developers/#source-code-and-configuration-files","title":"Source code and configuration files","text":"<p><code>g D</code>open definition in another window</p> <p><code>=</code> (code-aware indenting) operator. Nice with the <code>ap</code> (a paragraph) text object.</p> <p><code>C-]</code> Jump to definition of keyword under the cursor</p>"},{"location":"reference/vim-style/vim-tips-for-developers/#code-folding","title":"code folding","text":"<p><code>zc</code> and <code>zo</code> are useful to close and open folds, which can be a nice way of focusing on certain pieces of code.</p>"},{"location":"reference/vim-style/vim-tips-for-developers/#transposing-characters-and-sections","title":"Transposing characters and sections","text":"<p><code>x p</code>  simple transpose of the current and next character</p> <p><code>M-t</code> transpose words before and after cursor position</p> <p><code>{</code>, <code>}</code> motions jump to next and previous empty lines.  This motion makes it simple to rearrange paragraphs</p> <p><code>{ d }</code> will kill the paragraph (or multiple paragraphs)</p> <p><code>{</code> will jump to the start of the previous paragraph</p> <p><code>p</code> pastes the killed paragraph before the current paragraph</p> <p><code>&gt;</code> and <code>&lt;</code> (indent and dedent) operators, useful with the aforementioned <code>}</code>/<code>{</code> motions.</p> <p>/ ## multi-replace with iedit and narrowing /</p>"},{"location":"reference/vim-style/visual-select/","title":"Visual Select","text":"<p>Select characters, words, lines and regions with visual select.  The background changes color to visually indicate which text is selected</p> <p><code>v</code> enters visual select mode and can be with objects such as word <code>w</code> and locations such as end of line <code>$</code>.</p> <p><code>o</code> to expand from left side of selection and <code>O</code> to expand from the right side of a selection, using the <code>hjkl</code> navigation keys</p>"},{"location":"reference/vim-style/visual-select/#visual-line-selection","title":"Visual Line selection","text":"<p><code>V</code> to select by lines, using <code>j</code> and <code>k</code>.</p>"},{"location":"reference/vim-style/z-menu/","title":"Evil Z menu","text":"<p><code>z</code> in normal mode opens a menu of convenient utilities</p>"},{"location":"reference/vim-style/z-menu/#folding-code-comments-and-other-content","title":"Folding code, comments and other content","text":"<p>Code folding is very useful for hiding different levels of detail, for example you could hide everything but the function names in a namespace, showing just the API for that namespace.</p> <p>Comments and documentation can be folded to help you focus on a specific part of the content.</p> Key Description <code>z a</code> toggle fold of code, comment, section, etc. <code>z A</code> toggle all folds <code>z c</code> close fold <code>z f</code> create fold <code>z M</code> close all folds <code>z o</code> open fold <code>z O</code> open fold recursive (capital o) <code>z r</code> fewer folds <code>z R</code> open all folds <code>z x</code> update folds <p>See narrowing for a focused approach to editing.</p>"},{"location":"reference/vim-style/z-menu/#scrolling","title":"Scrolling","text":"<p>Jump the current line to the center, top or bottom of the buffer.</p> Key Description <code>z b</code> scroll the current line to bottom of buffer <code>z t</code> scroll the current line to top of buffer <code>z z</code> scroll the current line to center of buffer"},{"location":"reference/vim-style/z-menu/#spelling","title":"Spelling","text":"<p><code>z =</code> with the cursor on a word shows a list of possible spelling and similar words.</p> <p>Select a word using its number in tye list to repace the word under the cursor, or <code>q</code> to quit the spelling list.</p> Key Description <code>z =</code> spelling suggestions <code>z g</code> add word to spelling list <code>z w</code> mark word as misspelled"},{"location":"repl-driven-development/","title":"REPL Driven Development with Clojure","text":"<p>Conjure provides the REPL driven development workflow for Clojure (and many other fun languages) and includes a built-in tutorial.</p> <ul> <li>Vim style Editing</li> <li>Starting a REPL &amp; Evaluating code - using Conjure</li> <li>Structural Editing - parinfer or paredit</li> <li>Refactor tools - Language Server Protocol features</li> <li>Unit Testing - run REPL or external test runners</li> <li>Inspecting data, e.g.  Portal</li> </ul> <p>Practicalli Clojure CLI Config</p> <p> Practicalli Clojure CLI config contains aliases used extensively through the Clojure sections of this book</p> Practicalli Neovim config replaces some key bindings <p>practicalli/neovim-config-redux replaces several key bindings to make them consistent with other Clojure editors</p>"},{"location":"repl-driven-development/#references","title":"References","text":"<ul> <li>Which Clojure CLI execution option - M T X P - should be used</li> <li>Make task to simplify Clojure development</li> </ul>"},{"location":"repl-driven-development/conjure/","title":"Conjure","text":"<p>Conjure is the Clojure REPL client for Neovim.  Code in source code buffers can be evaluated and show the results in-line, providing instant feedback on the behaviour of the code as it develops.</p> <p>Conjure School interative tutorial</p> <p><code>:ConjureSchool</code> runs an interactive tutorial in Neovim, walking through the essential Conjure commands and key bindings. Use the commands provided to move through the guide or j / k to scroll through the guide content.</p>"},{"location":"repl-driven-development/conjure/#start-repl","title":"Start REPL","text":"<p>Start a REPL on the command line in the root of a Clojure project.  The REPL should also start an nREPL server for Conjure to connect too.</p> <p>Conjure will detect an nREPL server (via <code>.nrepl-port</code> file) when a Clojure file is opended (.clj .edn .cljs .cljc) and connect to the REPL process via that nREPL server.</p> Practicalli Clojure CLI ConfigManual Alias definition <p> Practicalli Clojure CLI config contains aliases to  start a REPL process that also start an nREPL server.</p> <p>Use <code>repl</code> make task for projects created by  Practicalli Project templates</p> <pre><code>make repl\n</code></pre> <p>Or use the Clojure CLI command with the <code>:repl/rebel</code> alias directly</p> <pre><code>clojure -M:repl/rebel\n</code></pre> Simplify the command line <p>Add a <code>Makefile</code> to define common tasks to simplify and add consistency to working with Clojure across projects  or shell script to simplify the commands used to call <code>clojure</code> to run common tasks</p> <pre><code>repl:  ## Run Clojure REPL with rich terminal UI (Rebel Readline)\n    $(info --------- Run Rebel REPL ---------)\n    clojure -M:env/dev:env/test:repl/rebel\n\n\nrepl-reloaded:  ## Run Clojure REPL with hotload, reload and rich terminal UI (Rebel Readline)\n    $(info --------- Run Rebel REPL ---------)\n    clojure -M:env/dev:env/test:lib/reloaded:repl/rebel\n</code></pre> <p>A <code>Makefile</code> can also include supporting commands, such as lint and format tools.</p> <pre><code># Run MegaLinter with custom configuration\nlint:\n    $(info --------- MegaLinter Runner ---------)\n    mega-linter-runner --flavor java --env 'MEGALINTER_CONFIG=.github/linters/mega-linter.yml'\n</code></pre> <p>practicalli/dotfiles/Makefile contains tasks for Clojure development, including running a REPL, preparing dependencies, building an uberjar, lint &amp; format Clojure and configuration files.</p> <p>Docker related tasks to build, run and compose common images and containers are also included.</p> <p>Add aliases to the user configuration for Clojure, e.g. <code>XDG_HOME_CONFIG/clojure/deps.edn</code> or <code>HOME/.clojure/deps.edn</code> <pre><code>  ;; Interactive client REPL with nREPL server for Clojure Editor support\n  :repl/basic\n  {:extra-deps {nrepl/nrepl       {:mvn/version \"1.0.0\"}\n                cider/cider-nrepl {:mvn/version \"0.40.0\"}}\n   :main-opts  [\"--main\" \"nrepl.cmdline\"\n                \"--middleware\" \"[cider.nrepl/cider-middleware]\"\n                \"--interactive\"]}\n\n  ;; Headless REPL with nREPL server for Clojure Editor support\n  :repl/headless\n  {:extra-deps {nrepl/nrepl       {:mvn/version \"1.0.0\"}\n                cider/cider-nrepl {:mvn/version \"0.40.0\"}}\n   :main-opts  [\"--main\" \"nrepl.cmdline\"\n                \"--middleware\" \"[cider.nrepl/cider-middleware]\"]}\n</code></pre></p> <p><code>clojure -M:repl/basic</code> starts a REPL with nREPL with a minimal REPL UI</p> <p><code>clojure -M:repl/headless</code> starts a REPL with nREPL server but without a REPL prompt (to prevent accidental interaction via the command line)</p> <p>Practicalli Clojure CLI Config aliases</p> <p> Practicalli Clojure CLI config defines aliases for a wide range of community tools and libraries that extend the features of Clojure CLI</p>"},{"location":"repl-driven-development/conjure/#evaluation","title":"Evaluation","text":"<p>Clojure REPL workflow encourages code expressions to be evaluated as the are written, providing instant feedback to ensure expected results are returned (or learn the kind of results a function returns).</p> <p>Results of evaluating an expression are shown in-line.  Open the REPL log to see larger results and a complete REPL history for the current session.</p> <p><code>,eb</code> - evaluate current buffer - used after first starting the REPL to load in a whole namespace and any required namespaces. Use to ensure all changes have been evaluated in the REPL (except those within a <code>(comment )</code> form or otherwise commented)</p> <p><code>,er</code> - evaluate top-level expression (root), ignoring a surrounding <code>(comment )</code> form to support the rich comments approach</p> <p><code>,ee</code> - evaluate expression (from start of current form) - especially useful for nested forms</p> <p><code>,ei</code> - interrupt evaluation (stop long running evaluations) - stop a long running evaluation</p> <p><code>,ew</code> - evaluate word (symbol) - inspect value of form - i.e. for def names</p> <p><code>,e!</code> - replace form with its result - helps understand a more complex function by replacing code with a specific value</p> <p><code>,emf</code> - evaluate marked form - mark forms regularly re-evaluted with <code>mf</code> (or any character with <code>m</code>) to avoid jumping to that form each time . A capital letter to mark form in a different namespace and evaluate  from the current buffer. </p> <p><code>\"cp</code> - paste contents of the register into buffer. The result of every evaluation is stored in a Neovim register as well as the log.</p>"},{"location":"repl-driven-development/conjure/#repl-log","title":"REPL log","text":"<p>The Conjure REPL log shows the results of every evaluation for the current session.</p> <p><code>,lt</code> opens log in a new tab page (tab), <code>,ls</code> in horizontal split, <code>,lv</code> in vertical tab</p> <p><code>,lq</code> - close log window / tab page</p> <p><code>,lr</code> - soft REPL reset, leave window open</p> <p><code>,lR</code> - hard REPL reset, close window &amp; delete buffer</p> <p>Inline evaluation over HUD log popup</p> <p> Practicalli Neovim configurations hide the HUD log popup that is otherwise shown when Conjure connects to the REPL process, i.e. <code>vim.g[\"conjure#log#hud#enabled\"] = false</code></p> <p>In-line evaluation results are the main feedback approach used by Practicalli when evaluating code.</p> <p>Practicalli recommends using the REPL log when larger results are returned</p> <p>Portal data inspector can be sent evaluation history and provides rich visualisation and navigation tools to explore that history in detail.</p>"},{"location":"repl-driven-development/conjure/#rich-comments","title":"Rich comments","text":"<p>Rich comments are a useful way to contain experimental expressions, or expresisons only evaluated directly by a person developing the code (e.g. starting / stoping services, testing api calls, etc.)</p> <p>Expressions in rich comments are not included when evaluating the buffer or when expressions are evaluated via a namespace require.</p> <p><code>,er</code> to evaluate the top level form within the rich comment, without evaluating the comment expression itself.</p> Start REPL from Neovim <p>Practicalli Configurations require the  vim-jack-in plugin to be added before this approach will work.</p> <p>Start Neovim with a Clojure file, e.g. <code>nvim src/practialli/playground.clj</code> or run <code>nvim</code> and open a Clojure file, e.g. <code>*.clj</code>, <code>*.cljc</code>, <code>*.cljs</code> or <code>.edn</code>.</p> <ul> <li><code>:Clj</code> command to start a REPL using Clojure CLI Tools</li> <li><code>:Lein</code> command to start a REPL using Leiningen</li> </ul> <p>Neovim switches to a terminal state, use <code>C-\\ C-n</code> to leave the terminal state.  Use <code>:N</code> or <code>:previous</code> to switch back to the source code buffer</p> <p><code>, c f</code> to connect to the REPL from Conjure, or simply open a Clojure file.  Automated connection will be added in a future version on Conjure.</p> <p>The <code>vim-jack-in</code> plugin enables Neovim to call out to Clojure tools or Leiningen to start a REPL and connect to it once its started.</p> <p>A full screen REPL log is displayed.  <code>, l q</code> to close the log window and return to the Clojure file. <code>, l v</code> to create a vertical split between code and REPL log, <code>, l s</code> for a horizontal split.</p>"},{"location":"repl-driven-development/refactor-tools/","title":"Refactor tools","text":"<p>Neovim and common plugins provide many text oriented tools useful for refactoring code.</p> <p>Clojure LSP server and Neovim LSP client support use static analysis of the project source code to allow provide common code refactor tools.</p>"},{"location":"repl-driven-development/refactor-tools/#language-server-protocol-lsp","title":"Language Server Protocol (LSP)","text":"<p>Using clojure-lsp server and Neovim Treesitter as an LSP client, code is statically analysed to provide auto-completion data, advanced editing actions such as refactor, live formatting, etc.</p> <p>Function help</p> <p><code>SPC l h</code> or K displays help for the function under the cursor</p> <p>Repeat the key binding to move the cursor to the documentation popup window and use j k to scroll the documentation</p>"},{"location":"repl-driven-development/refactor-tools/#key-maps","title":"Key maps","text":"Practicalli AstroNvim ConfigPracticalli Neovim Config Redux <ul> <li><code>&lt;leader&gt;la</code> code actions (popup with available actions)</li> <li><code>&lt;leader&gt;ld</code> hover diagnostics</li> <li><code>&lt;leader&gt;lD</code> search diagnostics</li> <li><code>&lt;leader&gt;lf</code> format buffer</li> <li><code>&lt;leader&gt;lG</code> search workspace symbols</li> <li><code>&lt;leader&gt;lh</code> function signature help</li> <li><code>&lt;leader&gt;li</code> information about the LSP client and running LSP servers</li> <li><code>&lt;leader&gt;lI</code> null-ls information (format &amp; lint tools)</li> <li><code>&lt;leader&gt;ll</code> code lens refresh</li> <li><code>&lt;leader&gt;lL</code> code lens run</li> <li><code>&lt;leader&gt;lr</code> rename current symbol (namespace rename not supported it seems)</li> <li><code>&lt;leader&gt;lR</code> search references</li> <li><code>&lt;leader&gt;ls</code> search symbols</li> <li><code>&lt;leader&gt;lS</code> symbols outline</li> </ul> <ul> <li><code>gd</code> Go to definition</li> <li><code>K</code> Show documentations</li> <li><code>&lt;leader&gt;ld</code> Function declarations</li> <li><code>&lt;leader&gt;lt</code> Type Definitions</li> <li><code>&lt;leader&gt;lh</code> Signature Help</li> <li><code>&lt;leader&gt;ln</code> Rename</li> <li><code>&lt;leader&gt;le</code> Show line diagnostics</li> <li><code>&lt;leader&gt;lq</code> Show all diagnostics information</li> <li><code>&lt;leader&gt;lf</code> Auto format</li> <li><code>&lt;leader&gt;lj</code> Go to next diagnostic</li> <li><code>&lt;leader&gt;lk</code> Go to previous diagnostic</li> <li><code>&lt;leader&gt;la</code> Open code actions menu (Using telescope plugin interface)</li> <li><code>&lt;leader&gt;la</code> Open code actions menu for the selected text in VISUAL mode (Using telescope plugin interface)</li> <li><code>&lt;leader&gt;lw</code> Open workspace diagnostics list (Using telescope plugin interface)</li> <li><code>&lt;leader&gt;lr</code> Show all references list for item under the cursor (Using telescope plugin interface)</li> <li><code>&lt;leader&gt;lr</code> Show all implementations list for item under the cursor (Using telescope plugin interface)</li> </ul>"},{"location":"repl-driven-development/refactor-tools/#troubleshooting","title":"Troubleshooting","text":"<p>Space l i shows the LSP server information for the current filetype, e.g. Clojure</p> <p> </p>"},{"location":"repl-driven-development/refactor-tools/#limitations-to-investigate","title":"Limitations to investigate","text":"<ul> <li>Neovim client does not seem to support namespace rename (AstroNvim)</li> </ul>"},{"location":"repl-driven-development/structural-editing/","title":"Structural Editing","text":"<p>Structural editing seeks to ensure that parenthesis (parens) and other pairs of characters remain balanced, i.e. an open paren is not removed without removing the closing paren.</p> <ul> <li>parinfer uses an indent approach, aligning code manages parens locations</li> <li>paredit uses a structural approach</li> </ul> AstroNvim Community Clojure Pack includes parinfer <p>nvim-parinfer plugin is included in the AstroNvim Community Clojure pack</p> <pre><code>  { import = \"astrocommunity.pack.clojure\" },\n</code></pre>"},{"location":"repl-driven-development/structural-editing/#parinfer","title":"Parinfer","text":"<p>Parinfer works very well with vim-style modal editing.</p> <p>The author of the code focuses on aligning code and parinfer takes care of balancing the parens.</p> <p>To include new lines of code within an expression, create a new line <code>o</code> and indent.</p> <p>Parinfer will move the preceeding closing paren(s) to the new line, enclosing the new code in the overall expression.</p> <p>Parinfer website </p>"},{"location":"repl-driven-development/testing/","title":"Unit tests and test runners","text":"<p>Run unit tests from within Neovim, showing a summary of test results or a full test report (especially if there are failures)</p> <p>Or run and external test runner via a terminal session, optionally using watch mode to re-run tests on every saved change.</p> Practicalli sets Kaocha test runner as default <p> practicalli/neovim-config-redux sets Kaocha as the default test runner</p> <p>Kaocha test runner set in  Astrocommunity Clojure language pack</p> Astrocommunity Clojure language pack<pre><code>{\n  \"Olical/conjure\",\n  -- load plugin on filetypes\n  ft = { \"clojure\" },\n  init = function()\n    vim.g[\"conjure#log#hud#width\"] = 1\n    vim.g[\"conjure#log#hud#enabled\"] = false\n    vim.g[\"conjure#log#hud#anchor\"] = \"SE\"\n    vim.g[\"conjure#log#botright\"] = true\n    vim.g[\"conjure#extract#context_header_lines\"] = 100\n    vim.g[\"conjure#eval#comment_prefix\"] = \";; \"\n    vim.g[\"conjure#client#clojure#nrepl#connection#auto_repl#enabled\"] = false\n    vim.g[\"conjure#client#clojure#nrepl#connection#auto_repl#hidden\"] = true\n    vim.g[\"conjure#client#clojure#nrepl#connection#auto_repl#cmd\"] = nil\n    vim.g[\"conjure#client#clojure#nrepl#eval#auto_require\"] = false\n    vim.g[\"conjure#client#clojure#nrepl#test#runner\"] = \"kaocha\"\n\n    vim.api.nvim_create_autocmd(\"BufNewFile\", {\n      group = vim.api.nvim_create_augroup(\"conjure_log_disable_lsp\", { clear = true }),\n      pattern = { \"conjure-log-*\" },\n      callback = function() vim.diagnostic.disable(0) end,\n      desc = \"Conjure Log disable LSP diagnostics\",\n    })\n</code></pre>"},{"location":"repl-driven-development/testing/#include-test-path","title":"Include test path","text":"<p>Ensure the <code>test</code> directory is included in the classpath when starting a REPL.  Use a project or user level alias which defines an <code>:extra-paths</code> key with the <code>[\"test\"]</code> path</p> <pre><code>clojure -M:test/env:repl/reloaded\n</code></pre>"},{"location":"repl-driven-development/testing/#conjure-test-runners","title":"Conjure Test runners","text":"<p><code>, t n</code> to run the tests for the current namespace</p> <p><code>, t a</code> to run all tests in the project</p> <p></p>"},{"location":"repl-driven-development/testing/#external-test-runner","title":"External test runner","text":"<p>Open a terminal in Neovim or a separate terminal session to run start a test runner in watch mode.  Tests run automatically when the code changes are saved</p> Practicalli Clojure CLI Config <p> Practicalli Clojure CLI config contains aliases for test runner tools</p> <ul> <li> <p><code>:test/run</code> uses Kaocha to run all tests, stopping on first failing test.  Add <code>:fail-fast? false</code> argument to run all tests regardless of failure</p> </li> <li> <p><code>:test/watch</code> as above and puts Kaocha in watch mode, triggering a test run each time a file is saved</p> </li> </ul> <p>Projects created with Practicalli Project Templates include a <code>test</code> and <code>test-watch</code> task to run Kaocha test runner</p> <p>Run all tests, stoping on first failing test</p> <pre><code>make test\n</code></pre> <p>Watch for changes and run all tests, stoping on first failing test</p> <pre><code>make test-watch\n</code></pre> <p>The make tasks call Clojure CLI with the appropriate alias, e.g. <code>clojure -X:test/run</code> and <code>clojure -X:test/watch</code></p> <p></p>"},{"location":"repl-driven-development/testing/#test-selectors","title":"Test Selectors","text":"<p>Use Test selectors to run a sub-set of tests based on selector meta data added to <code>deftest</code> code</p> <pre><code>(deftest ^:infrastructure function-name-test\n  (testing \"\"\n    (is ,,,))\n\n(deftest ^:persistence function-name-test\n  (testing \"\"\n    (is ,,,))\n</code></pre> Kaocha test runnerCognitect Labs Test Runner <p>Kaocha test runner can focus or skip on a sub-set of unit tests using test id, metadata, namespaces or a specific deftest. </p> <ul> <li><code>:focus</code> or <code>:skip</code> a given namespace or specific test var, i.e. <code>deftest</code> </li> <li><code>:focus-meta</code> or <code>:skip-meta</code> test selectors (metadata) on test vars, i.e. <code>^:persistence</code></li> </ul> <p>Specifying test <code>:id</code> in the <code>tests.edn</code> configuration file allows different test suites to be run, e.g. <code>:unit</code> for unit tests, <code>:spec</code> for specification tests </p> <p>Focus and skip works with a single test run or with a continuous watcher.</p> <p>Skip all tests with :persistence metadata</p> <pre><code>clojure -X:test/watch :skip-meta :persistence\n</code></pre> <p>Focus on a specific test namespace</p> <pre><code>clojure -X:test/watch :focus '[\"practicalli.gameboard.api.scoreboard-test\"]\n</code></pre> <p>Focus on a specific unit test (deftest)</p> <pre><code>clojure -X:test/watch :focus '[\"practicalli.gameboard.api.scoreboard-test/total-score-test\"]\n</code></pre> <p>Refine the tests that are watched</p> <p>Start the watcher with  focused or skiped tests by name or meta data (test selectors)</p> <p>Cognitect Labs Test Runner can include or exclude a sub-set of tests, identified by metadata on the var (<code>deftest</code>)</p> <p>Cognitect Labs Test Runner - inclusions &amp; exclusions </p>"},{"location":"termux/","title":"NeoVim on Termux","text":"<p>A smart phone or tablet and an external keyboard can make an excellent ultra-portable development environment, especially when travelling with limited space or restricted weight constraints.</p> <p>Termux can be installed using the F-Droid marketplace, as with installing any other Android app.</p> <p>Do not install Termux App from the Google Play store</p> <p>The Termux App in Google Play store is significantly out of date and will not work properly and probably not at all</p> <p></p>"},{"location":"termux/#keyboard","title":"Keyboard","text":"<p>Atreus from Keyboardio is an excellent travel keyboard and was used to write most of the Practicalli Neovim configuration and Neovim book (especially during delays at airports)</p> <p>Model 100 from Keyboardio is used by Practicalli at the office </p>"},{"location":"termux/#running-termux","title":"Running Termux","text":"<p>Run Termux from the app launcher added as an android app by the F-Droid install.</p> <p>A help menu will show the basic command needed to work with packages.</p> <p>Software keys for Termux specific controls are shown.  Keys can be toggled with the <code>Volume Up + q</code> key combination.</p> <p></p> <p>Termux may not display in fullscreen when Android productivity mode, usually activated on tablets when physical keyboard or mouse is attached.  Disabling productivity mode in the Android settings is recommended.</p>"},{"location":"termux/clojure-development/","title":"Clojure development environment","text":"<p>A comprehensive development environment for Clojure, supporting a REPL workflow and static analysis of code via Clojure Language Server Protocol.</p>"},{"location":"termux/clojure-development/#java-host-platform","title":"Java host platform","text":"<p>Install OpenJDK to host the Clojure REPL process and run packaged Clojure applications.</p> <p>Java 17 Long Term Support version is recommended as it is very stable, receives security updates and has the latest highly tested performance improvements.</p> <pre><code>pkg install openjdk-17\n</code></pre>"},{"location":"termux/clojure-development/#install-clojure","title":"Install Clojure","text":"<p>Clone practicalli/clojure-deps-edn to add a wide range of community tools to the Clojure CLI</p> <pre><code>git clone git@github.com:practicalli/clojure-deps-edn.git ~/.config/clojure\n</code></pre> <p>Use the Linux install with a prefix path pointing to Termux equivalent of <code>/usr/local</code>.  Find the path using <code>echo $PATH</code> and remove <code>bin</code> from the end.  Without the prefix Clojure will not install correctly</p> <pre><code>curl -O https://download.clojure.org/install/linux-install-1.11.1.1149.sh\n\nchmod +x linux-install-1.11.1.1149.sh\n\n./linux-install-1.11.1.1149.sh --prefix /data/data/com.termux/files/usr/\n</code></pre> <p><code>clojure</code> binary is installed in the existing bin, lib and share directories in <code>/data/..../usr/</code>, placing that binary on the system execution path.</p> <p>Test by running a REPL session, for example with Rebel Readline</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>optionally install rlwrap package if using the basic repl terminal UI</p>"},{"location":"termux/clojure-development/#install-clojure-lsp","title":"Install Clojure LSP","text":"<p>Visit clojure-lsp GitHub releases page and download the <code>clojure-lsp</code> file</p> <ul> <li>visit the relases page in firefox and copy the link to the file.</li> <li>use wget and paste the link to the file to download</li> <li>make executable <code>chmod 755 clojure-lsp</code></li> <li>test locally <code>./clojure-lsp --version</code> - should print clojure-lsp version and clj-kondo version</li> <li>copy or move file to path <code>mv clojure-lsp $PATH</code></li> </ul> <p>If the practicalli/clojure-lsp-config repository was cloned, move or link the <code>clojure-lsp</code> directory to <code>~/.config/clojure-lsp</code></p>"},{"location":"termux/custom-shell/","title":"Customise shell","text":"<p>Customising the shell is optional, although gives an enhanced experience.</p> <p>Zsh provides the richest command line experience, providing many advanced features over bash.  Oh My Zsh is a community configuration that provides a simple way to configure Zsh features and also supports powerline10k terminal theme, providing context specific information and a more engaging visual experience.</p> <p>Oh My Zsh community configuration enhances the Zsh experience.  Practicalli normally uses Prezto community configuration, unfortunately this did not work well on Termux.</p>"},{"location":"termux/custom-shell/#install-zsh","title":"Install Zsh","text":"<p>Install the zsh package using the Termux package manager</p> <pre><code>pkg install zsh\n</code></pre> <p>Start zsh, which will show a <code>%</code> character as the prompt</p> <pre><code>zsh\n</code></pre> <p>Set the shell to run zsh by default</p> <pre><code>chsh -s zsh\n</code></pre>"},{"location":"termux/custom-shell/#install-oh-my-zsh","title":"Install Oh My Zsh","text":"<p>Install Oh My Zsh via curl (or wget if preferred) in the <code>.oh-my-zsh/</code> directory</p> <pre><code>sh -c \"$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)\"\n</code></pre>"},{"location":"termux/custom-shell/#install-powerline10k","title":"Install Powerline10k","text":"<p>Powerline10k is a visually appealing prompt with a setup script to visually choose the presentation of the prompt.</p> <pre><code>git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k\n</code></pre> <p>Edit <code>~/.zshrc</code> and set the theme to <code>ZSH_THEME=\"powerlevel10k/powerlevel10k\"</code></p> <pre><code>nano ~/.zshrc\n</code></pre> <p>Save the changes <code>exit</code> termux.</p> <p>Next time zsh is run, powerline10k setup script will run.  If Meslo is not set as the terminal font, the setup script offers to install the font.  Installing the font will restart Termux (without prompting for a restart).</p> <p>The powerline10k setup script provides a wizard to configure each part of the prompt.</p> <p><code>p10k configure</code> command will manually run the powerline10k setup script.</p> Prezto Zsh community configuration <p>NOTE: previous attempts to use Prezto proved to have issues</p> <p>Clone prezto and its sub-modules into <code>XDG_CONFIG_HOME/zsh</code> which is typically <code>~/.config/zsh</code></p> <pre><code>git clone --recursive https://github.com/sorin-ionescu/prezto.git \"${ZDOTDIR:-${XDG_CONFIG_HOME:-$HOME/.config}/zsh}/.zprezto\"\n</code></pre> <p>Set the location of the Zsh configuration home with <code>$ZDOTDIR</code>, relative to the XDG locations</p> <pre><code>export ZDOTDIR=\"${ZDOTDIR:=$XDG_CONFIG_HOME/zsh}\"\n</code></pre> <p>Create a new Zsh configuration by copying/linking the Zsh configuration files provided:</p> <pre><code>setopt EXTENDED_GLOB\nfor rcfile in \"${ZDOTDIR:-$HOME}\"/.zprezto/runcoms/^README.md(.N); do\n  ln -s \"$rcfile\" \"${ZDOTDIR:-$HOME}/.${rcfile:t}\"\ndone\n</code></pre> <p>Practicalli Zsh configuration</p> <p>Clone practicalli/dotfiles and replace the symbolic links in <code>$XDG_CONFIG_HOME/zsh</code> with links to the respective Zsh configuration files in the cloned repository (or copy the files if you prefer)</p> <p>Copy or create a symbolic like for the <code>.p10k configuration or skip this to create your own configuration when next starting</code>zsh<code>.</code></p> <p>Edit <code>$XDG_CONFIG_HOME/.config/zsh/.zshenv</code> and add the following lines to enable zsh to find the prezto configuration</p> <pre><code>export XDG_CONFIG_HOME=\"${XDG_CONFIG_HOME:=$HOME/.config}\"\nexport ZDOTDIR=\"${ZDOTDIR:=$XDG_CONFIG_HOME/zsh}\"\n</code></pre> <p>Create a symbolic link from <code>$HOME/.zshenv</code> to <code>$XDG_CONFIG_HOME/.config/zsh/.zshenv</code> (or to the .zshenv file from practicalli/dotfiles)</p> <pre><code>ln -s $XDG_CONFIG_HOME/.config/zsh/.zshenv $HOME/.zshenv\n</code></pre> <p>Check the configuration is working by loading the .zshenv configuration</p> <pre><code>source \"$ZDOTDIR/.zshenv\"\n</code></pre> <p>Using Oh My Bash</p> <p>If preferring Bash, then ohmybash provides a nice command line experience, showing completions clearer, nice themes that provide information.</p>"},{"location":"termux/fdroid-install/","title":"Install Termux via the F-Droid App","text":"<p>Visit the FDroid app website and download F-Droid, which saves an F-Droid.apk file.  Android may display a security prompt stating the browser does not have permissions to install software.  The popup should include a configure link that opens the Android settings to allow the browser to install software.</p> <p>F-Droid should now be installed and its icon added to the Android system alongside all other Android apps.</p> <p>Open the F-Droid App and allow it to update its repositories, to ensure the latest list of apps are shown.</p> <p>Search for the Termux application, clicking on the Termux name if more details are required.</p> <p>Select the Install button.</p> <p></p> <p>When installing apps from F-Droid for the first time, a security prompt is show as F-Droid is an unknown source.</p> <p>Select Settings to open the Android settings and enable Allow from this source for the F-Droid app.</p> <p></p> <p>A Termux App launcher will be added to the Android screen.  Consider adding the Termux icon to the commonly used icons bar.</p>"},{"location":"termux/fdroid-install/#termux-styling","title":"Termux Styling","text":"<p>Styling is a Termux plugin that provides a visually richer experience. Styling contains beautiful color schemes and powerline-reaqdy fonts to customise the appearance of the terminal</p> <p>Install the package via F-Droid</p> <p></p> <p>The styling menu is accessed via a long press on the Termux app screen, showing a More &gt; Style option on the usual cut/copy/paste popup menu. Practicalli recommends <code>FiraCode</code> fonts.</p>"},{"location":"termux/git/","title":"Git version control","text":"<p>A Git client is used to version control projects and to clone projects and configuration from GitHub/GitLab.  Practicalli maintains several editor configurations in shared repositories on GitHub</p> <ul> <li>Install a Git Client (and optionally GitHub CLI)</li> <li>[optionally] clone the practicalli/dotfiles repository for the Git config and global ignores</li> <li>Configure an SSH key to access remote repositories (or Developer token if you cannot use SSH keys)</li> </ul>"},{"location":"termux/git/#install-a-git-client-and-github-cli","title":"Install a git client and GitHub CLI","text":"<pre><code>pkg install git gh\n</code></pre> <p>Clone the practicalli/dotfiles repository</p> <pre><code>git clone https://github.com/practicalli/dotfiles projects/dotfiles\n</code></pre> <p>Move or symbolically link the top-level directories to <code>~/.config</code>, e.g. for the Git configuration:</p> <pre><code>ln -s projects/dotfiles/git ~/.config/git\n</code></pre> <p>Edit the <code>.config/git/config</code> and update the <code>core.user</code>,  <code>core.name</code> and <code>github</code> or <code>gitlab</code> identities</p>"},{"location":"termux/git/#create-ssh-key-for-remote-repository-access","title":"Create SSH Key for remote repository access","text":"<p>Install the openssh package which contains the <code>ssh-keygen</code> command to generate a new public/private key combinations for use with GitHub SSH repository URLs</p> <pre><code>pkg install openssh\n</code></pre> <p>Generate a key using the email address of the GitHub or GitLab account</p> <pre><code>ssh-keygen -t rsa -C name@domain.tld\n</code></pre> <p>RET to confirm storing the keys in the default location.</p> <p>Usually a passphrase is recommended, however, termux does not seem to save a keyring to save the key passphrase using <code>ssh-add</code>.  So the passphrase must be entered each time the key is used, unless a blank passphrase is used.</p> <p>Vist your GitHub account settings and create a new SSH key</p> <p>Use <code>cat  ~/.ssh/id_rsa.pub</code> to show the public key contents.  Press the screen to select and copy the public key to the clipboard.</p> <p>Paste the public key into the GitHub new key form.</p>"},{"location":"termux/git/#optional-create-a-developer-token","title":"[optional] Create a developer token","text":"<p>A developer token (or ssh key) is required to access GitHub {and far more secure over password}</p> <p>Should the android device become lost or compromised, the developer token can be deleted to protect the repositories from any malicious access.  The developer token should be limited to the minimal access.  The developer token does not give access to the GitHub or GitLab account.</p> <p>HTTPS URLs should be used with a developer token.  git@git.com URLs are for SSH keys only.</p> <p>Visit GitHub / GitLab settings for your account</p> <p>Create a new developer token specifically for Termux</p> <p>Add a descriptive name for the token, based on the device Termuxc is runniung on, e.g. <code>Termux Pixel2XL</code></p> <p>Check the public_repo and status repo scopes</p> <p>Generate button creates a new token.</p> <p>Copy the token using the copy icon.</p> <p>Edit the <code>.config/git/config</code> file and add a github section with the GitHub account name and token</p> <pre><code>[github]\n    name = practicalli\n    token = ghp_************************************\n</code></pre> <p>Consider using GitHub CLI to cache the developer token rather than write the token to the Git configuration file for greater security.</p>"},{"location":"termux/neovim/","title":"Install neovim","text":"<p>Neovim version 8 availabe as current package</p> <pre><code>pkg install neovim\n</code></pre>"},{"location":"termux/neovim/#neovim-treesitter","title":"Neovim treesitter","text":"<p>Treesitter provides excellent language syntax parsing and highlighting and is a very attractive feature of the recent neovim releases.  Treesitter is a major attraction, bringing in a new audience for Neovim.</p> <p>The <code>nvim-treesitter</code> package is included in the practicalli/neovim-config-redux configuration.</p>"},{"location":"termux/neovim/#c-compiler","title":"C Compiler","text":"<p>Install C compiler for neovim-treesitter, to compile a parser for each specific programming language.</p> <pre><code>pkg install clang\n</code></pre> <p><code>gcc</code> is not packaged for Termux, although there are guides to install gcc if preferred. clang has proved to be capable of creating the parsers used in the Practicalli configuration.</p>"},{"location":"termux/neovim/#searching-files","title":"Searching files","text":"<p>Telescope and other packages that involve searching for files recommend using ripgrep, a highly optomised tool for finding files on the operating system.</p> <pre><code>pkg install ripgrep\n</code></pre>"},{"location":"termux/neovim/#optional-nodejs","title":"[optional] nodejs","text":"<p>Optional.  Only if node.js is required as a Neovim provider and JavaScript or ClojureScript development is to be done.</p> <pre><code>pkg install nodejs\n</code></pre>"},{"location":"termux/setup/","title":"Termux Setup","text":"<p>Launch Termux via its application icon.  A black terminal screen will appear with a bash shell prompt.</p>"},{"location":"termux/setup/#update-packages","title":"Update packages","text":"<p>Check for new packages and update them all</p> <pre><code>pkg upgrade -y\n</code></pre> <p>If you wish to first check the packages that will be updated, use <code>pkg --list-upgradable</code></p> <p>Select a specific region to minimise the number of mirrors checked during package upgrades, especially useful if on a limited data plan.</p> <pre><code>termux-change-repo\n</code></pre> <p></p> <p>At time of writing, the Termux package on F-Droid was around 6 months old so there will be a number of packages that should be updated before any further installation steps are undertaken.</p>"},{"location":"termux/setup/#configure-freedesktoporg-xdg-locations","title":"Configure Freedesktop.org XDG locations","text":"<p>Edit the <code>~/.profile</code> file, adding export directives to set the XDG locations:</p> <pre><code>nano ~/.profile\n</code></pre> XDG locations<pre><code># Common Free desktop.org locations\nexport XDG_CONFIG_HOME=$HOME/.config\nexport XDG_DATA_HOME=$HOME/.local/share\nexport XDG_STATE_HOME=$HOME/.local/state\nexport XDG_CACHE_HOME=$HOME/.cache\n\n# Set XDG location of Emacs Spacemacs configuration\nexport SPACEMACSDIR=\"$XDG_CONFIG_HOME/spacemacs\"\n</code></pre> <p>Load the environment variables into the shell, or exit Termux and restart.</p> Load .profile into shell<pre><code>source ~/.profile\n</code></pre> <p>nano editor installed by default</p> <p><code>nano</code> editor is used to edit the commands as the package is installed by default in termux. <code>vim</code>, <code>neovim</code>, <code>emacs</code> or any other Linux command line editor can be used if the package is first installed.  Termux will list packages to install when trying to run a command that is from a package not yet installed.</p>"},{"location":"termux/setup/#tools-to-download-binaries-and-configuration","title":"Tools to download binaries and configuration","text":"<p>Many tools can be installed via the <code>pkg</code> tool, although specific Clojure tools and configuration require additional tools:</p> <ul> <li><code>wget</code> and <code>curl</code> - download tools not packaged, i.e. clojure-lsp binary</li> <li><code>git</code> - clone configuration files and projects (see Git version control section)</li> <li><code>openssh</code> - SSH service and tools to generate SSH keys</li> </ul> <pre><code>pkg install curl wget git openssh\n</code></pre> <p>Configure a Git Identify and SSH key to before committing and pushing changes, or cloning repositories using the SSH protocol.  practicalli/dotfiles contains example configuration, ignore patterns and commit template for using Git.</p>"},{"location":"termux/setup/#optional-configure-termux-settings","title":"[Optional] Configure Termux Settings","text":"<p>Edit <code>~/.termux/termux.properties</code> to configure the default settings for termux.</p> <pre><code>nano ~/.termux/termux.properties\n</code></pre> <p>Load <code>termux.properties</code> if values are changed (restarting Termux is not enough to load setting changes)</p> <pre><code>termux-reload-settings\n</code></pre> <p>The defaults are suitable for the majority of uses, although you may wish to consider:</p> <ul> <li><code>fullscreen</code> set to <code>true</code> to us the whole screen, hiding Android menu bars, etc.</li> <li><code>hide-soft-keyboard-on-startup</code> set to <code>true</code> if always using a physical keyboard</li> <li><code>default-working-directory</code> to save files user files and directories in an alternative location,</li> </ul> <p>If swiping from left edge of the screen is already taken, set key bindings for creating a new termux session, naming a session and switching between sessions.  Alternatively, use byobu to create and switch between its tabs for multiple terminal sessions.</p>"},{"location":"termux/setup/#set-color-scheme-and-font","title":"Set Color Scheme and Font","text":"<p>The Termux:Styling plug provides menus for selecting terminal color scheme and font to use</p> <p>Press and hold on the Termux screen to show the context menu and select the Style menu.  On smaller screens select More &gt; Style</p> <p>If Termux:Styling plugin was not installed, a prompt will display asking if the plugin should be installed</p> <p>A menu appears with Choose Color and Choose Font</p> <p>Select Choose Color to select from the available list of colour schemes, e.g. Gruvbox Dark or Gruvbox Light</p> <p><code>~/.termux/colors.properties</code> file is added when selecting a colour scheme, defining Hex colors from the theme selected.</p> <p>Select Choose Font to select from the available fonts, e.g. FiraCode or Ubuntu</p> <p><code>~/.termux/font.ttf</code> font file is added when selecting a font.</p> <p>Termux:Styling uses NerdFonts for icons</p> <p>All fonts installed via <code>Termux:Styling</code> have been patched with NerdFonts, providing several thousand icons to use within the terminal prompt and Neovim itself (e.g. VimDevIcons).</p>"},{"location":"termux/using-termux/","title":"Using Termux","text":"<p>Start Termux app and a terminal prompt is shown, along with the standard Android software keyboard.  An extended keyboard is provided with common key bindings for the command line interface (Tab, Esc, Ctrl, arrow keys, etc.).</p> <p></p>"},{"location":"termux/using-termux/#keyboards","title":"Keyboards","text":"<p>Termux provides an extended keyboard with key combinations not possible with the Android software keyboard, i.e <code>Ctrl-c</code>, arrow keys, etc.  <code>TAB</code> is especially useful for driving command and filename completion.</p> <p><code>Volume Up + q</code> toggles the extended keyboard, so more screen is available when using a hardware keyboard.</p> <p>Connect a hardware keyboard for the best experience, e.g the Keyboard.io atreus is an excellent and highly portable mechanical keyboard. The software keyboard is automatically switched off when a hardware keyboard is connected, although the extended keyboard is still displayed by default.</p>"},{"location":"termux/using-termux/#adjusting-font-size","title":"Adjusting Font size","text":"<p>Pinch the screen inwards to zoom out making the text font smaller.</p> <p>Pinch the screen outwards to zoom in making the text font larger.</p>"},{"location":"termux/using-termux/#termux-menus","title":"Termux menus","text":"<p>Termux has three menus: A context menu, navigation drawer and Termux section of the Android notification.</p> <p>The context menu is shown by a long press anywhere on the terminal screen:</p> <ul> <li><code>Select</code> and <code>Paste</code> text to share text with other applications</li> <li><code>Reset</code> the terminal if it gets stuck or <code>Hangup</code> to exit the current terminal session</li> <li><code>Style</code> the terminal by selecting a font and a color scheme</li> </ul> <p>The navigation drawer is shown by swiping inwards from the left of the screen</p> <ul> <li>list and select terminal sessions, set a name for a session with a long press</li> <li>A button to toggle visibility of the touch keyboard.</li> <li>A button to create new terminal sessions (long press for creating a named session or a fail-safe one).</li> </ul> <p>If gesture navigation is enabled in Android, hold the edge of the screen briefly before swiping to bring up the navigation drawer</p> <p>The Android notification menu contains a Termux section. Press the Termux section to show the current terminal session or expand the Termux section to exiting all running terminal sessions or aquire a wake lock to avoid Termux entering sleep mode. A wake lock allows server and other background processes to run reliably and to continue to receive notifications</p>"},{"location":"termux/using-termux/#package-management","title":"Package management","text":"<p>Termux provides a Linux command line experience, providing a wide range of Unix tools and development environments.  Termux uses a Debian based system and packages are easily installed</p> <ul> <li><code>apt install</code> add tools and libraries to the Linux environment from the curated packages in the software center</li> <li><code>apt update</code> updates the list of packages fromhe software center</li> <li><code>apt list --upgradable</code> shows list of packages with new versions</li> <li><code>apt upgrade</code> install new versions of currently installed packages</li> <li><code>apt-cache search --names-only</code> - search for packages that include a specific pattern in their name.</li> <li><code>apt-cache show</code> - shows detail of the supplied package name, including a description</li> </ul> <p><code>pkg</code> is an alias for <code>apt</code>, the advance package tool, although there seems little benefit to using pkg if familiar with apt (they are both 3 characters)</p>"},{"location":"termux/using-termux/#byobu-terminal-tab-manager","title":"Byobu terminal tab manager","text":"<p>Byobu is an alternative to Termux provides a single terminal prompt. Byobu provides multiple shell prompts, allowing individual Clojure tools and editors to be run from the Termux prompt simultaneously.  Practicalli uses byobu to run Neovim, a Clojure REPL and unit test watcher in separate byobu tabs with the ability to add further tabs for other command line tools.</p> <pre><code>pkg install byobu\n</code></pre> <ul> <li><code>F2</code> to create a new tab</li> <li><code>F3</code> to select previous tab</li> <li><code>F4</code> to select next tab</li> </ul> <p><code>byobu-enable</code> command will configure the current shell to run byobu on startup.  Test this is working by typing <code>exit</code> in Termux and start Termux app again. <code>byobu-disable</code> stops this behaviour and byobu will need to be run manually after starting Termux.</p> <p>Run the <code>byobu-enable</code> command again if zsh is configured after this step or if adding any other shell to Termux.</p>"},{"location":"version-control/","title":"Version Control","text":"<p>There are several ways to interact with Git version control, although Practicalli recommends Neogit interactive git client and Octo to manage GitHub issues and pull requests</p> <ul> <li>lazygit terminal UI, embedded in Neovim (AstroNvim only)</li> <li>Neogit git client similar to Emacs Magit, with Diffview integration</li> <li>Octo for GitHub Issue and Pull Requests</li> <li>Open in GitHub</li> <li>Shell out to the command line, <code>:!</code> </li> <li>Git commands in Neovim terminal buffer</li> </ul>"},{"location":"version-control/#init-local-repository","title":"Init local repository","text":"AstroNvim <p>Space t f opens floating terminal window in the current project directory root (or which ever directory Neovim was started from).</p> <p>Initialise a local git repository in the current directory. <pre><code>git init .\n</code></pre></p>"},{"location":"version-control/#stage-in-buffer","title":"Stage in buffer","text":"AstroNvimPracticalli Neovim Config Redux <p>The current hunk or the whole buffer can be staged from the buffer using Git Signs, saving a trip to the Git Status buffer.</p> <p>Space g H stages the current hunk</p> <p>Space g S stages the current buffer</p> <p>Not supported.  </p>"},{"location":"version-control/#git-status","title":"Git Status","text":"AstroNvimPracticalli Neovim Config Redux <p><code>SPC g g</code> opens lazygit status, for minimal UI</p> <p> </p> <p>Space g s Space g n ++\"t\" opens neogit in a new tab for Magit style experience</p> <p><code>SPC g s</code> opens Git Status tab, by running <code>:Neogit</code></p> <p></p>"},{"location":"version-control/#github-integration","title":"GitHub integration","text":"<p>Interact with the remote GitHub repository using Octo</p> <p>List issues from a specific repository</p> <pre><code>:Octo issue list practicalli/neovim\n</code></pre> <p></p> <p>Create a pull request on a specific repository</p> <pre><code>:Octo pr create practicalli/neovim\n</code></pre>"},{"location":"version-control/diff/","title":"Diff","text":"<p>Compare differences between different files or between a file and its versions.</p> <p><code>:diffsplit filename</code> Neovim command opens a split containing the selected filename, showing a diff comparision to the currently opened file </p> <p>file path completion helps select the correct file for comparison</p>"},{"location":"version-control/diff/#git-diff","title":"Git Diff","text":"<p>DiffView compares working space and staged changes side by side, or a diff for git merge conflicts.</p> <p>++SPC++ g d or <code>d</code> in neogit status buffer (<code>SPC g s</code>) will open diffview in a new tab</p> <p><code>q</code> to return to neogit status buffer</p> <p></p> <ul> <li>Green - added lines</li> <li>Yellow - changed line</li> <li>Red - deleted lines</li> </ul> AstroNvimPracticalli Neovim Config <p>Ctrl h / j / k / l to navigate between open splits</p> <p><code>SPC b</code> toggles the sidebar buffer</p> <p><code>SPC w l</code> and <code>SPC w h</code> to move cursor between diff buffer and sidebar buffer</p> <p></p>"},{"location":"version-control/lazygit/","title":"Lazygit version control","text":"Command Line or AstroNvim configuration <p>Lazygit interface not provided by Practicalli Neovim Config Redux</p>"},{"location":"version-control/lazygit/#requirements","title":"Requirements","text":"<p>Install lazygit command line tool</p>"},{"location":"version-control/lazygit/#open-lazygit","title":"Open Lazygit","text":"AstroNvimCommand Line <p><code>SPC g g</code> to open git status with lazygit in a popup window</p> <p>Change to the root directory of the git managed project.</p> <p>Run the lazygit rich terminal UI</p> <pre><code>lazygit\n</code></pre>"},{"location":"version-control/lazygit/#use-lazygit","title":"Use Lazygit","text":"<p><code>SPC</code> to stage files or directories in the files section of the UI</p> <p><code>c</code> for a simple commit message prompt in the lazygit UI</p> <p><code>C</code> to create a commit message within the</p> <p>Define Editor for Git Commit Messages</p> <p>Set <code>core.editor</code> in the user Git configuration (i.e. <code>.config/git/config</code>) to the name of the editor to use for commit messages, e.g. <code>nvim</code>, <code>emacsclient</code>) <code>shell title= git config --global core.editor = nvim</code> Alternatively, use the <code>VISUAL</code> or <code>EDITOR</code> environment variable to the choice of editor</p>"},{"location":"version-control/neogit/","title":"Neogit - interactive client for Git","text":"<p>Neogit is an interactive git client that provides the core features of version control with Git.  Neogit emulates many of the features found in magit.</p> <p><code>SPC g s</code> to open <code>:Neogit</code> status buffer</p> <p><code>TAB</code> toggles expansion of sections, files and hunks</p> <p><code>d</code> provide a side-by-side view of changes</p> <p><code>q</code> to quit Neogit and return to the previous tab</p> <p></p> <p>Neovim is configured to use the magit style key bindings in practicalli/neovim-config-redux</p>"},{"location":"version-control/neogit/#branching","title":"Branching","text":"<p><code>b</code> opens the branch menu,</p> <ul> <li><code>b</code> - checkout a branch</li> <li><code>c</code> - create a new branch</li> <li><code>d</code> - delete a branch, <code>D</code> deletes local and remote branch</li> <li><code>l</code> - checkout a remote branch and create a local tracking branch</li> <li><code>m</code> - rename an existing local branch</li> <li><code>n</code> - create a new branch</li> </ul>"},{"location":"version-control/neogit/#staging-changes","title":"Staging changes","text":"<p><code>s</code> to stage change under cursor, either file or hunk. <code>S</code> to stage all changes</p> <p><code>u</code> to unstage change under cursor, <code>U</code> to unstage all changes</p> <p><code>v</code> to select lines to stage within a hunk using <code>s</code> or unstage with <code>u</code></p>"},{"location":"version-control/neogit/#commit","title":"Commit","text":"<p><code>c</code> for the commit menu</p> <p><code>c</code> for a new commit, <code>a</code> to amend the latest commit, <code>w</code> to reword a commit message, <code>e</code> to add staged changes to existing commit</p> <p>A new commit or amend commit qill open a new window to write a commit message (using a git commit message template if defined)</p> <p><code>:wq</code> to save a commit message and initiate the commit.</p> <p><code>:q!</code>  to cancel the commit from the commit message buffer.</p>"},{"location":"version-control/neogit/#stashing-changes","title":"Stashing changes","text":"<p><code>Z</code> to open the stash menu</p> <p><code>z</code> to stash the working copy and staged files (index)</p> <p><code>i</code> to only stash the staged files (index)</p>"},{"location":"version-control/neogit/#remote-changes","title":"Remote changes","text":"<p><code>F</code> to open the pull menu, <code>p</code> to pull changes (fetch and merge) from the remote repository, <code>u</code> t pull from the upstream repository, or <code>e</code> to specify the remote and branch names.</p> <p><code>P</code> to open the push menu to open, <code>-u</code> to push to the current remote</p> Confused when remote is not origin <p>Use <code>e</code> option to push to elsewhere when the remote name is not set to <code>origin</code>.  The <code>e</code> option will prompt for a remote name and branch.</p>"},{"location":"version-control/neogit/#commit-history","title":"Commit history","text":"<p><code>L l</code> to view git commit history log</p> <p><code>RET</code> on a log entry shows the commit details in a new window (split)</p> <p><code>q</code> to close the commit details window</p>"},{"location":"version-control/neogit/#modify-git-commit-history","title":"Modify Git commit history","text":"<p><code>r</code> opens the rebase menu</p>"},{"location":"version-control/octo/","title":"Octo - GitHub issues and PRs","text":"<p>List, create and edit issues and pull requests from Neovim with Octo package.</p> <p>Octo connects to GitHub via the GitHub CLI, using a developer token for authentication</p> <p>Neogit provides a Magit style client, creating commits, pull &amp; push changes with remote repositories.</p>"},{"location":"version-control/octo/#github-interaction","title":"GitHub interaction","text":"<p>GitHub CLI</p> <p>Work with GitHub issues and Pull Requests from the comfort of Neovim.</p> <p>GitHub CLI to authentication to a GitHub account.  Successful login creates a local developer token that is used by Octo to communicate with GitHub.</p> <pre><code>gh auth login\n</code></pre>"},{"location":"version-control/octo/#octo-commands","title":"Octo commands","text":"<p>Command line form: <code>Octo &lt;object&gt; &lt;action&gt; [arguments]</code> - Object, Action and Arguments commands</p> <p>List issues from current project (optionally add a specific repository)</p> <pre><code>:Octo issue list practicalli/neovim\n</code></pre> <p>The account/repository-name is required if Octo cannot find the repository</p> <p></p> <p>Create a pull requests from current project</p> <pre><code>:Octo pr create\n</code></pre> <p>Add a comment to the current topic (issue/pr) <pre><code>:Octo comment add\n</code></pre></p> <pre><code>:Octo gist list\n</code></pre> <p></p> <p>Octo.nvim configuration options</p> <p>Octo.nvim configuration options</p>"},{"location":"version-control/open-in-github/","title":"Open In GitHub","text":"<p>Open a file under local version control in the GitHub web UI (browser window).</p> Neovim <p><code>:OpenInGHFile</code></p> <p><code>:OpenInGHRepo</code></p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Neovim for Clojure development","text":"<p>coding at the speed of thought</p> <p>Neovim is incredibly fast and efficient, so thoughts flow from brain to editor without unnecessary delay.</p> <p>Touch typing is fast, Neovim and multi-modal editing makes it even faster.</p> <p>Neovim is a highly extensible and powerful editor, supporting multi-modal editing and Vim-style sequential key bindings. Highly responsive and low resource use makes Neovim ideal for development on any computer or  mobile device, e.g. tablet, smartphone.</p> <p>Neovim has  a diverse set of plugins and  Practicalli curated configurations use these plugins to provide a  rich set of features for Clojure development and wider engineering tasks.</p> <p>Practicalli Neovim provides install &amp; user guide focused on a simple, powerful and satisfying REPL Driven workflow for Clojure.</p> <p></p>"},{"location":"#quick-start","title":"Quick Start","text":"<p>Install Clojure, Neovim and choose a community configuration</p> <ul> <li>[Lua] AstroNvim</li> <li>[Fennel] Practicalli Neovim Config Redux</li> </ul>"},{"location":"#external-reverences","title":"External reverences","text":"<p>Getting started with Neovim and Conjure</p> <p>Neovim user guide</p> <p>This Week In Neovim - community update</p> <p>Conjure install guide Conjuring Clojure in Vim</p>"},{"location":"#navigate-the-book","title":"Navigate the book","text":"<p>Use the mouse or built-in key bindings to navigate the pages of the book</p> <ul> <li>P , , : go to previous page</li> <li>N , . : go to next page</li> </ul> <p>Use the search box to quickly find a specific topic</p> <ul> <li>F , S , / : open search dialog</li> <li>Down , Up : select next / previous result</li> <li>Esc , Tab : close search dialog</li> <li>Enter : follow selected result</li> </ul>"},{"location":"#sponsor-my-work","title":"Sponsor my work","text":"<p>All sponsorship recieved is used to maintain and further develop the Practicalli series of books and videos, although most of the work is still done with my own time and cost.</p> <p>Thank you to Cognitect, Nubank and a wide range of other sponsors from the Clojure community for your continued support</p>"},{"location":"#creative-commons-license","title":"Creative commons license","text":"This work is licensed under a Creative Commons Attribution 4.0 ShareAlike License (including images &amp; style sheets)."},{"location":"api-tools/","title":"API Tools","text":"<p>Astrocommunity proivdes plugins to support working with APIs and the JSON format</p> <ul> <li> nvim-jqx</li> <li> rest-nvim</li> </ul> <p>Included in Practicalli Astronvim Config</p> <p>Practicalli Astronvim Config includes nvim-jqx and rest.nvim plugins</p>"},{"location":"api-tools/#inspect-json","title":"Inspect JSON","text":"<p>Browse and preview json files in neovim.</p> <p><code>:JqxList</code> prettify JSON and start the inspector</p> <p><code>JqxQuery</code> to run complex <code>jq</code> commands</p> jq binary required <p><code>jq</code> binary should be available on the command line as nvim-jqx runs jq queries internally</p> <p></p> <p> nvim-jqx</p>"},{"location":"api-tools/#call-apis","title":"Call APIs","text":"<p>Space r r to run an http request under the cursor from within an <code>*.http</code> file.</p> <p>A fast Neovim http client written in Lua, providing a curl wrapper.</p>"},{"location":"api-tools/#http-file","title":"http file","text":"<p>Open a file with an <code>*.http</code> extension</p> <p>Write a call to an API, e.g. a call to a local server health care endpoint</p> <p>Call locally running API</p> health-check.http<pre><code>GET http://localhost:8080/system-admin/status\n</code></pre> <p>A new window opens with the result of the API call</p> Result of API call with rest.nvim <pre><code>GET http://localhost:8080/system-admin/status\nCommand :curl -sSL --compressed -X 'GET' --data-raw '' 'http://localhost:8080/system-admin/status'\n#+END\nHTTP/1.1 200 OK\nContent-Type: application/json; charset=utf-8\nContent-Length: 66\nServer: http-kit\nDate: Mon, 10 Jul 2023 16:21:33 GMT\n\n#+RESPONSE\n{\"application\":\"practicalli hole-in-one Service\",\"status\":\"Alive\"}\n#+END\n</code></pre> <p>The <code>Content-Type</code> can be explicitly set, especially useful when not using JSON</p> <p>API call returning EDN data</p> <pre><code>GET http://localhost:8080/api/v1/scoreboard\naccept: application/edn\n</code></pre> <p> rest.nvim test examples </p> <p> rest.nvim</p>"},{"location":"assets/images/social/","title":"Social Cards","text":"<p>Social Cards are visual previews of the website that are included when sending links via social media platforms.</p> <p>Material for MkDocs is configured to generate beautiful social cards automatically, using the colors, fonts and logos defined in <code>mkdocs.yml</code></p> <p>Generated images are stored in this directory.</p>"},{"location":"configuration/","title":"Neovim Configuration","text":"<p>Practicalli Neovim covers the following configurations.</p> <ul> <li>AstroNvim - thoughtful configuration, supports Neovim 0.9 onward, polished UI, many community extensions</li> <li>Practicalli Neovim Config Redux - mnemonic key bindings, packer, telescope selector, written in Fennel</li> </ul>"},{"location":"configuration/#multiple-configurations","title":"Multiple Configurations","text":"<p>Install multiple configurations, e.g. AstroNvim, lazyvim, Nvchad, etc. in the <code>$HOME/.config</code> directory using unique directory names.</p> <p>Set <code>NVIM_APPNAME</code> to specific the configuration to use when running nvim.</p> <pre><code>NVIM_APPNAME=astronvim nvim\n</code></pre> <p><code>NVIM_APPNAME</code> variable should be set to the directory name containing the configuration, relative to the <code>.config</code> directory.</p> <p>The configuration directory name is used to hold <code>share</code>, <code>state</code> and <code>cache</code> files for that specific configuration.</p> <p>Create shell aliases for each configuration. Optionalliy, define a terminal UI selection to choose a configuration.</p> Shell AliasesTerminal UI Selector <p>Create a Shell alias for each configuration that will be used, to avoid setting the <code>NVIM_APPNAME</code> variable each time.</p> <p>Define Shell Aliases to run each configuration</p> <pre><code>alias astro=\"NVIM_APPNAME=astronvim nvim\"\nalias lazyvim=\"NVIM_APPNAME=lazyvim nvim\"\nalias practicalli-redux=\"NVIM_APPNAME=neovim-config-redux nvim\"\n</code></pre> <p>Create an nvim configuration selector script, with items listing the directory name of each configuration</p> <p>Z Shell nvim-selector script</p> .local/bin/nvim-selector<pre><code>function nvim-selector() {\n  items=(\"astronvim\" \"neovim-config-redux\" \"lazyvim\")\n  config=$(printf \"%s\\n\" \"${items[@]}\" | fzf --prompt=\"\ue62b Neovim Config \uf63d \" --height=~50% --layout=reverse --border --exit-0)\n  if [[ -z $config ]]; then\n    echo \"Nothing selected\"\n    return 0\n  elif [[ $config == \"default\" ]]; then\n    config=\"\"\n  fi\n  NVIM_APPNAME=$config nvim $@\n}\n</code></pre>"},{"location":"configuration/astronvim/","title":"AstroNvim","text":"<p> AstroNvim is a community configuration with an engaging UI, using Lazy for plugin management (Neovim packages) and Mason for package management (LSP, DAP, format and lint tools)</p> <p> Practicalli AstroNvim Config is a user configuration that extends AstroNvim and imports packages from the  AstroNvim Community.</p>"},{"location":"configuration/astronvim/#prerequisits","title":"Prerequisits","text":"<ul> <li>Nerd Fonts version 3 - download a full font or only the symbols</li> <li>fzf fuzzy finder (ubuntu archive)</li> <li>gtu (Ubuntu package archive)</li> <li>btm from GitHub repository releases</li> <li>node.js (version 20) for Mason install of many LSP servers</li> </ul> <p>AstroNvim requires node.js</p> <p>AstroNvim uses Mason to install LSP servers, format and lint tools.  Many LSP servers require node.js to install and function.</p> <p>Node.js install - Practicalli Engineering Playbook </p> Kitty Terminal with Nerd Fonts <p> Kitty Terminal - Practicalli Engineering Playbook provides examples of using Nerd Fonts or Nerd Font symbols with the Kitty terminal.</p>"},{"location":"configuration/astronvim/#clone-astronvim","title":"Clone AstroNvim","text":"<p>Clone AstroNvim repository to <code>$HOME/.config/astronvim/</code></p> <pre><code>git clone --depth 1 https://github.com/AstroNvim/AstroNvim ~/.config/astronvim\n</code></pre> <p><code>$HOME/.config/nvim</code> can be used instead if only ever using one configuration for Neovim.</p>"},{"location":"configuration/astronvim/#clone-astronvim-user-config","title":"Clone AstroNvim user config","text":"<p>AstroNvim provides a  template repository to create a user configuration. The template includes  AstroNvim Community configuration to make it easier to extend the feature of AstroNvim.</p> <p> Practicalli AstroNvim Config is a clone of the AstroNvim user config with additional configuration to support Clojure development.</p> Practicalli AstroNvim ConfigAstroNvim User Config <p>Clone the  Practicalli AstroNvim config which provides a user configuration with Clojure support</p> <pre><code>git clone http://github.com/practicalli/astronvim-config $HOME/.config/astronvim/lua/user\n</code></pre> <p>Or clone to a separate directory and create a symbolic link</p> <pre><code>git clone http://github.com/practicalli/astronvim-config $HOME/.config/astronvim-config &amp;&amp; \\\nln -s $HOME/.config/astronvim-config/ $HOME/.config/astronvim/lua/user\n</code></pre> <p>Create your own user configuration using the AstroNvim user configuration template repository.</p> <p>Create a repository from the AstroNvim/user_example repository template</p> <p></p> <p>Clone the newly created repository into the existing AstroNvim configuration, in a <code>user</code> directory <pre><code>git clone git@github.com/&lt;github-account&gt;/&lt;new-repository&gt; $HOME/.config/astronvim/lua/user\n</code></pre></p>"},{"location":"configuration/astronvim/#configure-shell-alias","title":"Configure shell alias","text":"<p>Create a shell alias that sets <code>NVIM_APPNAME</code> to the location of the AstroNvim community config</p> <p>Add alias to <code>.bashrc</code> for Bash shell or <code>.zshenv</code> for Zsh</p> <pre><code>alias astro=\"NVIM_APPNAME=astronvim nvim\"\n</code></pre> <p> Configure shell alias</p>"},{"location":"configuration/astronvim/#post-install","title":"Post install","text":"<p>Open a terminal and use the <code>astro</code> alias to run Neovim.</p> <pre><code>astro\n</code></pre> <p><code>NVIM_APPNAME=astronvim nvim</code> to run Neovim with astronvim without setting a shell alias.</p> <p>Neovim will open and display the Lazy plugin manager UI, showing the progress of plugin installation.  This should only happen on the first run.</p> Unattended post install <p>Plugins can be installed without running the Neovim editor UI</p> <pre><code>nvim --headless -c 'autocmd User LazyDone quitall'\n</code></pre>"},{"location":"configuration/astronvim/#check-health","title":"Check Health","text":"<p>Run the Neovim <code>:checkhealth</code> command to report on the general Neovim install and supporting tools</p>"},{"location":"configuration/astronvim/#add-lsp-dap-lint-and-format-tools","title":"Add LSP DAP Lint and Format tools","text":"<p><code>SPC p m</code> to launch Mason which manages LSP servers, linters, filters ...</p> <p></p>"},{"location":"configuration/astronvim/#configure-format-rules","title":"Configure format rules","text":"<p>The configuration files for each lint and format tool should be used by Neovim.</p> <p>Setting a different location for these files has proved challenging.  <code>plugin/null-ls.lua</code> has a section to override its builtin configuration for each lint and format tool, however, in tests Practicalli was unable to succeffuly set a different location.</p>"},{"location":"configuration/astronvim/config-design/","title":"\ud83d\udce6 Practicalli AstroNvim Config Design","text":"<p>A guide to the AstroNvim Config user configuration created by Practicalli to support Clojure development.</p> AstroCommunity used where possible <p>Plugins and configuration is added vial AstroCommunity were possible, to minimise the code size and maintenance of the configuration</p>"},{"location":"configuration/astronvim/config-design/#user-config-overview","title":"User Config overview","text":"<p><code>core.lua</code> is for tuning plugins shipped with astronvim config</p> <p><code>plugins/</code> for additional plugins organised logically. All <code>.lua</code> files are read from this directory </p> <ul> <li><code>user.lua</code> for general user defined plugins</li> <li><code>clojure.lua</code> adds Conjure and parinf, ensuring Clojure treesitter parser and Clojure LSP</li> </ul>"},{"location":"configuration/astronvim/config-design/#clojure-support","title":"Clojure support","text":"<p>The  AstroCommunity provides a Clojure language pack that adds Conjure and nvim-parinfer, along with <code>clojure</code> Treesitter parser and <code>clojure-lsp</code> support.</p> AstroCommunity PackManually add plugins <p>Edit the <code>plugins/community.lua</code> file and import the Clojure pack.  The <code>\"AstroNvim/astrocommunity\",</code> repository is already added to to the file.</p> <pre><code>-- Packs\n-- Treesitter: clojure , Lsp: clojure-lsp, Lint/format:\n{ import = \"astrocommunity.pack.clojure\" },\n</code></pre> Override AstroCommunity Pack <p>Create a <code>plugins/clojure.lua</code> file and add the AstroCommunity repository, Clojure pack and additional configuration to your own preferences</p> <p>Clojure configuration with user configration overrides</p> <pre><code>return {\n  \"AstroNvim/astrocommunity\",\n  { import = \"astrocommunity.pack.clojure\" },\n  {\n    \"Olical/conjure\",\n    -- load plugin on filetypes\n    ft = { \"clojure\", \"fennel\" },\n    config = function()\n      -- HUD\n      -- Example: Set to `\"SE\"` and HUD width to `1.0` for full width HUD at bottom of screen\n      vim.g[\"conjure#log#hud#width\"] = 1 -- Width of HUD as percentage of the editor width, 0.0 and 1.0.\n      vim.g[\"conjure#log#hud#enabled\"] = false -- Display HUD\n      vim.g[\"conjure#log#hud#anchor\"] = \"SE\" -- Preferred corner position for the HUD\n      vim.g[\"conjure#log#botright\"] = true -- Open log at bottom or far right of editor\n      -- REPL\n      vim.g[\"conjure#extract#context_header_lines\"] = 100 -- Number of lines to check for `ns` form\n      vim.g[\"conjure#client#clojure#nrepl#connection#auto_repl#enabled\"] = false -- ;; Start \"auto-repl\" process, eg. babashka\n      vim.g[\"conjure#client#clojure#nrepl#connection#auto_repl#hidden\"] = true -- ;; Hide auto-repl buffer when triggered\n      vim.g[\"conjure#client#clojure#nrepl#connection#auto_repl#cmd\"] = nil -- ;; Command to start the auto-repl\n      -- ;; Automatically require namespace of new buffer or current buffer after connection\n      vim.g[\"conjure#client#clojure#nrepl#eval#auto_require\"] = false\n      -- Reloading code\n      -- Function to call on refresh (reloading) the log, namespace-qualified name of a zero-arity\n      -- vim.g[\"conjure#client#clojure#nrepl#refresh#after\"] = nil\n      -- The namespace-qualified name of a zero-arity function to call before reloading.\n      -- vim.g[\"conjure#client#clojure#nrepl#refresh#before\"] = nil\n      -- List of directories to scan. If no directories given, defaults to all directories on the classpath.\n      -- vim.g[\"conjure#client#clojure#nrepl#refresh#dirs\"] = nil\n      -- Testing\n      -- ;; Test runner called from the test key mappings\n      vim.g[\"conjure#client#clojure#nrepl#test#runner\"] = \"kaocha\"\n      -- Print raw test evaluation result, suppressing prefix for stdout lines `; (out)`\n      -- vim.g[\"conjure#client#clojure#nrepl#test#raw_out\"] = nil\n      -- Override string appended to the end of the test runner calls\n      -- vim.g[\"conjure#client#clojure#nrepl#test#call_suffix\"] = nil\n    end\n  },\n  {\n    \"gpanders/nvim-parinfer\",\n    ft = { \"clojure\" },\n    config = function()\n      vim.g.parinfer_force_balance = true\n      vim.g.parinfer_comment_chars = \";;\"\n    end,\n  },\n}\n</code></pre> <p>Add Conjure and parinfer plugin that will load when Clojure or Fennel file is opened.</p> <p>Clojure Packages in AstroNvim user configuration</p> <pre><code>```lua title=\".config/astronvim-config/plugins/clojure.lua\"\n-- Lazy Package manager configuration\nreturn {\n  {\n    \"Olical/conjure\",\n    -- load plugin on filetypes\n    ft = { \"clojure\", \"fennel\" },\n  },\n\n  {\n    \"gpanders/nvim-parinfer\",\n    ft = { \"clojure\", \"fennel\" },\n    config = function()\n      vim.g.parinfer_force_balance = true\n      vim.g.parinfer_comment_chars = \";;\"\n    end,\n  },\n}\n```\n</code></pre> <p>Improve syntax highlighting by installing the Clojure parser for Treesitter.</p> <p>Treesitter Parser for clojure in AstroNvim user configuration</p> .config/astronvim-config/plugins/treesitter.lua<pre><code>return {\n  \"nvim-treesitter/nvim-treesitter\",\n  opts = function(_, opts)\n    -- add more things to the ensure_installed table protecting against community packs modifying it\n    opts.ensure_installed = require(\"astronvim.utils\").list_insert_unique(opts.ensure_installed, {\n      -- \"lua\"\n    \"clojure\"\n    })\n  end,\n}\n</code></pre> <p>Install Treesitter Clojure Parser manually</p> <p><code>:TSInstall clojure</code> in Neovim will install the parser. A parser not included in the <code>opts.ensure_installed</code> configuration must be updated manually each time treesitter plugin is updated</p> Switch to Parinfer Parens mode for Paredit structural editing <p>Changing the Parinfer mode to <code>paren</code> gives a structured editing experience similar to Paredit (or Smartparens).</p> <p>Add the following configuration within the <code>return {}</code> table in the <code>plugins/community.lua</code> file to set the parinfef mode, i.e. <code>paren</code>, <code>smart</code> or <code>indent</code> (default</p> plugins/community.lua<pre><code>  {\n    \"gpanders/nvim-parinfer\",\n    ft = { \"clojure\" },\n    config = function()\n      vim.g.parinfer_force_balance = true\n      vim.g.parinfer_comment_chars = \";;\"\n      vim.g.parinfer_mode = \"paren\"\n    end,\n  },\n</code></pre>"},{"location":"configuration/astronvim/config-design/#clojure-mappings","title":"Clojure Mappings","text":"<p>Conjure mappings are defined respective to a <code>&lt;localleader&gt;</code> value. Define a local leader in the AstroNvim user configuration, e.g. <code>,</code> and all Conjure mappings become available.</p> AstroNvim 3.17.0 has localleader <p>AstroNvim 3.17.0 release sets <code>localleader</code> to <code>,</code> so a separate setting is not required in the user configuration (unless a different localleader is preferred)</p> Set localleader in user config <p><code>options.lua</code> in the user configuration provides a consistent way to set Neovim options.</p> .config/astronvim-config/options.lua<pre><code>-- set vim options here (vim.&lt;first_key&gt;.&lt;second_key&gt; = value)\nreturn {\n  opt = {\n    -- set to true or false etc.\n    relativenumber = true, -- sets vim.opt.relativenumber\n    number = true,         -- sets vim.opt.number\n    spell = false,         -- sets vim.opt.spell\n    signcolumn = \"auto\",   -- sets vim.opt.signcolumn to auto\n    wrap = false,          -- sets vim.opt.wrap\n  },\n  g = {\n    mapleader = \" \",                 -- sets vim.g.mapleader\n    maplocalleader = \",\",            -- Set local leader key binding (supports Conjure key bindings)\n    autoformat_enabled = true,       -- enable or disable auto formatting at start (lsp.formatting.format_on_save must be enabled)\n    cmp_enabled = true,              -- enable completion at start\n    autopairs_enabled = true,        -- enable autopairs at start\n    diagnostics_mode = 3,            -- set the visibility of diagnostics in the UI (0=off, 1=only show in status line, 2=virtual text off, 3=all on)\n    icons_enabled = true,            -- disable icons in the UI (disable if no nerd font is available, requires :PackerSync after changing)\n    ui_notifications_enabled = true, -- disable notifications when toggling UI elements\n    VM_leader = \"gm\"                 -- Visual Multi Leader (multiple cursors)\n  },\n}\n</code></pre>"},{"location":"configuration/astronvim/config-design/#clojure-lsp","title":"Clojure LSP","text":"<p>Clojure LSP support is enabled via the AstroCommunity Clojure pack.</p> <p><code>clojure_lsp</code> can be added using Mason UI, <code>SPC p m</code> or in the <code>plugins/mason.lua</code> file</p> Manual user config of clojure lsp server <pre><code>-- customize mason plugins\nreturn {\n  -- use mason-lspconfig to configure LSP installations\n  {\n    \"williamboman/mason-lspconfig.nvim\",\n    -- overrides `require(\"mason-lspconfig\").setup(...)`\n    opts = function(_, opts)\n      -- add more things to the ensure_installed table protecting against community packs modifying it\n      opts.ensure_installed = require(\"astronvim.utils\").list_insert_unique(opts.ensure_installed, {\n        -- \"clojure_lsp\",  -- provide by Clojure pack\n        \"marksman\", -- Markdown structure (also in markdown pack)\n        \"yamlls\",\n      })\n    end,\n  },\n}\n</code></pre>"},{"location":"configuration/astronvim/config-design/#snippets","title":"Snippets","text":"<p>The AstroNvim user example includes a commented LuaSnip configuration</p> .config/astronvim-config/plugins/core.lua<pre><code>  -- {\n  --   \"L3MON4D3/LuaSnip\",\n  --   config = function(plugin, opts)\n  --     require \"plugins.configs.luasnip\" (plugin, opts)  -- include the default astronvim config that calls the setup call\n  --     -- add more custom luasnip configuration such as filetype extend or custom snippets\n  --     local luasnip = require \"luasnip\"\n  --     luasnip.filetype_extend(\"javascript\", { \"javascriptreact\" })\n  --   end,\n  -- },\n</code></pre> <p>AstroNvim includes a Recipe for custom snippets</p> <pre><code>return {\n  plugins = {\n    {\n      \"L3MON4D3/LuaSnip\",\n      config = function(plugin, opts)\n        require \"plugins.configs.luasnip\"(plugin, opts) -- include the default astronvim config that calls the setup call\n        require(\"luasnip.loaders.from_vscode\").lazy_load { paths = { \"./lua/user/snippets\" } } -- load snippets paths\n      end,\n    },\n  },\n}\n</code></pre> <p>Practicalli AstroNvim Config combines the two examples to get</p> <p>AstroNvim config with custom VS Code style snippets</p> .config/astronvim-config/plugins/core.lua<pre><code>{\n  \"L3MON4D3/LuaSnip\",\n  config = function(plugin, opts)\n    require \"plugins.configs.luasnip\" (plugin, opts) -- include the default astronvim config that calls the setup call\n    -- add more custom luasnip configuration such as filetype extend or custom snippets\n    require(\"luasnip.loaders.from_vscode\").lazy_load { paths = { \"./lua/user/snippets\" } } -- load snippets paths\n    local luasnip = require \"luasnip\"\n    luasnip.filetype_extend(\"javascript\", { \"javascriptreact\" })\nend,\n},\n</code></pre>"},{"location":"configuration/astronvim/config-design/#astronvim-community-packages","title":"AstroNvim Community packages","text":"<p> AstroNvim Community provides a large number of packages currated by the community.</p> <p>Visit the AstroNvim Community repository on GitHub and browse the packages available.</p> <p><code>import</code> each package of interest to the <code>plugins/community.lua</code> file in the AstroNvim user configuration.</p> <p>AstroNvim Community Packages in AstroNvim user configuration</p> .config/astronvim-config/plugins/community.lua<pre><code>return {\n  -- Add the community repository of plugin specifications\n  \"AstroNvim/astrocommunity\",\n  -- Import each plugin from the Astro Community as required\n  { import = \"astrocommunity.editing-support.todo-comments\" },\n  { import = \"astrocommunity.git.neogit\" },\n  { import = \"astrocommunity.git.octo\" },\n  { import = \"astrocommunity.git.openingh\" },\n}\n</code></pre> <p>AstroCommunity packs set up support for each language</p> <p>Language packs enabled in Practicalli AstroNvim Config</p> .config/astronvim-config/plugin/community.lua<pre><code>  -- Packs\n  -- Treesitter: dockerfile , Lsp: dockerls &amp; docker_compose_language_service, Lint/format: hadolint\n  { import = \"astrocommunity.pack.docker\" },\n  -- Treesitter: json &amp; jsonc, Lsp: jsonls, Lint/format: stylua\n  { import = \"astrocommunity.pack.json\" },\n  -- Treesitter: lua, Lsp: lua_ls, Lint/format: stylua\n  { import = \"astrocommunity.pack.lua\" },\n  -- Treesitter: markdown &amp; markdown_inline, Lsp: marksman, Lint/format: prettierd\n  -- Pack disabled as prettierd too agressive with format\n  -- { import = \"astrocommunity.pack.markdown\" },\n  -- Treesitter: markdown &amp; markdown_inline, Lsp: marksman, Lint/format: prettierd\n  { import = \"astrocommunity.pack.yaml\" },\n</code></pre>"},{"location":"configuration/astronvim/config-design/#themes","title":"Themes","text":"<p>Themes are a collection of one or more colorschemes to affect the apperance of text, icons, highlights, etc.</p> <p>Themes supporting <code>vim.opt.background</code> can change between dark and light colorscheme (<code>SPC u b</code> UI &gt; background in AstroNvim)</p> <p><code>SPC f t</code> selector shows themes colorschemes, as long as the themes are configured to disable lazy loading</p> <p>The default <code>astrodark</code> theme is set via the <code>colorscheme</code> option in <code>init.lua</code></p> <p>Everforest provides a good dark and light theme and supports the background option to toggle between each colorscheme.</p> <p>Practicalli AstroNvim Config - default theme</p> <pre><code>colorscheme = \"everforest\",\n</code></pre> <p> AstroCommunity themes</p> <p>Practicalli AstroNvim Config themes</p> <pre><code>return {\n{\n\"AstroNvim/astrotheme\", -- default AstroNvim theme\nlazy = false,\n},\n  -- Add the community repository of plugin specifications\n  \"AstroNvim/astrocommunity\",\n  { import = \"astrocommunity.colorscheme.everforest\" },\n  {\n    \"sainnhe/everforest\",\n    lazy = false,\n  },\n  { import = \"astrocommunity.colorscheme.nightfox-nvim\" },\n  {\n    \"EdenEast/nightfox.nvim\",\n    lazy = false,\n  },\n  { import = \"astrocommunity.colorscheme.kanagawa-nvim\" },\n  {\n    \"rebelot/kanagawa.nvim\",\n    lazy = false,\n  },\n  { import = \"astrocommunity.colorscheme.github-nvim-theme\" }, -- no background support\n  {\n    \"projekt0n/github-nvim-theme\",\n    lazy = false,\n  },\n</code></pre>"},{"location":"configuration/astronvim/config-design/#configure-lazy-plugins","title":"Configure Lazy plugins","text":"<p> Lazy.nvim Plugin specification</p>"},{"location":"configuration/astronvim/config-design/#config-format-and-lint-tools","title":"Config Format and Lint tools","text":"<p>Disable format on save when tools provide unexpected results</p> <p><code>SPC u f</code> toggles if the respective format tool should run for the current buffer.  <code>SPC u F</code> for all buffers of the current kind.</p> <p><code>init.lua</code> lsp section can enable or disable format on save for specific file types.</p> <p>Mason is responsible for installing lint and format tools</p> <p>null-ls is responsible for running each tool and provides default configuration for code_actions, completion, diagnostics, formatting and hover.</p> <p> null-ls built-in configuration</p> <p>Override config file unconsistent</p> <p>The configuration file defined by <code>-config-path</code> does not always seem to be used when running astronvim.  Quit and start Neovim again seems to use the configuration file.</p> Override null-ls builtin configuration <p>Specify configuration files to use that override the null-ls builtin configuration</p> <pre><code>return {\n  \"jose-elias-alvarez/null-ls.nvim\",\n  opts = function(_, config)\n    -- config variable is the default configuration table for the setup function call\n    local null_ls = require \"null-ls\"\n    config.sources = {\n      null_ls.builtins.formatting.markdownlint.with {\n        -- pass arguments to modify/override the null-ls builtin configuration\n        extra_args = { \n          \"--config-path\", \n          vim.fn.expand(\"~/.config/astro-config/tool-config/markdownlint.yaml\") },\n      },\n    }\n    return config -- return final config table\n  end,\n}\n</code></pre> <p><code>vim.fn.expand()</code> reports luacheck error <code>accessing undefined variable</code> but seems to work regardless</p> General configuration for LSP Servers .config/astronvim-config/init.lua<pre><code>  lsp = {\n    -- customize lsp formatting options\n    formatting = {\n      -- control auto formatting on save\n      format_on_save = {\n        enabled = true,     -- format on save globally\n        allow_filetypes = { -- format on save for specified filetypes only\n          -- \"go\",\n        },\n        ignore_filetypes = { -- turn off format on save for specified filetypes\n          -- \"python\",\n        },\n      },\n      disabled = { -- switch off formatting capabilities for the listed language servers\n        -- turn off lua_ls formatting capability if you want to use StyLua to format your lua code\n        -- \"lua_ls\",\n        \"markdownlint\",\n      },\n      timeout_ms = 1000, -- default format timeout\n      -- filter = function(client) -- fully override the default formatting function\n      --   return true\n      -- end\n    },\n    -- enable servers that you already have installed without mason\n    servers = {\n      -- \"pyright\"\n    },\n  },\n</code></pre>"},{"location":"configuration/astronvim/config-design/#override-key-binding","title":"Override Key binding","text":"<p>AstroNvim uses Lazy package manager to set keys for packages.  </p> <p>Astrocommunity configuration defines a <code>keys</code> table that is used by Lazy.</p> <p>In the user configuration, return a function that sets key bindings to overide the <code>keys</code> table provided by astrocommunity</p> Override Key bindings for vim highlighter .config/astronvim-config/plugins/community.lua<pre><code>{\n    \"vim-highlighter\",\n    keys = function() \n        return {\n            { \"&lt;leader&gt;nn\", \"&lt;cmd&gt;Hi&gt;&lt;CR&gt;\", desc = \"Next Recently Set Highlight\" },\n            { \"&lt;leader&gt;ng\", \"&lt;cmd&gt;Hi&lt;&lt;CR&gt;\", desc = \"Previous Recently Set Highlight\" },\n            { \"&lt;leader&gt;n[\", \"&lt;cmd&gt;Hi{&lt;CR&gt;\", desc = \"Next Nearest Highlight\" },\n            { \"&lt;leader&gt;n]\", \"&lt;cmd&gt;Hi}&lt;CR&gt;\", desc = \"Previous Nearest Highlight\" },\n        }\n    end,\n}\n</code></pre>"},{"location":"configuration/astronvim/config-design/#plugin-key-binding","title":"Plugin Key binding","text":"<p>Add key binding if a plugin is available wrapped in an if statement, when defining keys in a different place to adding the plugin, e.g whichkey mappings.lua</p> <pre><code>if is_available \"plugin-name\" then\n  ,,,\nelse\n</code></pre>"},{"location":"configuration/practicalli/","title":"Neovim Config Redux","text":"<p>practicalli/neovim-config-redux</p> <p>practicalli/neovim-config-redux is a Fennel based configuraion with a wide range of plugins and telescope extensions.</p> <p>Clone practicalli/neovim-config-redux or create a fork if intending to customise that configuration</p> Multiple Neovim ConfigsSingle Neovim Configs <pre><code>git clone https://github.com/practicalli/neovim-config-redux.git ~/.config/neovim-config-redux\n</code></pre> <pre><code>git clone https://github.com/practicalli/neovim-config-redux.git ~/.config/nvim\n</code></pre>"},{"location":"configuration/practicalli/#screenshots","title":"Screenshots","text":"<p>Dashboard using the startup plugin</p> <p></p> <p>Mnemonic menu with which-key</p> <p></p> <p>Telescope buffer selection</p> <p></p> <p>Neogit Git client with diffview panel</p> <p></p>"},{"location":"configuration/practicalli/config-design/","title":"Config Design","text":"<p>The overall design of the Practicalli Neovim Config Redux</p>"},{"location":"configuration/practicalli/config-design/#initlua","title":"<code>init.lua</code>","text":"<ul> <li>bootstrap the aniseed package which compiles the Fennel configuration into Lua, which is then read by Neovim. Defines the entry point to the Fennel configuration as <code>fnl/config/init.fnl</code></li> <li>installs packer.nvim for package management</li> <li>examples to disable language providers if programming language support is not required (node, perl, python3, ruby)</li> </ul>"},{"location":"configuration/practicalli/config-design/#fnlconfiginitfnl","title":"<code>fnl/config/init.fnl</code>","text":"<ul> <li>load plugin configuration namespace <code>config.plugin</code></li> <li>load <code>config.util</code> namespace to streamline key binding definitions</li> <li>set the leader key as <code>space</code> and local-leader as <code>,</code></li> <li>define key bindings - uses config.util  (mapping to be moved to their own namespace)</li> <li>set global Neovim options</li> </ul>"},{"location":"configuration/practicalli/config-design/#fnlconfigpluginfnl","title":"<code>fnl/config/plugin.fnl</code>","text":"<p>Define plugins to add functionality to Neovim.</p> <p><code>use</code> is a private function that searches the plugin configuration map for the keyword <code>:mod</code> and loads the associated namespace (namespace defined with a keyword with the same name)</p> <p>e.g. in the telescope plugin configuration <code>:mod</code> has a value of <code>:telescope</code> which will load the file <code>fnl/config/plugin/telescope.fnl</code></p> <pre><code>  :nvim-telescope/telescope.nvim\n  {:requires [:nvim-lua/popup.nvim\n              :nvim-lua/plenary.nvim]\n   :mod :telescope}\n</code></pre> <p>Packer downloads the <code>nvim-telescope/telescope.nvim</code> plugin and all the plugins in <code>:requires</code> section and search for the namespace <code>telescope</code> in file located in the following path <code>fnl/config/plugin/telescope</code></p>"},{"location":"configuration/practicalli/config-design/#fnlconfigpluginconjurefnl","title":"<code>fnl/config/plugin/conjure.fnl</code>","text":"<p>The majority of default configuration settings are used for Conjure, with the exception of a few commonly used key bindings from Emacs CIDER &amp; Spacemacs.  The Heads Up Display (HUD) is also configured to be less intrusive, relying on mostly on inline results.</p> <p>Include the conjure and aniseed namespaces</p> <pre><code>(module config.plugin.conjure\n  {autoload {nvim aniseed.nvim}})\n</code></pre> <p>Configure keybindings to be closer to Spacemacs</p> <pre><code>;; Set e register for evaluation result\n(set nvim.g.conjure#eval#result_register :e)\n\n;; Evaluate root form (top level form) under the cursor\n;; Default: `\"er\"`\n(set nvim.g.conjure#mapping#eval_root_form \"ef\")\n\n;; Evaluate root form under the cursor &amp; insert result as comment\n;; Default: `\"ecr\"`\n(set nvim.g.conjure#mapping#eval_comment_root_form \"e;\")\n\n;; Evaluate file loaded from disk\n;; Default: `\"ef\"`\n(set nvim.g.conjure#mapping#eval_file \"el\")\n</code></pre> <p>Configure the HUD to be less intrusive.</p> <pre><code>;; Width of HUD as percentage of the editor width\n;; A float between 0.0 and 1.0.\n;; Default: `0.42`\n(set nvim.g.conjure#log#hud#width 1)\n\n;; Display HUD\n;; Default: `true`\n(set nvim.g.conjure#log#hud#enabled false)\n\n;; Preferred corner position for the HUD, over-ridden by HUD cursor detection\n;; Example: Set to `\"SE\"` and HUD width to `1.0` for full width HUD at bottom of screen\n;; Default: `\"NE\"`\n(set nvim.g.conjure#log#hud#anchor \"SE\")\n\n;; Open log at bottom or far right of editor, using full width or height\n;; Default: `false`\n(set nvim.g.conjure#log#botright true)\n</code></pre> <p>Practicalli encourages header comments at the start of each file to describe the purpose of the namespace, so the Clojure ns lookup is extended</p> <pre><code>;; Number of lines to check for `ns` form, used for setting evaluation context\n;; `b:conjure#context` to override a specific buffer that isn't finding the context\n;; Default: `24`\n(set nvim.g.conjure#extract#context_header_lines 100)\n</code></pre> <p>Disable the auto-repl as practicalli prefers manage repl connections themselves</p> <pre><code>;; Start \"auto-repl\" process, eg. babashka\n;; when Conjure unable to find candidate REPL process via to an existing nREPL connection\n;; Default: `true`\n(set nvim.g.conjure#client#clojure#nrepl#connection#auto_repl#enabled false)\n\n;; Hide auto-repl buffer when triggered, to avoid the need to interact with that buffer\n;; Default: `false`\n(set nvim.g.conjure#client#clojure#nrepl#connection#auto_repl#hidden true)\n\n;; Command to start the auto-repl\n;; Default: `\"bb nrepl-server localhost:8794\"`\n(set nvim.g.conjure#client#clojure#nrepl#connection#auto_repl#cmd nil)\n\n;; Print raw evaluation result, suppressing prefix for stdout lines `; (out)`\n;; Default: `false`\n(set nvim.g.conjure#client#clojure#nrepl#eval#raw_out true)\n\n;; Automatically require namespace of new buffer or current buffer after connection\n;; Ensures buffers are loaded, required code to compile and (re)loadable.\n;; Default: `true`\n(set nvim.g.conjure#client#clojure#nrepl#eval#auto_require false)\n</code></pre> <p>Use lambdaisland/kaocha as the test runner rather, which has a fail fast feature which can be more effective when adding or changing functionality</p> <pre><code>;; Test runner called from the test key mappings\n;; Default: `\"clojure\"`\n(set nvim.g.conjure#client#clojure#nrepl#test#runner \"kaocha\")\n\n;; Print raw test evaluation result, suppressing prefix for stdout lines `; (out)`\n;; Default: `true`\n(set nvim.g.conjure#client#clojure#nrepl#test#raw_out true)\n</code></pre>"},{"location":"configuration/practicalli/config-design/#fnlconfigplugintelescopefnl","title":"<code>fnl/config/plugin/telescope.fnl</code>","text":"<p>Settings like ignore <code>node_modules</code> and everything in <code>.gitignore</code> to be listed in the file finder.</p> <p>Defines a ripgrep command to set parameters for searching files</p> <p>Add <code>--hidden</code> to see all dotfiles (regardless of .gitignore patterns)</p> <p>Keymaps:</p> <ul> <li><code>&lt;leader&gt;ff</code> open the find files</li> <li><code>&lt;leader&gt;fg</code> open the fuzzy finder</li> <li><code>&lt;leader&gt;fb</code> open the find open buffer</li> <li><code>&lt;leader&gt;fh</code> open the nvim help fuzzy finder</li> </ul>"},{"location":"configuration/practicalli/config-design/#fnlconfigplugintreesitterfnl","title":"<code>fnl/config/plugin/treesitter.fnl</code>","text":"<p>Defines which language parsers and modules to use.</p> <ul> <li>automatically use <code>clojure</code>, <code>fennel</code> and <code>markdown</code> parsers (and compile on first run of Neovim)</li> <li>automatically update language parsers when nvim-treesitter plugin updated</li> <li>enable highlight module</li> <li>enable indent module</li> </ul> <pre><code>(treesitter.setup\n  {:ensure_installed [\"clojure\" \"fennel\" \"markdown\"]\n   :sync_install true\n   :highlight {:enable true}\n   :indent    {:enable true}})\n</code></pre>"},{"location":"configuration/practicalli/config-design/#fnlconfigpluginlspconfigfnl","title":"<code>fnl/config/plugin/lspconfig.fnl</code>","text":"<p>Language Server Protocol for static analysis of code, to provide common formatting, linting and refactoring tooling across all programming languages.</p> <p>Define which symbols to show for lsp diagnostics</p> <pre><code>(defn define-signs\n  [prefix]\n  (let [error (.. prefix \"SignError\")\n        warn  (.. prefix \"SignWarn\")\n        info  (.. prefix \"SignInfo\")\n        hint  (.. prefix \"SignHint\")]\n  (vim.fn.sign_define error {:text \"\uf057\" :texthl error})\n  (vim.fn.sign_define warn  {:text \"\uf071\" :texthl warn})\n  (vim.fn.sign_define info  {:text \"\uf05a\" :texthl info})\n  (vim.fn.sign_define hint  {:text \"\uf059\" :texthl hint})))\n</code></pre> <ul> <li>features and server settings to enable/customize.</li> <li>Handler defines features and how we want to render the server outputs.</li> <li>Capabilities we link with our autocompletion plugin (nvim-cmp), to say to the lsp servers that we have this feature enabled.</li> <li>On_Attach we customize our interaction with the LSP server, here we define the following keymaps:</li> <li>configure all settings above in clojure-lsp server instance.</li> </ul>"},{"location":"configuration/practicalli/config-design/#fnlconfigplugincmpfnl","title":"<code>fnl/config/plugin/cmp.fnl</code>","text":"<p>Configure sources to show in the autocomple menu (i.e. conjure, lsp, buffer) and key bindings to navigate the autocomplete popup menu.</p>"},{"location":"configuration/practicalli/config-design/#fnlconfigpluginthemefnl","title":"<code>fnl/config/plugin/theme.fnl</code>","text":"<p>Add the Neovim GitHub theme which gives 3 dark and 3 light themes to choose from.  Individual colors and styles can be configured to change specific parts of the theme.</p> <p>The light theme is used by default, with a custom softer background colour that is slightly red-shifted.</p> <p>Options are specified in the <code>theme.setup</code> function, where the option names are keywords and the values are strings, boolean or hash-map of more option keywords and values.</p> <pre><code>(theme.setup {:theme_style \"light\"\n              :colors {:bg \"#f8f2e6\"}\n              :comment_style \"italic\"})\n</code></pre> <p>The colors (Hex values) for each theme are in the github-nvim-theme/lua/github-theme/palette with the overal theme definition in github-nvim-theme/lua/github-theme/theme.lua</p>"},{"location":"configuration/practicalli/config-design/#fnlconfigpluginsexpfnl","title":"<code>fnl/config/plugin/sexp.fnl</code>","text":"<p>Settings for vim-sexp like enabling it for another lisp languages like Fennel and Jannet</p>"},{"location":"configuration/practicalli/config-design/#fnlconfigpluginlualinefnl","title":"<code>fnl/config/plugin/lualine.fnl</code>","text":"<p>Configure the status line (lualine) that shows at the bottom of Neovim, defining colors and elements that appear on that line.</p> <p>The Neovim GitHub theme includes definitions to set the look of the status line.</p>"},{"location":"configuration/practicalli/packer/","title":"Package Manager","text":"<p>Packer is a <code>use-package</code> inspired package management for Neovim.</p> <p>Packer is used as the package manager in this guide as it is built on native Neovim packages and supports Luarocks dependencies, use the <code>:help packages</code> command in Neovim for more details.</p> <p>Packer is written in Lua and is installed via the <code>init.lua</code> configuration file, although Practicalli Neovim configuration uses Fennel to configure each package added by Packer.</p>"},{"location":"configuration/practicalli/packer/#install","title":"Install","text":"<p><code>init.lua</code> is the entry point to the configuration and is the only part that is written in Lua language.</p> <p>The configuration bootstraps the Packer package manager and installs the Aniseed compiler required to process the fennel configuration.</p> <p>Aniseed compiles and loads <code>fnl/config/init.fnl</code> and all the required namespaces in that file.</p> <p>Packer will process the <code>use</code> form in <code>fnl/config/plugin.fnl</code> and install all the packages defined in that form, along with any package specific configuration defined in that package <code>{:mod :namespace-name}</code> file.</p> <pre><code>local execute = vim.api.nvim_command\nlocal fn = vim.fn\n\nlocal pack_path = fn.stdpath(\"data\") .. \"/site/pack\"\nlocal fmt = string.format\n\nfunction ensure (user, repo)\n  -- Ensures a given github.com/USER/REPO is cloned in the pack/packer/start directory.\n  local install_path = fmt(\"%s/packer/start/%s\", pack_path, repo, repo)\n  if fn.empty(fn.glob(install_path)) &gt; 0 then\n    execute(fmt(\"!git clone https://github.com/%s/%s %s\", user, repo, install_path))\n    execute(fmt(\"packadd %s\", repo))\n  end\nend\n\n-- Bootstrap essential plugins required for installing and loading the rest.\nensure(\"wbthomason\", \"packer.nvim\")\nensure(\"Olical\", \"aniseed\")\n\n-- Enable Aniseed's automatic compilation and loading of Fennel source code.\nvim.g[\"aniseed#env\"] = {\n  module = \"config.init\",\n  compile = true\n}\n</code></pre>"},{"location":"configuration/practicalli/packer/#packages","title":"Packages","text":"<p>Neovim packages add extra functionality to Neovim, e.g. conjure package provides an excellent Clojure REPL experience (and supports several other languages too).</p> <p>See the packages section for details of the packages used and a breakdown of their configuration.</p>"},{"location":"configuration/practicalli/packages/","title":"Add Neovim Packages","text":"<p>Evolving Packages in Practicalli config</p> <p>Check the practicalli/neovim-config-reduct configuration. Many packages have been added to the configuration and <code>fnl/config/package.fnl</code> is the most up to date list of packages currently used.</p> <p>List of packages and their purpose</p> Package Description conjure Clojure REPL Driven Development (and other language REPLs) sexp Structured Editing newpaper theme Clean and simple UI &amp; colour scheme, aimed at readably lualine Fast and configurable statusline nvim-treesitter Parse code highly efficiently, client for LSP servers telescope Completion tool, e.g. select files, buffers tabs, packages, etc nvim-tree Visual file manager - open, create, delete, etc. files &amp; directories neogit Magit style visual Git client Octo Git Issues and Pull Requests gitsigns Show diff changes in buffer gutter and status line <p>Any specific package configuration &amp; key bindings (on sub page if significant content)</p>"},{"location":"configuration/practicalli/packages/#package-selection-criteria","title":"Package selection criteria","text":"<p>Packages are more likely to be adopted if:</p> <ul> <li>provide valuable (or fun) features</li> <li>work reliably, without generating errors</li> <li>do not conflict with other valuable packages in this configuration</li> <li>written in fennel or lua to aid maintenance</li> <li>provides a <code>setup</code> or <code>config</code> function for setting package options</li> <li>use features provided by Neovim (e.g treesitter)</li> <li>are well documented</li> <li>are easy to configure</li> <li>are easy to use</li> <li>work well with themes (where relevant)</li> </ul>"},{"location":"configuration/practicalli/packages/#package-updates","title":"Package Updates","text":"<p>This Week In Neovim - community update</p>"},{"location":"configuration/practicalli/packages/lualine/","title":"Lualine - modeline theme","text":"<p>nvim-lualine/lualine.nvim is a fast and configurable statusline for neovim</p> <p>Example status line: evil_lualine</p> <p></p>"},{"location":"configuration/practicalli/packages/lualine/#lualine-configuration-in-fennel","title":"Lualine configuration in Fennel","text":"<p><code>nvim/fnl/config/plugin/lualine.fnl</code></p> <pre><code>(module config.plugin.lualine\n  {autoload {core aniseed.core\n             lualine lualine\n             lsp config.plugin.lspconfig}})\n\n(defn lsp_connection []\n  (if (vim.tbl_isempty (vim.lsp.buf_get_clients 0)) \"\uf096\" \"\uf0c8\"))\n\n(def github-lua-theme\n  (core.assoc\n    (require :lualine.themes.auto)\n    :inactive {:a {:bg \"#19181e\" :fg \"#a4a3a6\"}\n               :b {:bg \"#19181e\" :fg \"#a4a3a6\"}\n               :c {:bg \"#19181e\" :fg \"#a4a3a6\"}}\n    :normal {:a {:bg \"#131217\" :fg \"#24292e\"}\n             :b {:bg \"#131217\" :fg \"#3b8eea\"}\n             :c {:bg \"#19181e\" :fg \"#d1d5da\"}}\n    :command {:a {:bg \"#131217\" :fg \"#24292e\"}\n              :b {:bg \"#131217\" :fg \"#ccbed8\"}\n              :c {:bg \"#19181e\" :fg \"#d1d5da\"}}\n    :visual {:a {:bg \"#131217\" :fg \"#24292e\"}\n             :b {:bg \"#131217\" :fg \"#ced4b1\"}\n             :c {:bg \"#19181e\" :fg \"#d1d5da\"}}\n    :replace {:a {:bg \"#131217\" :fg \"#24292e\"}\n              :b {:bg \"#131217\" :fg \"#d1b6bd\"}\n              :c {:bg \"#19181e\" :fg \"#d1d5da\"}}\n    :insert {:a {:bg \"#131217\" :fg \"#24292e\"}\n             :b {:bg \"#131217\" :fg \"#a8d1c9\"}\n             :c {:bg \"#19181e\" :fg \"#d1d5da\"}}))\n\n(lualine.setup\n  {:options {:theme github-lua-theme\n             :icons_enabled true\n             :section_separators [\"\" \"\"]\n             :component_separators [\"\uf44a\" \"\uf438\"]}\n   :sections {:lualine_a []\n              :lualine_b [[:mode {:upper true}]]\n              :lualine_c [[\"FugitiveHead\"]\n                          [:filename {:filestatus true\n                                      :path 1}]]\n              :lualine_x [[:diagnostics {:sections [:error\n                                                    :warn\n                                                    :info\n                                                    :hint]\n                                         :sources [:nvim_lsp]}]\n                          [lsp_connection]\n                          :location\n                          :filetype]\n              :lualine_y [:encoding]\n              :lualine_z []}\n   :inactive_sections {:lualine_a []\n                       :lualine_b []\n                       :lualine_c [[:filename {:filestatus true\n                                               :path 1}]]\n                       :lualine_x []\n                       :lualine_y []\n                       :lualine_z []}})\n</code></pre>"},{"location":"configuration/practicalli/packages/nvim-treesitter/","title":"Nvim Treesitter","text":"<p>Treesitter provides language specific parsing, highlight and indent features and so is a fundamental plugin to use with Neovim.</p> <p><code>clojure</code>, <code>fennel</code>, <code>markdown</code> and <code>org</code> parsers are automatically installed in the practicalli/neovim-config-redux configuration.</p> <ul> <li><code>:TSInstallInfo</code> lists language parsers and install status</li> <li><code>:TSUpdate {language}</code> to update a parser to the latest compatible version (specified in nvim-treesitter lockfile.json).</li> <li><code>:TSInstall {language}</code> compiles and installs a parser for the given language.</li> <li><code>:TSUpdateSync</code> to update all parsers to the latest available versions</li> </ul>"},{"location":"configuration/practicalli/packages/nvim-treesitter/#nvim-treesitter-configuration","title":"nvim-treesitter configuration","text":"<p><code>clojure</code>, <code>fennel</code>, <code>markdown</code> and <code>org</code> parsers are automatically installed if not already available.</p> <p><code>:sync_install true</code> automatically updates the parsers when the nvim-treesitter plugin is updated.  Treesitter and its parsers are actively developed, so its important to ensure parsers are kept up to date.  This is the equivalent of manually running <code>:TSUpdateSync</code>.</p> <p>Parser highlight and indent modules are enabled by default</p> <p>In <code>fnl/config/plugin/treesitter.fnl</code></p> <pre><code>(module config.plugin.treesitter\n  {autoload {treesitter nvim-treesitter.configs}})\n\n(treesitter.setup\n  {:ensure_installed [\"clojure\" \"fennel\" \"markdown\" \"org\"]\n   :sync_install true\n   :highlight {:enable true}\n   :indent    {:enable true}})\n</code></pre>"},{"location":"configuration/practicalli/packages/nvim-treesitter/#manually-install-parsers","title":"Manually Install Parsers","text":"<p>nvim-treesitter provides the <code>TSInstall</code> command to generate a parser for a specific language, assuming that language is supported.</p> <p>A compiler (gcc, clang, etc) should be installed in the operating system on which nvim is running</p> <pre><code>:TSInstall {language}\n</code></pre> <p><code>TAB</code> completion lists the available language parsers, <code>TAB</code> and <code>S-TAB</code> to navigate the auto-completion popup.</p>"},{"location":"install/","title":"Install Overview","text":"<p>Practicalli Neovim provides a feature rich configuration for Neovim and all the tools required for effective Clojure development (and other Lisp dialects too).</p> <ul> <li>Clojure tooling and a Java SDK (Java Virtual Machine)</li> <li>Neovim 0.9.x or nightly build</li> <li>Neovim package manager and packages</li> <li>NerdFonts for icon support in themes and status line</li> <li>Optional: Neovide GUI for neovim</li> </ul> <p>Neovim 0.9.x latest stable release</p> <p>Content and configuration in this book has been tested against Neovim 0.9.x over the summer of 2023</p>"},{"location":"install/#install-summary","title":"Install summary","text":"<p>If you are familiar with most of the tools required, then the quick start list below provides an ultra-terse version on how to get started with Neovim and Clojure development.</p> <ul> <li>Install Neovim 0.9.x or greater<ul> <li>Linux AppImage</li> <li><code>brew install --HEAD neovim</code> for Homebrew install of development version</li> </ul> </li> <li>Install supporting tools<ul> <li><code>tar</code> &amp; <code>curl</code> and a C compiler, e.g. <code>gcc</code> for Linux or <code>clang</code> for android/termix (required by nvim-treesitter)</li> <li><code>ripgrep</code> &amp; <code>fd</code> to search for files (used by telescope)</li> <li><code>luarocks</code> for LSP support in AstroNvim</li> </ul> </li> <li>Optionally add a community configuration, e.g. AstroNvim or Practicalli Neovim Config</li> <li>Run <code>nvim</code> in a terminal </li> <li>Install Clojure CLI and supporting tools</li> <li>Clone / fork practicalli/clojure-deps-edn or add an alias with the required config to use nrepl and cider-nrepl</li> <li>Run a Clojure REPL process - in a terminal session with nREPL, e.g. using one of the REPL aliases from practicalli/clojure-cli-config<ul> <li><code>clojure -M:repl/rebel</code> for a rich REPL UI with auto-completion &amp; docs</li> <li><code>clojure -M:repl/headless</code> - headless REPL process when working exclusively in a Clojure connected editor . Open a Clojure file in Neovim - Conjure will automatically connect</li> </ul> </li> </ul>"},{"location":"install/#next-steps","title":"Next Steps","text":"<p>Learn how to use Neovim and how to use Conjure for REPL driven development</p>"},{"location":"install/clojure/","title":"Install Clojure","text":"<p>A rich Clojure REPL workflow is provided by the Conjure package, which works with Clojure CLI and Leiningen projects, assuming the respective tool is installed.</p> <p>Clojure LSP is highly recommended and packages to use an installed clojure-lsp tool are in the practicalli/neovim-config-redux configuration</p>"},{"location":"install/clojure/#clojure-cli","title":"Clojure CLI","text":"<p> Practicalli Clojure install guide</p> <p> Clojure CLI provides a way to run Clojure code, packaged Clojure (jar) and run a Clojure REPL.</p> <p> Practicalli Clojure install guide details prerequisites, Clojure install options and supporting tools for an enhanced developer workflow.</p> <p>Visit the  Clojure Getting Started guide for the Clojure CLI or to check the latest release version.</p> <p> Practicalli Clojure CLI Config provides a wide range of community tools that extend the features of Clojure CLI, creating a rich development environment for use across all projects.</p> <p>Aliases are required for many examples</p> <p>Without  Practicalli Clojure CLI Config many commands provided in this book are not available unless similar alias definitions are added to a either a project or user level <code>deps.edn</code> configuration.</p>"},{"location":"install/clojure/#language-server-protocol","title":"Language Server Protocol","text":"<p>Neovim Treesitter surfaces information from Language Server Protocol (LSP) servers to assist with development and refactor of Clojure code.</p> <p> Clojure LSP installation guide shows how to install the Clojure LSP binary for the relevant operating system.</p> <p>Once installed, run <code>clojure-lsp -v</code> in a terminal to ensure the command is working.</p> <p>practicalli/clojure-lsp-config</p> <p> practicalli/clojure-lsp-config provides a complete configuration for clojure-lsp (<code>config.edn</code>), including a wide range of snippets and less restrictive formatting rules (<code>cljfmt.edn</code>)</p> <p>clj-kondo provides static analysis of source code files, providing subtle warnings as Clojure code is written to help the developer follow idioms and avoid syntatic errors.</p> <p>Clojure LSP includes clj-kondo to provide  an implementation of the Language Server Protocol for the Clojure Language.</p> <p> Clojure LSP installation guide  Treesitter Fennel Configuration</p>"},{"location":"install/clojure/#leiningen","title":"Leiningen","text":"<p>Many existing Clojure projects use Leiningen build automation tool (although many new projects use Clojure CLI as well or instead of Leiningen).  </p> <p>The code is the same regardless of tooling choice.  The overall workflow is the same, although Clojure CLI may provide more workflow options.</p> <p>Follow the install instructions at Leiningen.org if required.</p>"},{"location":"install/neovim/","title":"Install Neovim","text":"<p>Neovim releases</p> <p>Neovim 8 is the minimum version for this configuration and Neovim 0.9.0 is currently being tested.</p> <p>Follow the install Neovim guide for the specific operating system.</p>"},{"location":"install/neovim/#suppoting-tools","title":"Suppoting Tools","text":"<p>Neovim uses several external tools for searching for files, search file contents and using the operating system clipbaord.</p> <p>AstroNvim requires node.js</p> <p>AstroNvim uses Mason to install LSP servers, format and lint tools.  Many LSP servers require node.js to install and function.</p> <p>Node.js install - Practicalli Engineering Playbook </p> Debian / Ubuntu <p>Install the following packages to support Neovim</p> <ul> <li><code>ripgrep</code> fast file contents search (used by telescope)</li> <li><code>find-fd</code> advanced search tool</li> <li><code>xclip</code> clipboard as a provider tools for Neovim copy/paste</li> <li><code>luarocks</code> for LSP servers (AstroNvim)</li> </ul> <pre><code>sudo apt install find-fd xclip luarocks\n</code></pre> <p>Add <code>set clipboard+=unnamedplus</code> to the Neovim configuration to use the Linux clipboard tool</p> Wayland requires wl-clipboard <p>Install the <code>wl-clipboard</code> package to use the Wayland desktop clipboard with Neovim <pre><code>sudo apt install wl-clipboard\n</code></pre></p>"},{"location":"install/neovim/#install-neovim_1","title":"Install Neovim","text":"Linux AppImageUbuntu/DebianBuild from Source <p>Download the AppImage from the Neovim Release page and place the file on the executable path, e.g. <code>$HOME/.local/bin</code></p> <p>Make the AppImage executable</p> <pre><code>chmod u+x nvim.appimage\n</code></pre> <p>Run neovim from the AppImage</p> <pre><code>nvim.appimage\n</code></pre> <p>Create a symbolic link called <code>nvim</code> to the nvim.appimage</p> <pre><code>ln -s $HOME/.local/bin/nvim.appimage $HOME/.local/bin/nvim\n</code></pre> <p>Download the Linux AppImage from the Neovim Releases page</p> <p>Or build Neovim from source and generate a <code>.deb</code> file from the build.</p> Linux version only packaged as AppImage from Neovim 0.9 onward <p>Neovim Build Prerequisites for each operating system</p> Ubuntu/Debian Packages <p>Install packages to support building Neovim <pre><code>sudo apt-get install ninja-build gettext cmake unzip curl\n</code></pre></p> <p>Clone the Neovim GitHub repository</p> <p><pre><code>git clone --origin neovim https://github.com/neovim/neovim.git\n</code></pre> Change into the cloned directory and change to the <code>stable</code> release to build version 0.9.0</p> <pre><code>git checkout stable\n</code></pre> <p>Build a release</p> <pre><code>make CMAKE_BUILD_TYPE=Release                                                                                                              \u2500\u256f\n</code></pre> <p>Once the nvim release has been built, create a debian package for use with Ubuntu and Debian systems</p> <pre><code>cpack -G DEB\n</code></pre>"},{"location":"install/neovim/#post-install-checks","title":"Post Install checks","text":"<p>Ensure supporting tools and binaries are available in the operating system by running the Neovim Heath Check.</p> <p><code>nvim</code> in a terminal to run NeoVim and check the installation is working without error.</p> <p></p> <p><code>:checkhealth</code> to run a check supporting tools are available to NeoVim.</p> <p>A report is generated and shown in NeoVim</p> <p><code>j</code> / <code>k</code> to scroll through the checkhealth report</p> <p>Review the warnings and install tooling that is required for languages that will be used.</p> <p></p> <p>Ignore Provider Warnings</p> <p>It is safe to ignore language provider warnings.</p> <p>Language Providers can be disabled in the Neovim configuration to remove the warnings from <code>:checkhealth</code> report.  Examples of disabling language provders are in the practicalli/neovim-config-redux configuration, covered in the Neovim Config install step</p>"},{"location":"introduction/community-projects/","title":"Community Configuration Projects","text":"<p>Practicalli Neovim book covers the following configurations:</p>"},{"location":"introduction/community-projects/#practicalli-neovim-config-redux","title":"Practicalli Neovim Config Redux","text":"<p> Practicalli Neovim Config Redux</p> <ul> <li>Fennel configuration</li> <li>Packer package manager &amp; Treesitter support</li> <li>Mnemonic key bindings</li> <li>Telescope selectors</li> <li>Autocompletion (cmp) &amp; snippets (luasnip)</li> <li>Esc with center row keys, e.g. \"fd\"</li> </ul>"},{"location":"introduction/community-projects/#astronvim-and-practicalli-astronvim-config","title":"AstroNvim and Practicalli AstroNvim Config","text":"<p> AstroNvim and Practicalli AstroNvim Config organised configuration with a polished UI</p> <ul> <li>Neovim 9 support</li> <li>Lazy for plugins (packages for Neovim)</li> <li>Mason to manage install for LSP, DAP, lint and format tools</li> <li>Treesitter and language parser support</li> <li>Telescope selectors</li> <li>Notification dialogs</li> <li>Autocompletion (cmp) &amp; snippets (luasnip)</li> <li>Neovim 9 background switch (live toggle light &amp; dark theme)</li> <li>Hidden command line <code>cmdheight=0</code> (Neovim 0.8 onward)</li> <li>Esc with center row keys, e.g. \"fd\" (user: <code>plugins/core.lua</code>)</li> </ul>"},{"location":"introduction/community-projects/#alternative-configurations","title":"Alternative configurations","text":"<p>Practicalli Neovim does not cover the following Community configurations.</p> <ul> <li>Magit Kit fennel configuration from the author of Conjure</li> <li>cajus-nvim inspiration for practicalli/neovim-config-redux</li> <li>LazyVim lazy &amp; mason configuration</li> <li>NvChad polished UI with Lazy optomisations</li> </ul> <p>Long term project: Fennel config with AstroNvim-like UI experience</p> <p>A very long term goal for Practicalli is to create a Neovim configuration written predominatly in Fennel, providing a rich user experience on par with the very polished experience of AstroNvim.</p> <p>Lazy and Mason should be used to manage packages and tools (LSP &amp; DAP servers, lint &amp; format tools).</p> <p>Which-key should provide a mnemonic menu system similar to the Spacemacs experience.</p>"},{"location":"introduction/contributing/","title":"Contributing to Practicalli","text":"<p>Practicalli books are written in markdown and use MkDocs to generate the published website via a GitHub workflow.  MkDocs can also run a local server using the <code>make docs</code> target from the <code>Makefile</code></p> <p>By submitting content ideas and corrections you are agreeing they can be used in this book under the Creative Commons Attribution ShareAlike 4.0 International license.  Attribution will be detailed via GitHub contributors.</p> <p>All content and interaction with any persons or systems must be done so with respect and within the Practicalli Code of Conduct.</p>"},{"location":"introduction/contributing/#book-status","title":"Book status","text":""},{"location":"introduction/contributing/#submit-and-issue-or-idea","title":"Submit and issue or idea","text":"<p>If something doesnt seem quite right or something is missing from the book, please raise an issue via the GitHub repository explaining in as much detail as you can.</p> <p>Raising an issue before creating a pull request will save you and the maintainer time.</p>"},{"location":"introduction/contributing/#considering-a-pull-request","title":"Considering a Pull request?","text":"<p>Before investing any time in a pull request, please raise an issue explaining the situation.  This can save you and the maintainer time and avoid rejected pull requests.</p> <p>Please keep pull requests small and focused, as they are much quicker to review and easier to accept.  Ideally PR's should be for a specific page or at most a section.</p> <p>A PR with a list of changes across different sections will not be merged, it will be reviewed eventually though.</p>"},{"location":"introduction/contributing/#thank-you-to-everyone-that-has-contributed","title":"Thank you to everyone that has contributed","text":"<p>A huge thank you to Rich Hickey and the team at Cognitect for creating and continually guiding the Clojure language.  Special thank you to Alex Miller who has provided excellent advice on working with Clojure and the CLI tooling.</p> <p>The Clojure community has been highly supportive of everyone using Clojure and I'd like to thank everyone for the feedback and contributions.  I would also like to thank everyone that has joined in with the London Clojurins community, ClojureBridgeLondon, Clojurians Slack community, Clojurians Zulip community and Clojureverse community.</p> <p>Thank you to everyone who sponsors the Practicalli websites and videos and for the Clojurists Together sponsorship, it helps me continue the work at a much faster pace.</p> <p>Special thanks to Bruce Durling for getting me into Cloure in the first place.</p> <p></p>"},{"location":"introduction/features/","title":"Neovim features","text":"<p>A clean UI provides for a distraction free development experience, with only the essential information presented in the Neovim statusline or inline with the code</p> <ul> <li>Conjure - automatic Clojure REPL connection, evaluation, test runners</li> <li>Treesitter</li> <li>Plug-in Manager (e.g. Lazy.nvim) </li> <li>LSP - auto-completion, snippets, inline linting, reference navigation, refactor and unit test coverage</li> <li>statusline - LSP status, diff changes, filetype, cursor position</li> <li>Selection narrowing completion of files, packages, colour schemes, etc</li> <li>File browser - telescope selection narrowing and visual file system navigation</li> <li>Version Control gutter indicators for changed lines</li> <li>todo comments todo, fix, notes, indicators with gutter icons</li> <li>relative line numbers for vim-style navigation</li> </ul>"},{"location":"introduction/features/#conjure","title":"Conjure","text":"<p> Conjure An interactive environment for evaluating code, e.g. a Clojure REPL.  Conjure automatically connects to an nREPL process running in the current project.</p> <p>Evaluate Clojure code as its developed for an instant feedback workflow.</p> <p>Run unit tests with Kaocha test runner (Cognitect Labs and ClojureScript runners also available)</p> <p>Fireplace has been a long-standing plugin for Vim to support Clojure REPL connection.</p>"},{"location":"introduction/features/#lazy-plugin-manager","title":"Lazy Plugin manager","text":"<p>Lazy.nvim manages neovim plugins with a rich UI that provides an enjoyable user experience.  Plugins are automatically installed during startup and lists the status of each plugins. </p> <p>Plugins are automatic cached &amp; bytecode compiled and can be lazy loaded to streamline startup time and resource usage based on events, commands, filetypes, and key mappings.  Efficient plugin downlaods using partial blobless clones of plugin repositories, i.e. <code>--filter=blob:none</code></p> <p></p> <p> Lazy.nvim</p>"},{"location":"introduction/features/#treesitter","title":"Treesitter","text":"<p>Neovim provides highly effective syntax highlighting of source code due to Treesitter.</p> <p>Tree-sitter parses files opened in Neovim and builds a concrete syntax tree that any Neovim plugin can use to efficiently provide feedback. Treesitter uses incremental parsing to efficiently update the syntax tree as a file is edited. </p> <ul> <li>parse on every keystroke in a text editor</li> <li>provide useful results even in the presence of syntax errors</li> </ul> <p> Treesitter </p>"},{"location":"introduction/features/#language-server-protocol","title":"Language Server Protocol","text":"<p>Neovim includes an LSP client which uses the information recieved from a language specific LSP server in real-time to provide a range of services:</p> <ul> <li>auto-completion of function and symbol names</li> <li>live linting as code is typed or opened from a file</li> <li>formatting</li> <li>function signatures and help documentation</li> <li>diagnostics (syntax errors &amp; idioms)</li> <li>symantic analysis providing rename through project, go-to-definition &amp; find-references</li> </ul> <p>LSP feedback is often presented in the buffer, file browser and status line of Neovim.</p> <p>LSP Server implementation is not universal</p> <p>LSP is a relatively new specification and many server implmentations are still evolving or are yet to be created.</p> <p>Lint tools tend to be more prevelent and may be required in concert with or in the absence of an LSP server.</p> LSP related Plugins <ul> <li>neovim/nvim-lspconfig - connect Neovim lsp client to lsp servers</li> <li>jose-elias-alvarez/null-ls.nvim - hook format and lint tools into the Neovim LSP client</li> <li>jayp0521/mason-null-ls.nvim - automatically install formatters/linters to be used by null-ls</li> <li>williamboman/mason - install and manage LSP servers, DAP servers, linters, and formatters</li> <li>williamboman/mason-lspconfig - register LSP configs with neovim so LSP client can connect to  servers</li> </ul>"},{"location":"introduction/features/#lint-and-format-tools","title":"Lint and format tools:","text":"<p>Linters check code for common problems and provide hints on how to correct any detected issues.</p> <p>Format tools suppor code to conforming to a specified coding style, typically these run when save-file is run.</p> <p>null-ls provides extensive builtin configuration for programming languages and configuration formats.  null-ls also passes lint and format tool information to the Neovim LSP client, extending the range of language support.</p>"},{"location":"introduction/features/#selection-narrowing","title":"Selection Narrowing","text":"<p> telescope.nvim is a highly extendable fuzzy finder over lists with community driven pickers, sorters and previewers.</p> <p>Navigate and narrow lists of files, packages, environment variables, ports, colour schemes (themes) and any other list of items effectively. </p> <p>Telescope File browser popup also explores the file system and in Normal mode can be used to create files and directories</p> <p>The telescope list narrows matches as characters are typed</p>"},{"location":"introduction/features/#version-control","title":"Version Control","text":"<p>Gitsigns hightlights buffer changes in the gutter</p> <p>Lualine shows number of Git changes in status line</p> <p>Diffview to review all changes for any git revision</p> <p>Neogit provides a rich git client to add, stash, commit, push &amp; pull changes.</p> <p>Octo provides a GitHub specific client to manage issues and pull requests, using GitHub CLI authentication.</p> <p>LazyGit UI</p>"},{"location":"introduction/features/#file-browser","title":"File Browser","text":"<p>neo-tree provides a visual file system explorer that can also create and delete files and directories</p>"},{"location":"introduction/features/#todo-comments","title":"TODO Comments","text":"<p>Highlight tasks, fixes, notes and dragons comments, including icons in the gutter.  Use Telescope to navigate TODO comments in the current project.</p>"},{"location":"introduction/features/#status-line","title":"Status Line","text":"<p>LSP feedback</p>"},{"location":"introduction/features/#markdown","title":"Markdown","text":"<ul> <li>LSP server</li> <li>Marksman: select anchors and pages for links</li> </ul>"},{"location":"introduction/fennel/","title":"Fennel","text":"<p>Lua is the defacto language for Neovim plugin development and configuration.</p> <p>Fennel can be used to write Neovim packages and configuration, using  nfnl to generate the equivalent Lua code that Neovim runs.</p> <p>Although Neovim fully supports Vimscript, Practicalli encourages Fennel or Lua, as Vimscript is a niche language with quite complex syntax.</p>"},{"location":"introduction/fennel/#overview","title":"Overview","text":"<p> Fennel is a programming language that brings together the speed, simplicity, and reach of  Lua with the flexibility of a  lisp syntax and macro system.</p> <ul> <li>Full Lua compatibility: Easily call any Lua function or library from Fennel and vice-versa.</li> <li>Zero overhead: Compiled code should be just as efficient as hand-written Lua.</li> <li>Compile-time macros: Ship compiled code with no runtime dependency on Fennel.</li> <li>Embeddable: Fennel is a one-file library as well as an executable. Embed it in other programs to support runtime extensibility and interactive development.</li> </ul> <p>Anywhere you can run Lua code, you can run Fennel code.</p> <p>Translate Lua to Fennel</p> <p> See Fennel is an online antifennel tool to convert Lua to Fennel or Fennel to Lua.</p> <p>practicalli/neovim-config-redux configuration provides helper functions to minimise the translation required.</p>"},{"location":"introduction/fennel/#fennel-packages","title":"Fennel Packages","text":"<p>The Conjure package which provides the Clojure REPL (and much more) is written in Fennel.</p>"},{"location":"introduction/fennel/#nfnl","title":"nfnl","text":"<p> nfnl generates Lua code from Fennel code.  Neovim runs the generated Lua code.</p> <p>nfnl loads only when working in directories containing a <code>.nfnl.fnl</code> configuration file, so has zero overhead when not working with fennel.</p> <p><code>*.fnl</code> files are automatically compiled to <code>*.lua</code> when changes are saved, showing any compilation errors to provide an effective feedback loop.</p> <p>nfnl standard library</p> <p>nfnl plugin example</p>"},{"location":"introduction/fennel/#development-tooling","title":"Development tooling","text":"<p>Neovim support</p> <ul> <li>Anti-fennel - convert from Lua code to Fennel code.</li> <li>nfnl - write plugins or configuration for Neovim with great runtime performance</li> <li>hotpot - seamless Fennel inside Neovim</li> </ul> <p> See Fennel is an online antifennel tool to convert between Lua and Fennel.</p> <p> Guide to plugin development with fennel</p> <p>Emacs support:</p> <ul> <li> technomancy/fennel-mode and Emacs mirror repository</li> </ul>"},{"location":"introduction/fennel/#playing-games","title":"Playing Games","text":"<p> TIC-80 is a simulated computer environment to to write code, design art, compose music and retro style game games.</p> <p> L\u00d6VE is a framework for making games with the Lua programming language, allows import from external resources and can use any resolution or memory resources required.</p> <p>TIC-80 and L\u00d6VE provide cross-platform support across Windows, Mac and Linux systems. TIC-80 games can also be played in the browser.</p>"},{"location":"introduction/repl-workflow/","title":"REPL Driven Development","text":"<p>Always be REPL'ing</p> <p>Coding without a REPL feels limiting. The REPL provides fast feedback from code as its crafted, testing assumptions and design choices every step of the journey to a solution  - John Stevenson, Practical.li</p> <p>Clojure is a powerful, fun and highly productive language for developing applications and services.  The clear language design is supported by a powerful development environment known as the REPL (read, evaluate, print, loop).  The REPL gives you instant feedback on what your code does and enables you to test either a single expression or run the whole application (including tests).</p> <p>REPL driven development is the foundation of working with Clojure effectively</p> <p>An effective Clojure workflow begins by running a REPL process.  Clojure expressions are written and evaluated immediately to provide instant feedback. The REPL feedback helps test the assumptions that are driving the design choices.</p> <ul> <li>Read - code is read by the Clojure reader, passing any macros to the macro reader which converts those macros into Clojure code.</li> <li>Evaluate - code is compiled into the host language (e.g. Java bytecode) and executed</li> <li>Print - results of the code are displayed, either in the REPL or as part of the application.</li> <li>Loop - the REPL is a continuous process that evaluates code, either a single expression or the whole application.</li> </ul> <p>Design decisions and valuable data from REPL experiments can be codified as specifications and unit tests</p> <p>Practicalli REPL Reloaded Workflow</p> <p>The principles of REPL driven development are implemented in practice using the Practicalli REPL Reloaded Workflow and supporting tooling.  This workflow uses Portal to inspect all evaluation results and log events, hot-load libraries into the running REPL process and reloads namespaces to support major refactor changes.</p>"},{"location":"introduction/repl-workflow/#evaluating-source-code","title":"Evaluating source code","text":"<p>A REPL connected editor is the primary tool for evaluating Clojure code from source code files, displaying the results inline.</p> <p>Source code is automatically evaluated in its respective namespace, removing the need to change namespaces in the REPL with (<code>in-ns</code>) or use fully qualified names to call functions.</p> <p>Evaluate Clojure in Neovim with Conjure</p> <p><code>, e b</code> evaluates the code in the current buffer</p> <p> </p> Evaluate Clojure in a Terminal UI REPL <p>Entering expressions at the REPL prompt evaluates the expression immediately, returning the result directly underneath  </p>"},{"location":"introduction/repl-workflow/#rich-comment-blocks-living-documentation","title":"Rich Comment blocks - living documentation","text":"<p>The <code>(comment ,,,)</code> function wraps code that is only run directly by the developer using a Clojure aware editor.</p> <p>Expressions in rich comment blocks can represent how to use the functions that make up the namespace API.  For example, starting/restarting the system, updating the database, etc.  Expressions provide examples of calling functions with typical arguments and make a project more accessible and easier to work with.</p> <p>Clojure Rich Comment to manage a service</p> <pre><code>(ns practicalli.gameboard.service)\n\n(defn app-server-start [port] ,,,)\n(defn app-server-start [] ,,,)\n(defn app-server-restart [] ,,,)\n\n(defn -main\n  \"Start the service using system components\"\n  [&amp; options] ,,,)\n\n(comment\n  (-main)\n  (app-server-start 8888)\n  (app-server-stop)\n  (app-server-restart 8888)\n\n  (System/getenv \"PORT\")\n  (def environment (System/getenv))\n  (def system-properties (System/getProperties))\n  ) ; End of rich comment block\n</code></pre> <p>Rich comment blocks are very useful for rapidly iterating over different design decisions by including the same function but with different implementations.  Hide clj-kondo linter warnings for redefined vars (<code>def</code>, <code>defn</code>) when using this approach.</p> <pre><code>;; Rich comment block with redefined vars ignored\n#_{:clj-kondo/ignore [:redefined-var]}\n(comment\n  (defn value-added-tax []\n    ;; algorithm design - first idea)\n\n  (defn value-added-tax []\n    ;; algorithm design - second idea)\n\n  ) ;; End of rich comment block\n</code></pre> <p>The \"Rich\" in the name is an honourary mention to Rich Hickey, the author and benevolent dictator of Clojure design.</p>"},{"location":"introduction/repl-workflow/#design-journal","title":"Design Journal","text":"<p>A journal of design decisions makes the code easier to understand and maintain.  Code examples of design decisions and alternative design discussions are captured, reducing the time spent revisiting those discussions.</p> <p>Journals simplify the developer on-boarding processes as the journey through design decisions are already documented.</p> <p>A Design Journal is usually created in a separate namespace, although it may start as a rich comment at the bottom of a namespace.</p> <p>A journal should cover the following aspects</p> <ul> <li>Relevant expressions use to test assumptions about design options.</li> <li>Examples of design choices not taken and discussions why (saves repeating the same design discussions)</li> <li>Expressions that can be evaluated to explain how a function or parts of a function work</li> </ul> <p>The design journal can be used to create meaningful documentation for the project very easily and should prevent time spent on repeating the same conversations.</p> <p>Example design journal</p> <p>Design journal for TicTacToe game using Reagent, ClojureScript and Scalable Vector Graphics</p>"},{"location":"introduction/repl-workflow/#viewing-data-structures","title":"Viewing data structures","text":"<p>Pretty print shows the structure of results from function calls in a human-friendly form, making it easier for a developer to parse and more likely to notice incorrect results.</p> <p>Tools to view and navigate code</p> <ul> <li> Cider inspector is an effective way to navigate nested data and page through large data sets.</li> <li> Portal Inspector to visualise many kinds of data in many different forms.</li> </ul> <p></p>"},{"location":"introduction/repl-workflow/#code-style-and-idiomatic-clojure","title":"Code Style and idiomatic Clojure","text":"<p>Clojure aware editors should automatically apply formatting that follows the  Clojure Style guide.</p> <p>Live linting with clj-kondo suggests common idioms and highlights a wide range of syntax errors as code is written, minimizing bugs and therefore speeding up the development process.</p> <p> </p> <p>Clojure LSP is build on top of clj-kondo</p> <p> Clojure LSP uses clj-kondo static analysis to provide a standard set of development tools (format, refactor, auto-complete, syntax highlighting, syntax &amp; idiom warnings, code navigation, etc).</p> <p>Clojure LSP can be used with any Clojure aware editor that provides an LSP client, e.g.  Spacemacs,  Doom Emacs,  Neovim, VSCode.</p> <p>Clojure Style Guide</p> <p>The  Clojure Style guide provides examples of common formatting approaches, although the development team should decide which of these to adopt.  Emacs <code>clojure-mode</code> will automatically format code and so will Clojure LSP (via cljfmt).  These tools are configurable and should be tailored to the teams standard.</p>"},{"location":"introduction/repl-workflow/#data-and-function-specifications","title":"Data and Function specifications","text":"<p> Clojure spec is used to define a contract on incoming and outgoing data, to ensure it is of the correct form.</p> <p>As data structures are identified in REPL experiments, create data specification to validate the keys and value types of that data.</p> <pre><code>;; ---------------------------------------------------\n;; Address specifications\n(spec/def ::house-number string?)\n(spec/def ::street string?)\n(spec/def ::postal-code string?)\n(spec/def ::city string?)\n(spec/def ::country string?)\n(spec/def ::additional string?)\n\n(spec/def ::address   ; Composite data specification\n  (spec/keys\n   :req-un [::street ::postal-code ::city ::country]\n   :opt-un [::house-number ::additional]))\n;; ---------------------------------------------------\n</code></pre> <p>As the public API is designed, specifications for each functions arguments are added to validate the correct data is used when calling those functions.</p> <p> Generative testing provides a far greater scope of test values used incorporated into unit tests. Data uses clojure.spec to randomly generate data for testing on each test run.</p>"},{"location":"introduction/repl-workflow/#test-driven-development-and-repl-driven-development","title":"Test Driven Development and REPL Driven Development","text":"<p>Test Driven Development (TDD) and REPL Driven Development (RDD) complement each other as they both encourage incremental changes and continuous feedback.</p> <p>Test Driven Development fits well with Hammock Time, as good design comes from deep thought</p> <ul> <li>RDD enables rapid design experiments so different approaches can easily and quickly be evaluated .</li> <li>TDD focuses the results of the REPL experiments into design decisions, codified as unit tests.  These tests guide the correctness of specific implementations and provide critical feedback when changes break that design.</li> </ul> <p> Unit tests should support the public API of each namespace in a project to help prevent regressions in the code.  Its far more efficient in terms of thinking time to define unit tests as the design starts to stabilize than as an after thought.</p> <p><code>clojure.test</code> library is part of the Clojure standard library that provides a simple way to start writing unit tests.</p> <p> Clojure spec can also be used for generative testing, providing far greater scope in values used when running unit tests.  Specifications can be defined for values and functions.</p> <p>Clojure has a number of  test runners available.  Kaocha is a test runner that will run unit tests and function specification checks.</p> <p>Automate local test runner</p> <p>Use  kaocha test runner in watch mode to run tests and specification check automatically (when changes are saved) <pre><code>clojure -X:test/watch\n</code></pre></p>"},{"location":"introduction/repl-workflow/#continuous-integration-and-deployment","title":"Continuous Integration and Deployment","text":"<p>Add a  continuous integration service to run tests and builds code on every shared commit.  Spin up testable review deployments when commits pushed to a pull request branch, before pushing commits to the main deployment branch, creating an effective pipeline to gain further feedback.</p> <ul> <li> CircleCI provides a simple to use service that supports Clojure projects.</li> <li> GitHub Workflows and GitHub actions marketplace to quickly build a tailored continuous integration service, e.g. Setup Clojure GitHub Action.</li> <li> GitLab CI</li> </ul> <p></p>"},{"location":"introduction/repl-workflow/#live-coding-with-data-stuart-halloway","title":"Live Coding with Data - Stuart Halloway","text":"<p>There are few novel features of programming languages, but each combination has different properties. The combination of dynamic, hosted, functional and extended Lisp in Clojure gives developers the tools for making effective programs. The ways in which Clojure's unique combination of features can yield a highly effective development process.</p> <p>Over more than a decade we have developed an effective approach to writing code in Clojure whose power comes from composing many of its key features. As different as Clojure programs are from e.g. Java programs, so to can and should be the development experience. You are not in Kansas anymore!</p> <p>This talk presents a demonstration of the leverage you can get when writing programs in Clojure, with examples, based on my experiences as a core developer of Clojure and Datomic.</p> <p> </p>"},{"location":"introduction/writing-tips/","title":"Writing tips for MkDocs","text":"<p>Making the docs more engaging using the mkdocs-material theme reference guide</p> Configuring Colors <p>Material for MkDocs - Changing the colors lists the primary and accent colors available.</p> <p>HSL Color Picker for codes to modify the theme style, overriding colors in <code>docs/assets/stylesheets/extra.css</code></p>"},{"location":"introduction/writing-tips/#hypertext-links","title":"Hypertext links","text":"<p>Links open in the same browser window/tab by default.</p> <p>Add <code>{target=_blank}</code> to the end of a link to configure opening in a new tab</p> <pre><code>[link text](url){target=_blank}\n</code></pre>"},{"location":"introduction/writing-tips/#buttons","title":"Buttons","text":"<p>Convert any link into a button by adding <code>{.md-button}</code> class names to end of the markdown for a link, which uses <code>.md-button-primary</code> by default.  Include <code>target=_blank</code> for buttons with links to external sites.</p> <pre><code>[link text](http://practical.li/blog){.md-button target=_blank}\n</code></pre> <p>Or specify a different class</p> <pre><code>[link text](http://practical.li/blog){.md-button .md-button-primary}\n</code></pre> <p>Add an icon to the button</p> <p> Practicalli Issues  Practicalli Blog</p> <pre><code>[:fontawesome-brands-github: Practicalli Issues](http://practical.li/blog){ .md-button .md-button-primary }\n[:octicons-heart-fill-24: Practicalli Blog](http://practical.li/blog){ .md-button .md-button-primary }\n</code></pre> <p>Search all supported icons</p>"},{"location":"introduction/writing-tips/#youtube-video","title":"YouTube video","text":"<p>Use an iframe element to include a YouTube video, wrapping in a paragraph tag with center alignment to place the video in a centered horizontal position</p> <pre><code>&lt;p style=\"text-align:center\"&gt;\n&lt;iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/rQ802kSaip4\" title=\"YouTube video player\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen&gt;&lt;/iframe&gt;\n&lt;/p&gt;\n</code></pre> <p>mkdocs material does not have direct support for adding a YouTube video via markdown.</p>"},{"location":"introduction/writing-tips/#admonitions","title":"Admonitions","text":"<p>Supported admonition types</p> <p>Note</p> <p>Use <code>!!!</code> followed by <code>NOTE</code></p> <p>Adding a title</p> <p>Use <code>!!!</code> followed by <code>NOTE</code> and a <code>\"title in double quotes\"</code></p> <p>Shh, no title bar just the text... Use <code>!!!</code> followed by <code>NOTE</code> and a <code>\"\"</code> empty double quotes</p> <p>Abstract</p> <p>Use <code>!!!</code> followed by <code>ABSTRACT</code></p> <p>Info</p> <p>Use <code>!!!</code> followed by <code>INFO</code></p> <p>Tip</p> <p>Use <code>!!!</code> followed by <code>TIP</code></p> <p>Success</p> <p>Use <code>!!!</code> followed by <code>SUCCESS</code></p> <p>Question</p> <p>Use <code>!!!</code> followed by <code>QUESTION</code></p> <p>Warning</p> <p>Use <code>!!!</code> followed by <code>WARNING</code></p> <p>Failure</p> <p>Use <code>!!!</code> followed by <code>FAILURE</code></p> <p>Danger</p> <p>Use <code>!!!</code> followed by <code>DANGER</code></p> <p>Bug</p> <p>Use <code>!!!</code> followed by <code>BUG</code></p> <p>Example</p> <p>Use <code>!!!</code> followed by <code>EXAMPLE</code></p> <p>Quote</p> <p>Use <code>!!!</code> followed by <code>QUOTE</code></p>"},{"location":"introduction/writing-tips/#collapsing-admonitions","title":"Collapsing admonitions","text":"Note <p>Collapse those admonitions using <code>???</code> instead of <code>!!!</code></p> Replace with a title <p>Use <code>???</code> followed by <code>NOTE</code> and a <code>\"title in double quotes\"</code></p> Expanded by default <p>Use <code>???+</code>, note the <code>+</code> character,  followed by <code>NOTE</code> and a <code>\"title in double quotes\"</code></p>"},{"location":"introduction/writing-tips/#inline-blocks","title":"Inline blocks","text":"<p>Inline blocks of text to make a very specific callout within text</p> <p>Info</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Adding something to then end of text is probably my favourite</p> <p>Info</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p>"},{"location":"introduction/writing-tips/#code-blocks","title":"Code blocks","text":"<p>Code blocks include a copy icon automatically</p> <p>Syntax highlighting in code blocks</p> <pre><code>(defn my-function  ; Write a simple function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n</code></pre> <p>Give the code block a title using <code>title=\"\"</code> after the backtics and language name</p> src/practicalli/gameboard.clj<pre><code>(defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n</code></pre> <p>We all like line numbers, especially when you can set the starting line</p> src/practicalli/gameboard.clj<pre><code>(defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n</code></pre> <p>Add <code>linenums=42</code> to start line numbers from 42 onward</p> <pre><code>clojure linenums=\"42\" title=\"src/practicalli/gameboard.clj\"\n</code></pre>"},{"location":"introduction/writing-tips/#annotations","title":"Annotations","text":"<p>Annotations in a code block help to highlight important aspects.  Use the comment character for the language followed by a space and a number in brackets</p> <p>For example, in a shell code block, use <code># (1)</code> where 1 is the number of the annotation</p> <p>Use a number after the code block to add the text for the annotation, e.g. <code>1.</code>. Ensure there is a space between the code block and the annotation text.</p> <pre><code>ls -la $HOME/Downloads  # (1)\n</code></pre> <ol> <li> I'm a code annotation! I can contain <code>code</code>, formatted text, images, ... basically anything that can be written in Markdown.</li> </ol> <p>Code blocks with annotation, add <code>!</code> after the annotation number to suppress the <code>#</code> character</p> <pre><code>(defn helper-function\n  \"Doc-string with description of function purpose\" ; (1)!\n  [data]\n  (merge {:fish 1} data)\n  )\n</code></pre> <ol> <li>Always include a doc-string in every function to describe the purpose of that function, identifying why it was added and what its value is.</li> </ol> <p>GitHub action example with multiple annotations</p> <pre><code>name: ci # (1)!\non:\n  push:\n    branches:\n      - master # (2)!\n      - main\npermissions:\n  contents: write\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-python@v4\n        with:\n          python-version: 3.x\n      - run: pip install mkdocs-material # (3)!\n      - run: mkdocs gh-deploy --force\n</code></pre> <ol> <li> <p>You can change the name to your liking.</p> </li> <li> <p>At some point, GitHub renamed <code>master</code> to <code>main</code>. If your default branch     is named <code>master</code>, you can safely remove <code>main</code>, vice versa.</p> </li> <li> <p>This is the place to install further [MkDocs plugins] or Markdown     extensions with <code>pip</code> to be used during the build:</p> <pre><code>pip install \\\n  mkdocs-material \\\n  mkdocs-awesome-pages-plugin \\\n  ...\n</code></pre> </li> </ol>"},{"location":"introduction/writing-tips/#highlight-lines-in-code-blocks","title":"Highlight lines in code blocks","text":"<p>Add highlight line meta data to a code block after the opening backticks and code block language.</p> <p><code>hl_lines=\"2\"</code> highlights line 2 in the codeblock</p> <p><code>hl_lines=\"2 3 4\"</code> highlights line 2, 3 and 4 in the codeblock</p> <pre><code>(defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map\n   inc\n   [1 2 3]))\n</code></pre>"},{"location":"introduction/writing-tips/#embed-external-files","title":"Embed external files","text":"<p><code>--8&lt;--</code> in a code block inserts code from a source code file or other text file</p> <p>Specify a local file from the root of the book project (the directory containing mkdocs.yml)</p> Scheduled Version Check GitHub Workflow from source code file scheduled version check<pre><code>\n</code></pre> Practicalli Project Templates Emacs project configuration - .dir-locals.el<pre><code>((clojure-mode . ((cider-preferred-build-tool . clojure-cli)\n                  (cider-clojure-cli-aliases . \":test/env:dev/reloaded\"))))\n</code></pre> <p>Code example reuse</p> <p>Use an embedded local or external file (URL) when the same content is required in more than one place in the book.</p> <p>An effective way of sharing code and configuration mutliple times in a book or across multiple books.</p>"},{"location":"introduction/writing-tips/#content-tabs","title":"Content tabs","text":"<p>Create in page tabs that can also be</p> <p>Setting up a project</p> Clojure CLILeiningen <pre><code>clojure -T:project/new :template app :name practicalli/gameboard\n</code></pre> <pre><code>lein new app practicalli/gameboard\n</code></pre> <p>Or nest the content tabs in an admonition</p> <p>Run a terminal REPL</p> Clojure CLILeiningen <pre><code>clojure -T:repl/rebel\n</code></pre> <pre><code>lein repl\n</code></pre>"},{"location":"introduction/writing-tips/#diagrams","title":"Diagrams","text":"<p>Neat flow diagrams</p> <p>Diagrams - Material for MkDocs</p> <pre><code>graph LR\n  A[Start] --&gt; B{Error?};\n  B --&gt;|Yes| C[Hmm...];\n  C --&gt; D[Debug];\n  D --&gt; B;\n  B ----&gt;|No| E[Yay!];</code></pre> <p>UML Sequence Diagrams</p> <pre><code>sequenceDiagram\n  Alice-&gt;&gt;John: Hello John, how are you?\n  loop Healthcheck\n      John-&gt;&gt;John: Fight against hypochondria\n  end\n  Note right of John: Rational thoughts!\n  John--&gt;&gt;Alice: Great!\n  John-&gt;&gt;Bob: How about you?\n  Bob--&gt;&gt;John: Jolly good!</code></pre> <p>state transition diagrams</p> <pre><code>stateDiagram-v2\n  state fork_state &lt;&lt;fork&gt;&gt;\n    [*] --&gt; fork_state\n    fork_state --&gt; State2\n    fork_state --&gt; State3\n\n    state join_state &lt;&lt;join&gt;&gt;\n    State2 --&gt; join_state\n    State3 --&gt; join_state\n    join_state --&gt; State4\n    State4 --&gt; [*]</code></pre> <p>Class diagrams - not needed for Clojure</p> <p>Entity relationship diagrams are handy though</p> <pre><code>erDiagram\n  CUSTOMER ||--o{ ORDER : places\n  ORDER ||--|{ LINE-ITEM : contains\n  LINE-ITEM {\n    customer-name string\n    unit-price int\n  }\n  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses</code></pre>"},{"location":"introduction/writing-tips/#keyboard-keys","title":"Keyboard keys","text":"<p>Represent key bindings with Keyboard keys. Each number and alphabet character has their own key.</p> <ul> <li>1 <code>++1++</code> for numbers</li> <li>l <code>++\"l\"++</code> for lowercase character</li> <li>U <code>++u++</code> for uppercase character or <code>++\"U\"++</code> for consistency</li> </ul> <p>Punctionation keys use their name</p> <ul> <li>Space <code>++spc++</code></li> <li>, <code>++comma++</code></li> <li>Left <code>++arrow-left++</code></li> </ul> <p>For key sequences, place a space between each keyboard character</p> <ul> <li>Space g s <code>++spc++ ++\"g\"++ ++\"s\"++</code></li> </ul> <p>For key combinations, use join they key identifies with a <code>+</code></p> <ul> <li>Meta+X <code>++meta+x++</code></li> <li>Ctrl+Alt+Del <code>++ctrl+alt+del++</code></li> </ul> <p>MkDocs keyboard keys reference</p>"},{"location":"introduction/writing-tips/#images","title":"Images","text":"<p>Markdown images can be appended with material tags to set the size of the image, whether to appear on light or dark theme and support lazy image loading in browsers</p> SizeLazy LoadingAlignTheme SpecificAll Image Attributes <p><code>{style=\"height:150px;width:150px\"}</code> specifies the image size <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){style=\"height:150px;width:150px\"}\n</code></pre></p> <p></p> <p><code>{loading=lazy}</code> specifies an image should lazily load in the browser <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png){loading=lazy}\n</code></pre></p> <p><code>{aligh=left}</code> or <code>{aligh=right}</code> specifies the page alignment of an image. <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right}\n</code></pre></p> <p>  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p><code>![Kitty Logo](image/kitty-light.png#only-dark)</code> or <code>![Kitty Logo](image/kitty-light.png#only-light)</code>  specifies the theme the image should be shown, allowing different versions of images to be shown based on the theme. <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){style=\"height:150px;width:150px\"}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){style=\"height:150px;width:150px\"}\n</code></pre> Use the theme toggle in the top nav bar to see the icon change between light and dark.  </p> <p>Requires the color pallet toggle</p> <p>Alight right, lazy load and set image to 150x150</p> <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right loading=lazy style=\"height:64px;width:64px\"}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right loading=lazy style=\"height:64px;width:64px\"}\n</code></pre> <p>  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p>"},{"location":"introduction/writing-tips/#lists","title":"Lists","text":"<p>Task lists</p> <ul> <li> Lorem ipsum dolor sit amet, consectetur adipiscing elit</li> <li> Vestibulum convallis sit amet nisi a tincidunt</li> <li> In hac habitasse platea dictumst</li> <li> In scelerisque nibh non dolor mollis congue sed et metus</li> <li> Praesent sed risus massa</li> <li> Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque</li> </ul> <p>Task List example</p> <pre><code>- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit\n- [ ] Vestibulum convallis sit amet nisi a tincidunt\n    * [x] In hac habitasse platea dictumst\n    * [x] In scelerisque nibh non dolor mollis congue sed et metus\n    * [ ] Praesent sed risus massa\n- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque\n</code></pre>"},{"location":"introduction/writing-tips/#tooltips","title":"Tooltips","text":"<p>The humble tool tip</p> <p>Hover me</p> <p>with references</p> <p>Hover me</p> <p>Icon tool tip with a title</p> <p></p>"},{"location":"introduction/writing-tips/#abreviations","title":"Abreviations","text":"<p>The HTML specification is maintained by the W3C.</p> <p>[HTML]: Hyper Text Markup Language [W3C]: World Wide Web Consortium</p>"},{"location":"introduction/writing-tips/#magic-links","title":"Magic links","text":"<p>MagicLink can auto-link HTML, FTP, and email links. It can auto-convert repository links (GitHub, GitLab, and Bitbucket) and display them in a more concise, shorthand format.</p> <p>Email Practicalli</p> <p>Practicalli Neovim</p>"},{"location":"neovim-basics/","title":"Using Neovim","text":"<p>The fundamental controls of Neovim which apply across all editing tasks.</p>"},{"location":"neovim-basics/#fundamentals","title":"Fundamentals","text":"<p> File Buffer Window and Tab page  Multi-modal Editing</p>"},{"location":"neovim-basics/#keyboard-mappings","title":"Keyboard mappings","text":"<p><code>:verbose map</code> followed by a key binding shows the location of the configuration that was last used to set the key mapping.  Use when its not clear what command a key mapping is calling or if a plugin is over-riding an expected mapping. </p> <p>Space f n to list all notifications and Enter on the relevant notification to see the details.</p> <p><code>:verbose map &lt;C-Up&gt;</code> shows the last place in the neovim config that defines a mapping for Ctrl+Up.</p> <p>Map Listing: Neovim docs Key Notation: Neovim docs</p>"},{"location":"neovim-basics/#editing-tools","title":"Editing Tools","text":"<p> Multiple Cursors</p>"},{"location":"neovim-basics/#writing-tools","title":"Writing Tools","text":"<p> Snippets</p>"},{"location":"neovim-basics/#development-tools","title":"Development Tools","text":"<p> Comments  Clojure Development  Version Control</p> <p>Format and Lint tools are installed via Mason</p>"},{"location":"neovim-basics/#spellcheck","title":"Spellcheck","text":"AstroNvim <p><code>SPC u s</code> toggles spellcheck, marking misspelt words with a rew wavy underline</p> <p><code>] s</code> jumps to next misspelt word, <code>[ s</code> jumps to previous misspelt word, </p> <p><code>z =</code> shows numbered list of possible words, enter the number next to the work to replace the misspelt word.</p> <p><code>z g</code> to add the current word to the spell list, infroming spellcheck that this is a correct word.</p>"},{"location":"neovim-basics/comments/","title":"Comments","text":"<p>comment.nvim toggles a comment for lines, visual selections or for motions</p> <p><code>gcc</code> comment current line, <code>4gcc</code> comment current line and next 4 lines</p> <p><code>gc</code> comment region or use with motion e.g. <code>gcap</code> comment paragraph,</p> <p>gc in operator pending mode to target a comment TODO: what is operator pending mode</p> <p><code>:7,17Commentary</code> comment a range</p> <p><code>:g/TODO/Commentary</code> as part of a :global invocation</p> <p><code>gcgc</code> removes comments from a set of adjacent commented lines.</p>"},{"location":"neovim-basics/file-buffer-window-tab/","title":"Files Buffers Windows and Tabs","text":"<p>Files are text written to perminant storage, e.g. disk or usb drive and are names with an extension that represents the file type, e.g. <code>.clj</code> for clojure, <code>.md</code> for markdown, etc.</p> <p>A Buffer hold the contents of a file or any other information from processes, e.g. the REPL evaluation log.</p> <p>Windows are a view on a buffer and windows can swap which buffer they show.  Multiple windows, also known as splits, can be present in a Neovim frame.  </p> <p>A tab page (or tab) can hold one or more windows and multiple tab pages can be shown on a tab-line. </p>"},{"location":"neovim-basics/file-buffer-window-tab/#files","title":"Files","text":"<p>Use Neo-tree.nvim to visually navigate and manage files using a tree view of the current project. Files and directories can be added, renamed, moved and deleted.</p> <p>Use Telescope to select files, typing a name narrows the file list.</p>"},{"location":"neovim-basics/file-buffer-window-tab/#using-neo-tree","title":"Using Neo-tree","text":"AstronvimPracticalli Neovim Config Redux <p>Space e toggles neo-tree file browser</p> <p>Space o toggles between buffer and neo-tree</p> <p>Configure hidden files</p> <p>Configure Neotree to display hidden files and directories by default.  They are shown with a different visual style (subtle color) compared to the other files and directories.  </p> <p><code>H</code> with the cursor in neotree window will still toggle the display of hidden files and directories.</p> <p>Optionally, specify files or directories to never show. Practicalli Astronvim-config: plugins/core.lua<pre><code>  {\n    \"nvim-neo-tree/neo-tree.nvim\",\n    opts = {\n      filesystem = {\n        filtered_items = {\n          -- when true, they will just be displayed differently than normal items\n          visible = true,\n          -- remains hidden even if visible is toggled to true, this overrides always_show\n          never_show = {\n            \".DS_Store\",\n            \"thumbs.db\",\n          },\n        },\n      },\n    },\n  },\n</code></pre></p> <p>Space f t t to open file explorer</p> <p>Within Neo-tree:</p> <p>h j k l to navigate the file tree hierachy</p> <p>&lt; and &gt; to navigate between File, Bufs and Git sources tabs</p> <p>? shows neotree help, listing key bindings</p> <p>a adds a file, prompting for a name relative to the directory where a was pressed. The name can include new directories to be created. A name ending with ++forward-slash++ will create a directory rather than a file.</p> <p>d deletes the current file or directory (including sub-directories), a conformation prompt is shown</p> <p>r to rename a file or directory (use move to change the path)</p> <p>m to move a file or directory, optionally renaming too</p> <p>Neotree icons</p> <ul> <li>yellow dot - unsaved changes</li> <li>pencil - git added changes</li> <li>cross - git deleted changes</li> <li>Warning triangle - lsp diagnostics issues</li> </ul>"},{"location":"neovim-basics/file-buffer-window-tab/#telescope","title":"Telescope","text":"<p>Telescope provides a selector which will narrow the list of matches as a pattern is typed, providing a fast way to find an item in a list.</p> <p>Telescope provides a preview of the selected file (only if there is sufficient space in the Neovim frame)</p> <p>File lists are relative to the directory Neovim was opened from (or Path subsequently set in Neovim).</p> AstroNvimPracticalli Neovim Config Redux <p><code>SPC f f</code> selector for files within the scope of the current directory path. <code>SPC f F</code> to also show hidden files from the current directory path. </p> <p><code>SPC f a</code> selector for AstroNvim user configuration files</p> <p><code>SPC f p</code> selector for previously opened files (oldfiles)</p> <p><code>SPC f f</code> to list files within the scope of the current directory path.</p> <p><code>SPC f b</code> provides a file browser to open files, navigate the file space and create new files and directories</p>"},{"location":"neovim-basics/file-buffer-window-tab/#save-file","title":"Save File","text":"<p>Files and directories are created in the path given, relative to the directory in which Neovim was opened.</p> <p>A file must exist for Neovim to write to it.  Neo-tree and Telescope can be used to create files and directories, as can a terminal and the command line integration (!)</p> AstronvimPracticalli Neovim Config ReduxNeovim <p>Space w will write all buffer changes to the associate file.</p> <p>Space n creates a new buffer that can be written to a given file using <code>:write path/to/filename</code></p> <p><code>:write path/to/filename</code> will write the current buffer to a new file.</p> <p><code>SPC f b ESC C</code> to create a new file or directory. The base path is shown in the command bar.  Type the name of directories and file name as required. <code>RTN</code> to create or <code>ESC</code> to cancel.  The newly created directories or file name appears n the Telescope list and scan be selected for opening.</p> <p>Telescope Normal mode and help</p> <p><code>ESC</code> in Telescope to switch to Normal mode and use comannds, <code>c</code> for Create, <code>r</code> to rename.</p> <p><code>?</code> to show all the commands available in Telescope</p> <p><code>:lcd</code> to set the current local directory</p> <p><code>:write path/to/filename</code> will write the current buffer to a new file</p> <p><code>:!mkdir path/to/directory</code> will create a new directory</p> <p>If a file is already opened, i.e. with <code>:edit</code>, there is some short-hand syntax to simplify the typing</p> <p><code>:!mkdir -p %:h</code></p> <p><code>-p</code> option createst any parts of the path required to make the full path</p> <p><code>%</code> is the neovim name of the current file</p> <p><code>:h</code> for the current directory (the \u201chead\u201d of the path).</p> <p><code>!</code> is the NeoVim terminal shell command, e.g. <code>:!mkdir -p path/to/new/directory</code> creates a new directory and any intermediate path</p>"},{"location":"neovim-basics/file-buffer-window-tab/#swap-file","title":"Swap file","text":"<p>Neovim creates a swap file, <code>.swp</code>, containing the changes made in a buffer to minimise loss should there be an issue with the computer or Neovim.  Changes are written to the swap file after 200 characters or after 4 seconds pause. </p> Swap file location <p><code>:swapname</code> shows the full path to the swap file for the current buffer, e.g.  <pre><code>/home/practicalli/.local/state/astronvim/swap//%home%practicalli%projects%practicalli%books%neovim%docs%neovim-basics%files-buffers-windows.md.swp`\n</code></pre></p> <p><code>:preserve</code> command will write all text from current buffer to the swap file.</p> <p><code>:recover</code> command overwrites the current buffer with the data from the swap file.  <code>:recover!</code> command must be use if the buffer has newer changes than the swap file.  Add a filename after the command to recover to a different file than that contained in the current buffer. </p> <p>Opening a file checks if there is an associated swap file and prompts the user </p> <ul> <li>(A)bort opening the file</li> <li>(D)elete the swap file</li> <li>(E)dit anyway, select if the file is newer than the swap file</li> <li>(R)ecover the data in the swap file into the file buffer</li> </ul> <p><code>:edit</code> after the file is open also prompts if there is a swap file.  Selecting (D)elete will delete the swap file without changing the current buffer</p>"},{"location":"neovim-basics/file-buffer-window-tab/#buffers","title":"Buffers","text":"AstroNvimPracticalli Neovim Config Redux <p><code>SPC f b</code> selector for currently open buffers</p> <p><code>SPC b b</code> to select a buffer from the tab line, pressing the character that appears next to the buffer tab (case sensitive)</p> <p><code>SPC b D</code> to delete a buffer from the tab line, pressing the character that appears next to the buffer tab (case sensitive)</p> <p>Open multiple buffers when starting Neovim by specifying multiple files to open</p> <pre><code>astro README.md deps.edn src/practicalli/playground.clj test/practicalli/playground.clj\n</code></pre> <p><code>SPC b b</code> switch between buffers in the current window, using a Telescope popup that lists all current buffers (includes files, Conjure REPL Log, etc.).</p> <p><code>SPC b n</code> (<code>:next</code>) and <code>SPC b n</code> (<code>:previous</code>) to cycle through buffers in the current window</p> <p><code>SPC TAB</code> (<code>C-^</code>) opens the previous buffer, useful to toggle between two buffers in the same window</p> <p>Use Telescope to switch between buffers</p> <p></p> <p>Open multiple buffers when starting Neovim by specifying multiple files to open</p> <pre><code>nvim README.md deps.edn src/practicalli/playground.clj test/practicalli/playground.clj\n</code></pre>"},{"location":"neovim-basics/file-buffer-window-tab/#buffer-text-wrapping","title":"Buffer text wrapping","text":"<p>The test in a buffer is not wrapped by default. Set and unset soft text wrapping in a buffer</p> AstroNvimPracticalli Neovim Config ReduxNeovim <p><code>SPC u w</code> toggles wrapping of text</p> <p>line wrap not enabled in configuration by default.</p> fnl/config/init.fnl<pre><code>(nvim.ex.set :nowrap)\n</code></pre> <p><code>:set wrap</code> to set soft wrapping on current buffer</p> <p><code>:set nowrap</code> to show lines in full (scroll sideways to see lines longer than the window)</p>"},{"location":"neovim-basics/file-buffer-window-tab/#windows","title":"Windows","text":"<p>Windows can be active (contains the cursor), hidden (open but not shown) or inactive.</p> AstroNvimPracticalli Neovim Config ReduxNeovim <p><code>\\</code> creates an horizontal split</p> <p><code>SPC q</code> removes the current split</p> <p><code>SPC h</code> / <code>SPC l</code> to jump to left / right buffer,  <code>SPC j</code> / <code>SPC k</code> to jump to buffer below / above</p> <p><code>SPC b b</code> to list current buffers and switch between them using telescope</p> <p><code>C-w</code> and <code>hjkl</code> to navigate windows is the classic Vim approach</p> <p><code>C-w</code> menu to manage Windows, also known as splits.</p> <p><code>C-w</code> with one of <code>hjkl</code> will move the cursor to the next window in that direction.  Also works with arrow keys.</p> <p><code>C-w w</code> toggle between open windows</p> <p><code>:q</code> or <code>C-w q</code> closes the active window, closing Neovim if it is the last active window.</p> <p><code>:wincmd</code> can be used as an alternative to the Normal mode key bindings</p> <p>Open file in a new window</p> <pre><code>:sp relative-or-full-filename-path\n</code></pre> <p>Resize windows</p> <p><code>C-w</code> <code>-</code>, <code>+</code>, <code>&lt;</code> or <code>&gt;</code> for vertical or horizontal size adjustment</p>"},{"location":"neovim-basics/file-buffer-window-tab/#tab-pages","title":"Tab pages","text":"<p>A Tab page can hold one or more tabs and are useful for grouping different types of files and information. </p> <p>A Tab page holds one or more windows, each window is a view on a buffer, a buffer holds the contents of a file or any other information in the editor memory (repl log, etc).</p> <p>A tab page can provide a logical grouping of windows, e.g. Clojure source code in one tab, tests in a second tab and REPL log in a third.</p> <p>Neovim window commands may be constrained within the bounds of a tab page (without using the :tab modifier)</p> <p>Tab pages are often referred to as tabs.</p> AstroNvim <p>g Tab jump to previously selected tab, commonly used to toggle between two tabs  (Practicalli AstroNvim mapping)</p> <p>g t jump to next tab page</p> <p>g T jump to previous tab page</p>"},{"location":"neovim-basics/multi-modal-editing/","title":"Multi-modal Editing","text":"<p>TODO: Add multi-modal editing in Neovim guide</p> <p>Practicalli Spacemacs has useful reference content on multi-modal editing (Evil mode).</p> <p>Most of this content is the same in Neovim with a few exceptions</p>"},{"location":"neovim-basics/multi-modal-editing/#selecting-text","title":"Selecting text","text":"<p><code>vi)</code> selects all the text within <code>()</code>, e.g. <code>(http://oldwebsite.doh)</code></p>"},{"location":"neovim-basics/multi-modal-editing/#surround","title":"Surround","text":"<p><code>viw</code> selects the current word, using j/k to modify the selection where required. <code>o</code> toggles which end of the selection is expanded/shrunk</p> <p><code>s</code> substitues the selection, type the characters to surround the selection.</p> <p><code>p</code> to pase the original text</p>"},{"location":"neovim-basics/multi-modal-editing/#nvim-surround","title":"nvim-surround","text":"<p>nvim-surround provides enhancments over the neovim surround command.</p> <p>nvim-surround included in Practicalli AstroNvim Config</p>"},{"location":"neovim-basics/multi-modal-editing/#visual-mode","title":"Visual Mode","text":"<p><code>viw</code> to select the current word (visual in word)</p> <p>S  on a visual selection to surround with next that character, e.g. <code>S)</code> to surround with parens.</p> <p>Closing paren surrounds without spaces</p> <p><code>)</code>, <code>]</code>, <code>}</code> surrounds the selected text without spaces between the text and the open and closing parens.</p> <p><code>(</code>, <code>[</code>, <code>{</code> surrounds the selected text with a space between the text and the open and closing parens.</p>"},{"location":"neovim-basics/multi-modal-editing/#normal-mode","title":"Normal mode","text":"<p><code>cs</code> inside an existing pair of characters to change them to another pair of surrounding characters, e.g. <code>cs(}</code> to change (text) to {text}</p> <p><code>ds</code> inside a pair of surrounding characters to delete them, e.g. <code>ds(</code> to change (text) to text</p> <p><code>ys</code> you surround followed by motion and character, e.g. <code>ysw)</code> surrounds word with (parens)</p> <p><code>yS</code> to surround current line</p> <p><code>ySS</code> to surround current line, placing characters on new lines, e.g. <code>ySS{</code> will change \"Olical/conjure\" to:</p> <pre><code>{\n    \"Olical/conjure\"\n}\n</code></pre> <p>The three \"core\" operations of add/delete/change can be done with the keymaps ys{motion}{char}, ds{char}, and cs{target}{replacement}, respectively. For the following examples, * will denote the cursor position:</p> <pre><code>Old text                    Command         New text\n----------------------------------------------------\nsurr*ound_words             ysiw)           (surround_words)\n*make strings               ys$\"            \"make strings\"\n[delete ar*ound me!]        ds]             delete around me!\nremove &lt;b&gt;HTML t*ags&lt;/b&gt;    dst             remove HTML tags\n'change quot*es'            cs'\"            \"change quotes\"\n&lt;b&gt;or tag* types&lt;/b&gt;        csth1&lt;CR&gt;       &lt;h1&gt;or tag types&lt;/h1&gt;\ndelete(functi*on calls)     dsf             function calls\n</code></pre> <p>Neovim help provides details on using nvim-surround</p> <pre><code>:help nvim-surround.usage\n</code></pre>"},{"location":"neovim-basics/multi-modal-editing/#web-links","title":"Web Links","text":"<p>g x on a URL to open in the default browser</p>"},{"location":"neovim-basics/multi-modal-editing/#markdown","title":"Markdown","text":"<p><code>s</code> in visual mode substitues the selection with the next character typed</p> <p><code>v</code> to create visual selection, <code>s</code> to substitute the current selection, <code>****</code> to create a bold style, <code>P</code> with the cursor on the second <code>*</code> pastes the text that was visually selected. </p>"},{"location":"neovim-basics/multi-modal-editing/#text-style","title":"Text style","text":"<p><code>ysiw*</code> surrounds current word with <code>*</code> to create italic text, <code>.</code> repeats to make bold text style.</p> <p><code>ds*</code> removes <code>*</code> from current word.</p>"},{"location":"neovim-basics/multi-modal-editing/#nvim-surround_1","title":"nvim-surround","text":"<p>nvim-surround plugin assists with adding style characters around text, e.g adding links, italic or bold text, etc.</p> <p><code>S</code> on a visual selection will surround the text with the next character.  <code>.</code> repeat not supported.</p> <p>Create a link</p> <p><code>v</code> and motion keys to select text, <code>S [</code> to surround text with <code>[]</code> creating the text of a link anchor.  Use <code>S (</code> to surround the URL of the link.</p>"},{"location":"neovim-basics/multiple-cursors/","title":"Multiple cursors","text":"<p>Visual-Multi (VM) is a multiple selections/cursors plugin that uses modal editing and provide visual feedback when editing multiple lines simultaneously.</p> <p>Mulitple cursors is generally useful when editing smilarly structured lines with diffferent content.  Cursors are moved by column position or by using vim motions.</p> AstroNvimPracticalli Neovim Config Redux <p>Space g m opens the visual-multi menu</p> <p>Using visual select is a simple way to edit multiple lines as the same time.</p> <p>Space g m c on visually selected lines creates a cursor on each line.</p> <p>Esc or f d to close multiple cursors.</p> <p><code>\\ \\ c</code> creates a cursor at the start of every visual selection line</p> <p><code>\\ \\ \\</code> toggle cursor at position</p>"},{"location":"neovim-basics/multiple-cursors/#search-and-replace","title":"Search and Replace","text":"<p>Select a text pattern to search for and use multiple cursors to add a cursor each match, then change each selected occurance concurrently.</p> AstroNvimPracticalli Neovim Config Redux <p>Select the pattern with visual select</p> <p>Space g m a on each matching text pattern in the buffer</p> <p><code>c</code> to change the original text and type the new pattern.  All cursors will update concurrently.</p> <p>Esc or f d to close multiple cursors.</p> <p><code>\\ \\ a</code> creates a cursor at the start of every visual selection line</p> <p><code>\\ \\ \\</code> toggle cursor at position</p> <p><code>c</code> to change the original text and type the new pattern.  All cursors will update concurrently.</p> <p>Esc or f d to close multiple cursors.</p>"},{"location":"neovim-basics/multiple-cursors/#command-quick-reference","title":"Command quick reference","text":"<p><code>:help g:VM_maps</code> for a reference of all mappings and instructions on how to change them</p> AstroNvim <p><code>SPC g m</code> opens the Visual-Multi menu in normal mode</p> <p><code>g m</code> opens the Visual-Multi menu in visual mode</p> <p><code>c</code> to add a cursor to every line in the visually selected region</p> Practicalli Neovim Config Redux <p><code>\\ \\</code> is the leader for multiple cursors and will show the visual-multi menu in which-key.</p> <p>These commands cover the large majority of use cases for multiple cursors.</p> Action Key Command Add Cursor at Position <code>\\\\\\</code> <code>vm-add-cursor</code> Alignm VM cursors with cursor <code>\\\\a</code> <code>vm-align</code> Select All Words <code>\\\\A</code> <code>vm-select-all</code> Transposition <code>\\\\t</code> <code>vm-transpose</code> Toggle Mappings <code>\\\\&lt;Space&gt;</code> <code>vm-mappings-toggle</code> Find with Regex <code>\\\\/</code> <code>vm-regex-search</code> Reselect Last <code>\\\\gS</code> <code>vm-reselect-last</code> <p>Once visual-multi has started the vm-mappings-buffer mappings are available:</p> Action Key Command Find Word <code>&lt;C-n&gt;</code> vm-find-word Next/Previous/Skip <code>n</code> / <code>N</code> / <code>q</code> vm-find-next Remove Region <code>Q</code> vm-remove-region Add Cursors Down/Up <code>&lt;C-Down&gt;</code> / <code>&lt;C-Up&gt;</code> vm-add-cursors Select Right/Left <code>&lt;S-Right&gt;</code>, <code>&lt;S-Left&gt;</code> vm-shift-select Slash motion <code>g/</code> vm-slash Select Operator <code>s</code> vm-select-operator Find Operator <code>m</code> vm-find-operator <p>NOTE: <code>C-n</code> conflicts with the Termux binding for naming a session</p>"},{"location":"neovim-basics/multiple-cursors/#searching","title":"Searching","text":"<p><code>g/</code> to search for a match to add when visual-multi is active, rather than the usual <code>/</code> vim search.</p> <p><code>n</code> and <code>N</code> can't be used to repeat the search, as they are used to get the next visual-multi match.</p>"},{"location":"neovim-basics/multiple-cursors/#find-with-regex","title":"Find with Regex","text":"<p><code>\\ \\ /</code> followed by a regex pattern will create a selection with that pattern.</p> <p><code>n</code> and <code>N</code> finds the next occurrence of the regex pattern</p>"},{"location":"neovim-basics/multiple-cursors/#smart-case-change","title":"Smart case change","text":"<p><code>gc</code> In extend-mode will use smartcase to change a selection</p> <ul> <li>at main cursor, text is always inserted as typed</li> <li>at other cursors, if region text was fully uppercased, replacement will be uppercased as well</li> <li>if the region text was capitalized, the replacement will be as well</li> </ul>"},{"location":"neovim-basics/multiple-cursors/#filter-regions","title":"Filter regions","text":"<p><code>\\ \\ f</code> filter out (remove) regions based on pattern or expression.</p> <p><code>C-x</code> to cycle filtering method:</p> <ul> <li>pattern: remove regions that don't match the pattern</li> <li>!pattern:  remove regions that match the pattern</li> <li>expression: remove regions that don't match the expression (same as below)</li> </ul>"},{"location":"neovim-basics/multiple-cursors/#transform-regions-with-expression","title":"Transform regions with expression","text":"<p><code>\\ \\ e</code> to transform a region with a vim expression, run on each region</p> <p>Placeholders can be used in the expression</p> <ul> <li>`%t~ region's text as a string (as-is)</li> <li>`%f~ region's text evaluated as a floating point number</li> <li>`%n~ region's text evaluated as an integer number</li> <li>`%i~ region's index</li> <li>`%N~ total number of regions</li> </ul> <p>Examples: - <code>%f * 0.5</code> divide text of all regions by 2 - <code>%t .\" \". %i .\" / \". %n</code>  append index / total to text of each region - <code>%i%2 ? %t : toupper(%t)</code>  uppercase all odd regions (1,3,5...) - <code>%i%3-2 ? %t : ''</code>  delete every third region</p>"},{"location":"neovim-basics/multiple-cursors/#vm-motions","title":"VM Motions","text":"<p>visual-multi supports vim motions although they behave differently as their result is dependent on the mode:</p> <ul> <li><code>cursor mode</code> will move cursors</li> <li><code>extend mode</code> motions extend selections</li> </ul> <p>Unless multiline-mode is enabled motions are restricted to the current line and cannot cross line boundaries</p> <p>Some object-motions and various-motions require multiline-mode and aliased to avoid conflict with VM mappings:</p> vim VM~ Description / g/ to next match (for all regions) ( ( [count] sentences backward ) ) [count] sentences forward { { [count] paragraphs backward } } [count] paragraphs forward [( g( go to [count] previous unmatched '(' [{ g{ go to [count] previous unmatched '{' ]) g) go to [count] next unmatched ')' ]} g} go to [count] next unmatched '}'"},{"location":"neovim-basics/multiple-cursors/#vm-operators","title":"vm-operators","text":"<p>Visual-Multi supports several operators by default:</p> <ul> <li><code>y</code> / <code>d</code> / <code>c</code> to yank / delete / change</li> <li><code>gu</code> / <code>gU</code> to change text case</li> </ul> <p>Visual-Multi uses its own registers that are lists of strings. One element for each region that is yanked/deleted.</p> <p>There is also built-in support for:</p> <ul> <li>vim-surround  e.g. <code>ysiw(</code> to enclose in parentheses</li> <li>vim-abolish e.g. <code>cr_</code> to change current word to snake case</li> </ul> <p>`:help g:VM_user_operators to disccover how to doefine other operators</p>"},{"location":"neovim-basics/multiple-cursors/#vm-multiline-mode","title":"vm-multiline-mode","text":"<p>In normal and insert mode, cursors and selections are kept within their own line.  Cursors are blocked from moving off the current line to the next line.</p> <p><code>M</code> enables multiline-mode that allows cuursors to move onto another line.</p> <p>Multiline mode must be enabled for an object motions, or they will fail. See |vm-motions|.</p>"},{"location":"neovim-basics/multiple-cursors/#alignment","title":"Alignment","text":"<p><code>\\\\a</code> aligns by setting the minimum column to the highest of all regions <code>\\\\&lt;</code> aligns by character, or [count] characters <code>\\\\&gt;</code> aligns by regex pattern</p> <p>In extend-mode selections are collapsed to cursors first, although will work regardless.</p>"},{"location":"neovim-basics/multiple-cursors/#replace-pattern-in-regions","title":"Replace pattern in regions","text":"<p><code>R</code> to replace with a pattern and then the replacement text</p> <p>substitution will take place in all selected regions, leaving unselected text untouched.</p> <p>Only working in |extend-mode|. When |R| is pressed in |cursor-mode|, it will start |vm-replace-mode| instead.</p>"},{"location":"neovim-basics/multiple-cursors/#subtract-pattern-from-regions","title":"Subtract pattern from regions","text":"<p><code>\\\\s</code> subtract the entered pattern from regions, splitting them. Only working in |extend-mode|.</p>"},{"location":"neovim-basics/multiple-cursors/#transposition","title":"Transposition","text":"<p><code>\\ \\ t</code> swaps the contents of selections, cycling them if there are more than two.</p> <p>If there is an equal number of selections in each line, swapping takes place within the same line only. Only in |extend-mode|.</p>"},{"location":"neovim-basics/multiple-cursors/#duplication","title":"Duplication","text":"<p><code>\\ \\ d</code> duplicates in place the contents of the selections, reselecting the original ones. Only in extend-mode.</p>"},{"location":"neovim-basics/multiple-cursors/#shift-selections","title":"Shift Selections","text":"<p> and  move the selections right or left, preserving the surroundings."},{"location":"neovim-basics/multiple-cursors/#case-conversion","title":"Case conversion","text":"<p><code>\\\\C</code> runs on inner words in cursor mode</p> <ul> <li><code>u</code> lowercase</li> <li><code>U</code> UPPERCASE</li> <li><code>C</code> Captialize</li> <li><code>t</code> Title Case</li> <li><code>c</code> camelCase</li> <li><code>P</code> PascalCase</li> <li><code>s</code> snake_case</li> <li><code>S</code> SNAKE_UPPERCASE</li> <li><code>-</code> dash-case</li> <li><code>.</code> dot.case</li> <li><code>&lt;space&gt;</code> space case</li> </ul>"},{"location":"neovim-basics/multiple-cursors/#modes","title":"Modes","text":"<p>cursor-mode and extend-mode are two Visual-Multi modes, roughly corresponding to normal-mode and visual-mode</p> <p><code>TAB</code> switches between cursor-mode and extended-mode</p>"},{"location":"neovim-basics/multiple-cursors/#vm-cursor-mode","title":"VM Cursor Mode","text":"<p>cursor-mode commands expect a motion, e.g. <code>c</code> should be followed by a text object to be changed.</p> Key Description <code>operators</code> see vm-operators <code>motions</code> see vm-motions <code>|</code> set column for all cursors (to current column or [count]) <code>r</code> replace single character <code>R</code> enter vm-replace-mode <code>~</code> change case of single character <code>&amp;</code> repeat last substitution <code>&lt;C-A&gt;</code> increase numbers <code>&lt;C-X&gt;</code> decrease numbers <code>g&lt;C-A&gt;</code> progressively increase numbers (<code>v_g_CTRL-A</code>) <code>g&lt;C-X&gt;</code> progressively decrease numbers (<code>v_g_CTRL-X</code>) <p>You can enter |insert-mode| with <code>i</code>, <code>I</code>, <code>a</code>, <code>A</code>, and only from cursor mode also with <code>o</code> and <code>O</code>.</p> <p>Also see <code>vm-motions</code> for supported motions in VM (some with differences).</p>"},{"location":"neovim-basics/multiple-cursors/#vm-extend-mode","title":"VM Extend Mode","text":"<p>extend-mode is like having multiple visual selections.  motions extend the slections and change / yank / delete commands don't wait for a motion, just like in visual mode.</p> <p>Even the key <code>o</code> works as in visual mode, inverting the anchor of the selections.</p> <p>Some commands are specific to |extend-mode|, such as:</p> <ul> <li><code>s</code> vim-surround</li> <li><code>R</code> replace pattern in regions</li> <li><code>\\\\s</code> split regions by pattern</li> <li><code>\\\\e</code> transform regions text with vim expression</li> </ul> <p>Some commands enforce cursor-mode when run from extend-mode:</p> <ul> <li><code>&lt;C-A&gt;</code> increase numbers</li> <li><code>&lt;C-X&gt;</code> decrease numbers</li> </ul> <p>Others can use a different mapping:</p> <ul> <li><code>gu/gU</code> change case (instead of vim <code>u</code> / <code>U</code>)</li> <li><code>o</code> and <code>O</code> mappings are used to invert the facing of the selected regions and not to start insert mode.</li> </ul>"},{"location":"neovim-basics/notifications/","title":"Notifications","text":"Notifications only in AstroNvim, not the Practicalli Neovim configuration <p>Space f n lists the history of notifications for the current sesion</p> <p>Enter to open the highlighted item in the list in its own popup</p> <p> </p> <p>Notification popups show information, warnings and errors.</p> <p></p>"},{"location":"neovim-basics/notifications/#configure-notifications","title":"Configure notifications","text":"<p>Notifications are controlled by  nvim-notify</p> <p> Practicalli astronvim-config overrides several default values in <code>plugins/core.lua</code></p> <ul> <li><code>top_down</code> position of notifications, <code>false</code> shows popups from bottom of screen</li> <li><code>timeout</code> value controls how long a popup displays, defautl <code>3000</code></li> <li><code>level</code> of information displayed, level 3 hides less important information, e.g. file write messages, default 5</li> </ul> <p>Practicalli Configuration for notifications</p> plugins/core.lua<pre><code>  -- Configure notify popups\n  {\n    \"rcarriga/nvim-notify\",\n    opts = {\n      top_down = false,\n      timeout = 1000,\n      -- log level - 3 hide file write messages - default 5\n      level = 3,\n      -- background_color = \"#000000\",\n    },\n  },\n</code></pre> <p>Noice uses nvim-notify configuration</p> <p>Noice replaces the UI for messages, command line and popup menus, although uses the configuration of nvim-notify for position and popup timing.</p>"},{"location":"neovim-basics/plugin-manager/","title":"Plugin Manager","text":"<p>Neovim community provides a wide range of plugins to greatly extend the features of Neovim</p> <p>There is a wide range of plugin managers too, including a built-in plugin manager in Neovim.</p> <ul> <li>Lazy - AstroNvim Config</li> <li>Packer - Practicalli Neovim Config Redux</li> </ul> <p>Lazy plugin manager recommeded</p> <p>Practicalli recommends Lazy plugin manager as it feels much easier to use and has a more engaing and understandable user interface</p> Neovim evolving <p>Neovim and its plugins are evolving quite rapidly, so it is recommended to update plugins if there are issue or when a newer version of Neovim has been installed</p> <p>Plugin issue are not that common and typically fixed quite quickly by the community</p> AstroNvimPracticalli Neovim Config Redux <p>Lazy plugin manager</p> <p> </p> <p><code>SPC P u</code> to update packages to their latest versions (<code>:PackerUpdate</code>).  Details of updated changes will be shown at the end of the update.</p> <p></p> <p><code>r</code> in the package update screen gives the option to revert an update if something has gone wrong (although this seem to be a rare issue).</p> <p>When packages are all at the latest available version, Packer update reports packages already up to date.</p> <p></p> <p>Packer downloads packages and documentation from the Internet, so a connection is required</p>"},{"location":"neovim-basics/plugin-manager/#package-list-and-documentation","title":"Package List and documentation","text":"AstroNvimPracticalli Neovim Config Redux <p>Lazy plugin manager</p> <p><code>SPC P l</code> to list the current packages added to the configuration</p> <p></p> <p>Selecting a package will display the website documentation for the package (although this may be in HTML so not the cleanest way to read the docs).</p>"},{"location":"neovim-basics/plugin-manager/#adding-packages","title":"Adding packages","text":"AstroNvimPracticalli Neovim Config Redux <p>Lazy plugin manager</p> <p>Add package names as keywords in the <code>use</code> expression in <code>fnl/config/plugin.fnl</code> file.</p> <p><code>:requires</code> to add a package that is a dependency for the package being added</p> <p><code>:mod</code> defines the namespace that contains the package configuration, typically a <code>setup</code> function with options.  The namespace matches the file name under <code>fnl/config/plugin</code></p> <p><code>SPC P i</code> to install packages that have been added to <code>fnl/config/plugin.fnl</code></p> <p><code>q</code> to quit once all packages are up to date</p>"},{"location":"neovim-basics/snippets/","title":"Snippets","text":"<p>LuaSnip can use several different sources for snippets</p> <ul> <li>VSCode JSON snippets (Friendly-snippets)</li> <li>LSP style snippets </li> </ul> LuaSnip Configuration <p>Practicalli Neovim Config Redux includes the LuaSnip package which also adds friendly-snippets and cmp_luasnip. <pre><code>  ; snippets\n  :L3MON4D3/LuaSnip \n  {:requires [:rafamadriz/friendly-snippets\n              :saadparwaiz1/cmp_luasnip]\n   :mod :lua-snip}\n</code></pre> Configure LSP snippet locations <pre><code>{\n  \"name\": \"practicalli-snippets\",\n  \"engines\": {\n    \"vscode\": \"^1.11.0\"\n  },\n  \"contributes\": {\n    \"snippets\": [\n      {\n        \"language\": [\n          \"markdown\",\n          \"global\",\n          \"all\"\n        ],\n        \"comment\": \"snippets accross several languages\",\n        \"path\": \"./global.json\"\n      },\n      {\n        \"language\": \n          \"markdown\",\n        \"path\": \"./markdown.json\"\n      }\n    ]\n  }\n}\n</code></pre></p>"},{"location":"neovim-basics/snippets/#snippet-definitions","title":"Snippet Definitions","text":"<p><code>snippets</code> directory contains snippet definitions, with a JSON file for each language, e.g. <code>markdown.json</code></p> <p>Practicalli Neovim Config Redux contains several groups of snippet definitions</p> <ul> <li>MkDocs format and icons (<code>markdown.json</code> VSCode syntax)</li> </ul> <p>Restart Neovim to load new defintions</p> <p>Snippets added to VSCode JSON snippets are only loaded when Neovim starts, so newly added snippets will only be available after Neovim is restarted.</p>"},{"location":"neovim-basics/terminal/","title":"Terminal","text":"<p>akinsho/toggleterm.nvim plugin provides a terminal session within Neovim, using a float, split or tab.</p> AstroNvim <p><code>SPC t</code> for the Terminal sub-menu </p> <p><code>SPC t f</code> opens a terminal in a floating window, useful for one-off commands</p> <p><code>SPC t h</code> opens a terminal in a horizontal split, useful for a process that prints valuable feedback, e.g. a test runner in watch mode</p> <p><code>SPC t t</code> opens a terminal in a tab, useful for background processes that do not need attendtion </p> <p> </p>"},{"location":"neovim-basics/zen-mode/","title":"Focus Modes","text":"<p>Focus on the code or text being created, without distractions</p> <p><code>zZ</code> toggles Zen mode</p> <p><code>SPC z a</code> ataraxis focus mode</p> <p><code>SPC z f</code> focus current buffer</p> <p><code>SPC z n</code> narrow to current buffer</p> <p><code>SPC z n</code> remove status bar and window decorations</p> <p><code>v SPC z n</code> narrow to selection</p>"},{"location":"neovim-basics/zen-mode/#zen-mode","title":"Zen Mode","text":"<p>Zen Mode distraction-free coding for Neovim</p> <p>Available via the Astrocommunity repository.</p> <p>Zen Mode configuration for AstroNvim</p> .config/astronvim-config/plugins/community.lua<pre><code>  { import = \"astrocommunity.editing-support.zen-mode-nvim\" },\n  {\n    \"folke/zen-mode.nvim\",\n    opts = {\n      -- override default configuration\n      -- https://github.com/folke/zen-mode.nvim#%EF%B8%8F-configuration\n      plugins = {\n        options = {\n          enabled = true,\n        },\n        kitty = {\n          enabled = true,\n          font = \"+4\", -- font size increment\n        },\n      },\n    },\n  },\n</code></pre> <p>kitty configuration enables Zen Mode to resize kitty fonts.</p>"},{"location":"neovim-basics/zen-mode/#true-zen","title":"True Zen","text":"<p>true-zen.nvim clean and elegant distraction-free writing for NeoVim</p> <p>True Zen Mode configuration for AstroNvim</p> <pre><code>  {\n    \"Pocco81/true-zen.nvim\",\n    lazy = false,\n    opts = {\n      integrations = {\n        kitty = {\n          -- increment font size in Kitty.\n          enabled = true,\n          font = \"+4\",\n        },\n      },\n    },\n  },\n</code></pre> <p>See kitty configuration to enable Zen Mode to resize kitty fonts.</p>"},{"location":"neovim-basics/zen-mode/#kitty-configuration","title":"Kitty configuration","text":"<p>Add <code>allow_remote_control socket-only</code> and <code>listen_on unix:/tmp/kitty</code> to the kitty config</p> <p>Kitty support for Zen Mode</p> .config/kitty/kitty.config<pre><code># ---------------------------------------------------------\n#  Neovim zen-mode-nvim\n#  - change the font size on kitty when in zen mode\nallow_remote_control socket-only\nlisten_on unix:/tmp/kitty\n# ---------------------------------------------------------\n</code></pre>"},{"location":"neovim-basics/search-replace/","title":"Search and Replace","text":"<p>Search and replace within the current buffer:</p> <ul> <li>use multipe cursors for in-place editing (visual-multi plugin) </li> <li><code>:%substitue</code> vim-style search and replace</li> </ul> <p>Search and replace across a project:</p> <ul> <li>Space s search and replace commands using Spectre (AstroNvim community plugin)</li> <li>Space l r to rename symbols using Clojure LSP (AstroNvim) </li> </ul>"},{"location":"neovim-basics/search-replace/#buffer-wide","title":"Buffer wide","text":"AstroNvimNeovim commands <p>g m A uses visual-multi multiple curses to match all instances of the selected text and in-place editing</p> <p>Vim-editing tools can be used to replace the text at all cursors simultaneously.</p> <p>multiple cursors in more detail </p> <p>Replace all occurances of the current-pattern with the new pattern within the buffer.</p> <pre><code>:%s/current-pattern/new-pattern/g\n</code></pre> <p>Add the <code>c</code> option to confirm each replacement</p> <p>Further examples of <code>:substitue</code> neovim command</p>"},{"location":"neovim-basics/search-replace/#project-wide","title":"Project wide","text":"<p>Evaluating...</p> AstroNvimNeovim commands <p>Spectre is available via the AstroNvim Community project pack and included in the Practicalli astronvim-config    </p> <p>Space s is the search and replace menu</p> <p></p> <p>ripgrep and sed are required.</p> <p>Spectre </p> <p>Vims new :cdo command</p> Neovim :help :cdo <pre><code>EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST:\n                            *:cdo*\n:cdo[!] {cmd}       Execute {cmd} in each valid entry in the quickfix list.\n            It works like doing this:  \n                :cfirst\n                :{cmd}\n                :cnext\n                :{cmd}\n                etc.\n            When the current file can't be |abandon|ed and the [!]\n            is not present, the command fails.\n            When going to the next entry fails execution stops.\n            The last buffer (or where an error occurred) becomes\n            the current buffer.\n            {cmd} can contain '|' to concatenate several commands.\n\n            Only valid entries in the quickfix list are used.\n            A range can be used to select entries, e.g.:  \n                :10,$cdo cmd\n            To skip entries 1 to 9.\n\n            Note: While this command is executing, the Syntax\n            autocommand event is disabled by adding it to\n            'eventignore'.  This considerably speeds up editing\n            each buffer.\n            Also see |:bufdo|, |:tabdo|, |:argdo|, |:windo|,\n            |:ldo|, |:cfdo| and |:lfdo|.\n\n                            *:cfdo*\n:cfdo[!] {cmd}      Execute {cmd} in each file in the quickfix list.\n            It works like doing this:  \n                :cfirst\n                :{cmd}\n                :cnfile\n                :{cmd}\n                etc.\n            Otherwise it works the same as `:cdo`.\n\n                            *:ldo*\n:ld[o][!] {cmd}     Execute {cmd} in each valid entry in the location list\n            for the current window.\n            It works like doing this:  \n                :lfirst\n                :{cmd}\n                :lnext\n                :{cmd}\n                etc.\n            Only valid entries in the location list are used.\n            Otherwise it works the same as `:cdo`.\n\n                            *:lfdo*\n:lfdo[!] {cmd}      Execute {cmd} in each file in the location list for\n            the current window.\n            It works like doing this:  \n                :lfirst\n                :{cmd}\n                :lnfile\n                :{cmd}\n                etc.\n            Otherwise it works the same as `:ldo`.\n</code></pre>"},{"location":"neovim-basics/search-replace/substitute/","title":"Substitute command","text":"<p><code>:substitute</code> or <code>:s</code> command highlights the matches for a text pattern and substitute for a new pattern</p> Neovim :help :substitute <pre><code>:help :substitute\n</code></pre> <p>Subsitute the first matching patterns in the current line</p> <pre><code>:s/current-pattern/new-pattern/\n</code></pre> <p>If the new-pattern text is ommitted, then substitute deletes the current-pattern occurances, e.g <code>:s/current-pattern//</code></p> <p>Subsitute all the matching patterns in the current line,  <code>g</code> representing all occurances in a line</p> <pre><code>:s/current-pattern/new-pattern/g\n</code></pre> <p>Use <code>%</code> to specify the current buffer as the scope to change all matches</p> <pre><code>:%s/current-pattern/new-pattern/g\n</code></pre> <p>An inclusive line range can be specified to narrow the search</p> <pre><code>:4,24s/current-pattern/new-pattern/g\n</code></pre> <p><code>.</code> can be used to represent the current line of buffer</p> <p><code>$</code> to represent the last line of the current buffer</p> <pre><code>:.,$s/current-pattern/new-pattern/g\n</code></pre> <p>Match the whole word </p> <pre><code>:.,$s/\\&lt;current-pattern\\&gt;/new-pattern/g\n</code></pre>"},{"location":"neovim-basics/search-replace/substitute/#substitute-history","title":"Substitute history","text":"<p><code>:s</code> and the Up / Down will navigate through the substitution history for the current session (from when Neovim was last opened if session was not restored)</p>"},{"location":"neovim-basics/search-replace/substitute/#confirm-replacement","title":"Confirm replacement","text":"<p>c option at the end prompt for confirmation to replace each occurance</p> <pre><code>:%s/current-pattern/new-pattern/gc\n</code></pre> <p>y confirms the repacement </p> <p>l confirms the repacement and quits</p> <p>n skips the current occurance and goes to the next one</p> <p>y or Esc to quit substitution</p>"},{"location":"neovim-basics/search-replace/substitute/#regular-expression","title":"Regular expression","text":"<p>regular expressions can be used as a search pattern. </p> <p>To replace all lines starting with \u2018foo\u2019 with \u2018NeoVim Rocks\u2019:</p> <pre><code>:%s/^foo.*/NeoVim rocks/gc\n</code></pre> <p>Replace all instances of \u2018apple\u2019, \u2018orange\u2019, and \u2018mango\u2019 with \u2018fruit\u2019:</p> <pre><code>:%s/apple\\|orange\\|mango/fruit/g\n</code></pre> <p>Remove trailing blank space at the end of each line:</p> <pre><code>:%s/\\s\\+$//e\n</code></pre>"},{"location":"neovim-basics/search-replace/substitute/#matching-case","title":"Matching case","text":"<p><code>i</code> option disables the default case sensitive search</p> <pre><code>:%s/current-pattern/new-pattern/gi\n</code></pre>"},{"location":"neovim-basics/search-replace/substitute/#visual-select","title":"Visual Select","text":"<p>Use a visual select to search and replace, with confirmation</p> <p>Note: <code>'&lt;,'&gt;</code> is automatically included when in visual mode and <code>:</code> is pressed to start a command </p> <pre><code>:'&lt;,'&gt;s/search-text/replace-text/g\n</code></pre> <p>A potentially more effecitve approach:</p> <ul> <li>visually select the text</li> <li><code>*</code> to select all matching occurances</li> <li><code>:%s//replace-text/g</code></li> </ul>"},{"location":"reference/lua-language/","title":"Lua","text":"<p>Lua is the default language for Neovim configuration.</p>"},{"location":"reference/lua-language/#learning-lua","title":"Learning Lua","text":"<p> Neovim Lua introduction</p> <p> Lua.org - Programming in Lua (first edition)</p> <p> Codecademy - learn lua course</p>"},{"location":"reference/lua-language/#reference","title":"Reference","text":"<p> Lua.org 5.4 Reference Manual</p>"},{"location":"reference/neovim/","title":"Neovim Reference","text":"<ul> <li>Language Providers</li> <li>Key mappings</li> </ul>"},{"location":"reference/neovim/language-providers/","title":"Language Providers","text":"<p>Neovim delegates some features to language providers.</p> <p><code>:checkhealth</code> command in Neovim shows if the binaries and tools required by each provider are available in the operating system.</p> <p>Resolve the issue with providers that generate a warning in the checkhealth report, following the ADVICE steps provided.</p>"},{"location":"reference/neovim/language-providers/#disable-language-providers","title":"Disable Language Providers","text":"<p>If a language is not used with Neovim, then its provider can be disabled.  Details on how to disable a provider are included at the end of the ADVICE in the report section for that provider.</p> <p></p> <p>Disable language providers in the <code>init.lua</code> configuration file</p> init.lua<pre><code>-- Disable Language providers\nvim.g.loaded_node_provider = 0       --- (1)!\nvim.g.loaded_perl_provider = 0\nvim.g.loaded_python3_provider = 0\nvim.g.loaded_ruby_provider = 0\n</code></pre> <ol> <li>Example configuration to disable providers is provided in the practicalli/neovim-config-redux configuration</li> </ol> <p>Ignore Language Provider warnings</p> <p>If the programming language is not used, there are no issues with using Neovim if the warnings are simply ignored</p>"},{"location":"reference/neovim/standard-path/","title":"Neovim Standard Path","text":"<p>View the standard paths used by Neovim using the help menu</p> <pre><code>:help standard-path\n</code></pre> <p>Output of command</p> <pre><code>Standard Paths                  *standard-path*\n\nNvim stores configuration, data, and logs in standard locations. Plugins are\nstrongly encouraged to follow this pattern also. Use |stdpath()| to get the\npaths.\n\n                        *base-directories* *xdg*\nThe \"base\" (root) directories conform to the XDG Base Directory Specification.\nhttps://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html\nThe $XDG_CONFIG_HOME, $XDG_DATA_HOME, $XDG_RUNTIME_DIR, and $XDG_STATE_HOME\nenvironment variables are used if defined, else default values (listed below)\nare used.\n\nCONFIG DIRECTORY (DEFAULT) ~\n                  *$XDG_CONFIG_HOME*            Nvim: stdpath(\"config\")\n    Unix:         ~/.config                   ~/.config/nvim\n    Windows:      ~/AppData/Local             ~/AppData/Local/nvim\n\nDATA DIRECTORY (DEFAULT) ~\n                  *$XDG_DATA_HOME*              Nvim: stdpath(\"data\")\n    Unix:         ~/.local/share              ~/.local/share/nvim\n    Windows:      ~/AppData/Local             ~/AppData/Local/nvim-data\n\nRUN DIRECTORY (DEFAULT) ~\n                  *$XDG_RUNTIME_DIR*            Nvim: stdpath(\"run\")\n    Unix:         /tmp/nvim.user/xxx          /tmp/nvim.user/xxx\n    Windows:      $TMP/nvim.user/xxx          $TMP/nvim.user/xxx\n\nSTATE DIRECTORY (DEFAULT) ~\n                  *$XDG_STATE_HOME*             Nvim: stdpath(\"state\")\n    Unix:         ~/.local/state              ~/.local/state/nvim\n    Windows:      ~/AppData/Local             ~/AppData/Local/nvim-data\n\nNote: Throughout the user manual these defaults are used as placeholders, e.g.\n\"~/.config\" is understood to mean \"$XDG_CONFIG_HOME or ~/.config\".\n\nLOG FILE                    *$NVIM_LOG_FILE* *E5430*\nBesides 'debug' and 'verbose', Nvim keeps a general log file for internal\ndebugging, plugins and RPC clients. &gt;\n    :echo $NVIM_LOG_FILE\nBy default, the file is located at stdpath('log')/log unless that path\nis inaccessible or if $NVIM_LOG_FILE was set before |startup|.\n</code></pre>"},{"location":"reference/vim-style/","title":"Reference: Learn Vim-style Editing","text":"<p>Learning vim-style multi-modal editing takes time and practice.  Most importantly this approach can be learned in stages, as insert mode is the same editing experience as using most other editors.</p> <p>Start with the multi-modal concept and the basics of navigation.  Then adopt more normal and visual mode actions, including motions </p>"},{"location":"reference/vim-style/#getting-started","title":"Getting started","text":"<p><code>:Tutor</code> runs the intteractive tutorial built into neovim <code>(:help tutor</code> also runs the tutor)</p> <p>vim adventures isa simple online game to teach you the fundamentals of vim-style editing.</p>"},{"location":"reference/vim-style/#navigation-and-searching","title":"Navigation and searching","text":"<ul> <li>moving the cursor</li> <li>Motions </li> <li>line numbers </li> <li>jumping around a buffer</li> <li>search and replace</li> </ul>"},{"location":"reference/vim-style/#text-wrangling","title":"Text wrangling","text":"<ul> <li>iedit</li> <li>text case</li> </ul>"},{"location":"reference/vim-style/#clojure-editing","title":"Clojure Editing","text":"<p>traversing expressions  structural editing </p>"},{"location":"reference/vim-style/case/","title":"Modifying text case","text":"<p>Convert Characters and regioins to upper or lower case text.</p>"},{"location":"reference/vim-style/case/#toggle-case-with-visual-select","title":"Toggle case with visual select","text":"<p><code>v</code> to visually select a character or use the vim motion keys to select a region</p> <p><code>U</code> to uppercase current character or selected region </p> <p><code>u</code> to lowercase current character or selected region </p> <p><code>~</code> to toggle the case of the text in the selected region</p> <p><code>.</code> will repeat the previous selection size and case toggle</p>"},{"location":"reference/vim-style/case/#toggle-case-menu","title":"Toggle case menu","text":"<p>Toggle the current character using vim motion keys, without needing to select a region.</p> <p><code>g ~</code> opens the toggle case menu</p> <p>TODO: Add screenshot of <code>g ~</code> toggle case menu</p> <p><code>g ~ ~</code> uppercase current line (also works for <code>RET</code> and maybe other none-menu characters, but not <code>SPC</code>)</p>"},{"location":"reference/vim-style/case/#cheatsheet","title":"Cheatsheet","text":"<ul> <li><code>~</code> Changes the case of current character</li> <li><code>guu</code> Change current line from upper to lower.</li> <li><code>gUU</code> Change current LINE from lower to upper.</li> <li><code>guw</code> Change to end of current WORD from upper to lower.</li> <li><code>guaw</code> Change all of current WORD to lower.</li> <li><code>gUw</code> Change to end of current WORD from lower to upper.</li> <li><code>gUaw</code> Change all of current WORD to upper.</li> <li><code>g~~</code> Invert case to entire line</li> <li><code>g~w</code> Invert case to current WORD</li> <li><code>guG</code> Change to lowercase until the end of document.</li> <li><code>gU)</code> Change until end of sentence to upper case</li> <li><code>gu}</code> Change to end of paragraph to lower case</li> <li><code>gU5j</code> Change 5 lines below to upper case</li> <li><code>gu3k</code> Change 3 lines above to lower case</li> </ul>"},{"location":"reference/vim-style/g-menu/","title":"Evil G menu","text":"<p>g` in normal mode opens a menu of convenient utilities.  Practicalli uses this menu to comment existing lines, jumping to top or bottom of the buffer and changing text case.</p>"},{"location":"reference/vim-style/g-menu/#comment-lines-and-regions","title":"Comment lines and regions","text":"<p><code>g c c</code> will comment the current line using the buffer major mode comment character(s).  A prompt will ask if no comment character is set for the major mode.</p> <p><code>g c</code> with a selected region will comment all lines with the major mode comment character(s)</p>"},{"location":"reference/vim-style/g-menu/#jumping-around","title":"Jumping around","text":"<p><code>g g</code> jumps to the top of the buffer, <code>g G</code> to the bottom of the buffer</p> <p><code>g d</code> to jump to the source code of a function definition, <code>g D</code> to open that in a different window.</p> <p><code>g f</code> to jump to file name under cursor (if file exists).</p>"},{"location":"reference/vim-style/g-menu/#changing-text-case","title":"Changing text case","text":"<p><code>g u</code> to change the current character or selection to lowercase, <code>g U</code> for uppercase.</p> <p>Toggle case with <code>~</code></p> <p><code>~</code> will toggle the case of the current character or selected region.</p>"},{"location":"reference/vim-style/key-binding-reference/","title":"Evil Keybinding Reference","text":"<p>An alphabetically ordered reference of Vim-style key bindings.</p>"},{"location":"reference/vim-style/key-binding-reference/#normal-mode-keybindings","title":"Normal mode keybindings","text":"<p>Keybindings available in Evil normal mode and the resultant state they leave you in.</p> Keybinding Description State <code>@</code> execute keyboard macro (defined by <code>q</code>) Normal <code>'</code> jump to mark (defined by <code>m</code>) Normal <code>a</code> append text after cursor Insert <code>a</code> append text after cursor Insert <code>A</code> append text to end of sentence Insert <code>b</code> move cursor back to start of previous word Normal <code>B</code> move cursor back to start of last word Normal <code>c</code> change (use with modifier) Insert <code>C</code> change rest of sentence Insert <code>d</code> delete (use with modifier) Normal <code>D</code> delete rest of sentence Normal <code>e</code> end of word Normal <code>E</code> end of word  (seems same as above) Normal <code>f</code> find character forward (type character) Normal <code>F</code> find character backward (type character) Normal <code>fd</code> Escape (press almost together) Normal <code>g</code> go menu Normal <code>G</code> Jump to end of buffer Normal <code>h</code> move cursor left Normal <code>H</code> move cursor to top of buffer Normal <code>i</code> insert text Insert <code>I</code> insert text at start of sentence Insert <code>j</code> Move cursor down a line Normal <code>J</code> Join next line to end of current Normal <code>k</code> Move cursor up a line Normal <code>K</code> <code>spacemacs/evil-smart-doc-lookup</code> Normal <code>l</code> Move cursor right Normal <code>L</code> Move cursor to bottom of buffer Normal <code>m</code> Create marker (next character is marker name) Normal <code>M</code> Jump to middle of buffer Normal <code>n</code> Next search occurrence Normal <code>N</code> Previous search occurrence Normal <code>o</code> New line below Insert <code>O</code> New line above Insert <code>p</code> Paste (after / below cursor) Insert <code>P</code> Paste (before / above cursor) Insert <code>q</code> Record keyboard macro attached to given character Normal <code>Q</code> undefined Normal <code>r</code> Replace character under cursor Normal <code>R</code> Replace character state Replace <code>s</code> Substitute character Insert <code>S</code> Substitute current line Insert <code>t</code> Find character forward - cursor before character Normal <code>T</code> Find character backward - cursor after character Normal <code>u</code> Undo last change (C-R to redo) Normal <code>U</code> Undefined Normal <code>v</code> Visual select Visual <code>V</code> Visual select sentence Visual <code>w</code> Jump cursor to start of next word Normal <code>W</code> Jump cursor to start of next word Normal <code>x</code> Delete character under cursor Normal <code>X</code> Delete character backwards Normal <code>y y</code> Yank (copy) line Normal <code>Y</code> Yank (copy) line Normal <code>z</code> Menu - code folding / keyboard macros Normal"},{"location":"reference/vim-style/motions/","title":"Motions","text":"<p>Todo</p> <p>Moving the cursor around by context rather than individual characters</p>"},{"location":"reference/vim-style/moving-around/","title":"Moving around the cursor","text":"<p>Scrolling is quite inefficient in most editors and moving (jumping) the curor around is far more effective.</p> <p>Using the <code>h</code> <code>j</code> <code>k</code> <code>l</code> as a common part of navigation provides consistency and keeps fingers on the most convienient part of the keyboard.</p>"},{"location":"reference/vim-style/moving-around/#moving-by-charater","title":"Moving by charater","text":"<p><code>h</code> <code>j</code> <code>k</code> <code>l</code> keys move the cursor once character or can be used with numbers to move further.</p> <ul> <li><code>h</code> move left (often used to move up a path or tree, e.g. a directory path)</li> <li><code>j</code> move down</li> <li><code>k</code> move up</li> <li><code>l</code> move right (often used to move down a path or tree, e.g. a directory path)</li> </ul>"},{"location":"reference/vim-style/moving-around/#moving-with-numbers","title":"Moving with numbers","text":"<p><code>:</code> followed by a number then one of <code>h</code> <code>j</code> <code>k</code> <code>l</code> keys will move the cursor that number in the director of the key.</p> <p><code>3j</code> will move 3 lines down the buffer (or to the end of the fuffer if there are fewer lines remaining)</p> <p>Using Relative line numbers showws how far each line is from the current line.  The practicalli/neovim-config sets <code>:relativenames true</code> in <code>fnl/config/init.fnl</code>.</p> <p><code>42l</code> moves 42 charaters to the right</p> <p>moving by motions avoids the need to count characters</p>"},{"location":"reference/vim-style/moving-around/#moving-around-the-buffer","title":"Moving around the buffer","text":"<p><code>g g</code> to jump to the top of the current buffer </p> <p><code>G</code> to jump to the bottom of the buffer</p> <p><code>z z</code> moves the current line and cursor to the middle of the window</p> <p><code>z t</code> moves the current line and cursor to the top of the window</p> <p><code>z t</code> moves the current line and cursor to the bottom of the window (or as far as the buffer will move in the window)</p>"},{"location":"reference/vim-style/narrowing/","title":"Narrowing","text":"<p>Narrowing to a region enables vim commands to be applied to a specific part of the current buffer, rather than the whole buffer.</p> <p>Common examples include - replacing local variables within a specific function (avoiding affecting other function definitions)</p>"},{"location":"reference/vim-style/narrowing/#nrrwrgn-plugin","title":"NrrwRgn plugin","text":"<p>[NrrwRgn plugin] is inspired by the Narrowing feature of Emacs  and means to focus on a selected region while making the rest inaccessible. </p> <p><code>SPC n r</code> opens a select region in a new split window.  The original buffer is protected from changes. </p> <p><code>:w</code> to write changes in the narrowed window to the original buffer</p>"},{"location":"reference/vim-style/narrowing/#commands","title":"Commands","text":"<p><code>:NR</code>  - Open the selected region in a new narrowed window <code>:NW</code>  - Open the current visual window in a new narrowed window <code>:WR</code>  - (In the narrowed window) write the changes back to the original buffer. <code>:NRV</code> - Open the narrowed window for the region that was last visually selected. <code>:NUD</code> - (In a unified diff) open the selected diff in 2 Narrowed windows <code>:NRP</code> - Mark a region for a Multi narrowed window <code>:NRM</code> - Create a new Multi narrowed window (after :NRP) - experimental! <code>:NRS</code> - Enable Syncing the buffer content back (default on) <code>:NRN</code> - Disable Syncing the buffer content back <code>:NRL</code> - Reselect the last selected region and open it again in a narrowed window</p> <p>Appending <code>!</code> to most commands opens the narrowed part in the current window instead of a new window. </p> <p><code>:WR!</code> closes the narrowed window in addition to writing to the original buffer.</p>"},{"location":"reference/vim-style/narrowing/#documentation","title":"Documentation","text":"<p><code>:help NarrowRegion</code> to view the documetation on the NrrwRgn plug use</p>"},{"location":"reference/vim-style/narrowing/#attention","title":"Attention","text":"<p><code>:NRM</code> is described as experimental by the project readme.</p>"},{"location":"reference/vim-style/speaking-vim/","title":"Learning to speak Vim","text":"<p>Neovim is easier to learn and gain much more benefit from if you learn to speak commands as sentences.</p> <p>First learn some verbs:</p> <ul> <li><code>c</code> change </li> <li><code>d</code> delete</li> <li><code>g</code> go, </li> <li><code>v</code> visual select </li> <li><code>y</code> yank (copy)</li> </ul> <p>Then use those verbs with some modifiers</p> <ul> <li><code>'</code> mark </li> <li><code>{ }</code> beginning/end of paragraph</li> <li><code>0</code> start of line</li> <li><code>^</code> first non white-space character of line</li> <li><code>$</code> end of line</li> <li><code>a</code> around</li> <li><code>f</code> find (includes character)</li> <li><code>i</code> inside a range (e.g. word, paren,)</li> <li><code>s</code> surround </li> <li><code>t</code> till (move just before specified character)</li> </ul> <p>Then learn the text objects you can apply verbs and modifiers too</p> <ul> <li><code>b</code> block/parentheses</li> <li><code>p</code> paragraph, </li> <li><code>s</code> sentence  </li> <li><code>t</code> tag e.g. html/xml </li> <li><code>w</code> word</li> </ul>"},{"location":"reference/vim-style/speaking-vim/#examples-of-speaking-vim","title":"Examples of speaking Vim","text":"<p>Practice speaking evil with these examples</p> Keybinding Description <code>c i s</code> change inside current sentence (change the whole sentence) <code>c i \"</code> change inside double quotes <code>c f )</code> change from cursor to next <code>)</code> character <code>c s ' \"</code> change by the surrounding single quotes with double quotes <code>c t X</code> change till the character <code>X</code> (not including <code>X</code>) <code>c /foo</code> change until the first search result of \u2018foo\u2019 <code>d d</code> delete current line <code>D</code> delete current line from cursor onward <code>d i w</code> delete inside the current word (delete word) <code>v t SPC</code> visual select till the next <code>Space</code> character <code>v s ]</code> visually select and surround with <code>[]</code> without spaces <code>v s [</code> as above with <code>[ ]</code> with spaces between parens and content <code>g v</code> go to last visual selection (select last visual selection) <code>v a p</code> visually select around current paragraph <code>v i w S \"</code> visually select, insert around current word, and surround with quotes <code>y y</code> yank (copy) current line <code>y w</code> yank (copy) current word <code>y @ a</code> yank (copy) to mark <code>a</code> (<code>m a</code> creates a mark called <code>a</code>)"},{"location":"reference/vim-style/vim-quick-reference/","title":"Neovim Quick Reference","text":"<p>A reference of the most common keybindings available in Vim Normal mode. Spacemacs DOCUMENTATION key bindings section contains full details</p> <p><code>.</code> repeats the last keybinding sequence used in Vim Normal mode or a change made within a complete Vim Insert session.</p>"},{"location":"reference/vim-style/vim-quick-reference/#moving-around","title":"Moving around","text":"<p>In Normal mode you can keep your fingers resting on the main row of your keyboard to move around.</p> Key action <code>j</code> move cursor down one line <code>k</code> move cursor up one line <code>l</code> move cursor right one character <code>h</code> move cursor left one character <p>In menus such as helm you can move around using <code>Ctrl</code> and these keybindings.  So <code>C-j</code> will move the cursor down one item in a menu.</p>"},{"location":"reference/vim-style/vim-quick-reference/#navigating-the-current-line","title":"Navigating the current line","text":"Key Action <code>f</code> to next character (you specify) <code>t</code> to just before the next character <code>;</code> repeat <code>f</code> or <code>t</code> search <code>w</code> start of next word <code>W</code> start of next word, white space delimited <code>e</code> end of current word <code>b</code> start of previous word <code>W</code> end of next word, white space delimited <code>*</code> to next matching symbol name <code>$</code> end of current line <code>0</code> start of current line <code>^</code> start of non-whitespace <code>%</code> jump to matching parens or next closed paren"},{"location":"reference/vim-style/vim-quick-reference/#navigating-the-current-buffer","title":"Navigating the current buffer","text":"Key action <code>gg</code> start of buffer <code>G</code> end of buffer <code>H</code> move cursor to head of buffer <code>M</code> move cursor to middle of buffer <code>L</code> move cursor to bottom line of buffer <code>C-u</code> jump up half a page <code>C-d</code> jump down half a page <code>}</code> move cursor forward by paragraph or block <code>{</code> move cursor backward by paragraph or block <code>ma</code> mark a line in a file with marker \"a\" <code>`a</code> after moving around, go back to the exact position of marker \"a\" <code>'a</code> after moving around, go back to line of marker \"a\" <code>:marks</code> view all the marks <code>''</code> go to the last place you were <code>[{</code> jump back to the \"{\" at the beginning of the current code block <code>C-o</code> jump back to previous cursor location (<code>evil-jump-backwards</code>) <code>C-i</code> Go to newer position in jump list (opposite of <code>C-o</code>) <code>: 4</code> go to line 4"},{"location":"reference/vim-style/vim-quick-reference/#text-editing","title":"Text Editing","text":"<p>The following commands put you into the Evil Insert state</p> Key Action <code>i</code> insert state at cursor <code>I</code> insert state at start of line <code>a</code> append - insert state after cursor <code>A</code> append - insert state at end of line <code>o</code> new line after cursor <code>O</code> new line before cursor"},{"location":"reference/vim-style/vim-quick-reference/#return-to-normal-state","title":"Return to Normal state","text":"<p>Regularly switch back to normal state should become common practice.  As soon as you finish typing some new text, it should become second nature to go back to normal state.</p> <p><code>ESC</code> or press <code>fd</code> keys in extremely quick succession.</p> <p><code>fd</code> shortcut for Esc</p> <p>Using <code>f d</code> together is low risk as if you dont get it right it will either add the characters or try find the next <code>d</code> character (as <code>f</code> moves to the next character). Keep trying this key combination as once in normal state you can use <code>u</code> to undo any <code>f d</code> characters inserted.</p>"},{"location":"reference/vim-style/vim-quick-reference/#copy-cut-paste-undo-redo","title":"Copy, cut, paste, undo, redo","text":"<p><code>v</code> in Vim normal mode changes to Visual select mode.  Use the navigation keys or any other movement keys to select text to copy or cut.</p> Key Action <code>y</code> copy (yank) selection and add to kill ring <code>x</code> delete character at point and add to kill ring <code>X</code> delete character before point and add to kill ring <code>p</code> paste (put) <code>u</code> undo <code>Ctrl-r</code> redo <p>Undo tips</p> <p>Undo will revert the last action in normal mode or all the changes you made in insert state</p>"},{"location":"reference/vim-style/vim-quick-reference/#replace-and-changing-text","title":"Replace and changing text","text":"Key Action <code>r</code> replace the character under cursor <code>R</code> replace multiple characters until <code>ESC</code> <code>cw</code> change word from cursor to end <code>4 c w</code> change 4 words <code>v (select) c</code> change region <code>v (select) d</code> delete region <code>v i w c</code> change current word <code>v i d</code> delete current word <code>d w</code> delete from cursor to end of word <code>C</code> change from cursor to end of line <code>D</code> , <code>d $</code> delete from cursor to end of line"},{"location":"reference/vim-style/vim-quick-reference/#delete-commands","title":"Delete commands","text":"Key Action <code>de</code> delete to end of word, not including space <code>dw</code> delete to end of word, including space <code>d$</code> delete to end of line <code>dd</code> delete the current line <code>4 d w</code> delete 4 words <code>4 d $</code> delete 4 lines to end <code>dt</code> delete to a character (not including character) <code>dab</code> delete a whole block / expression <code>dib</code> delete contents of a block / expression <code>cab</code> change all the block / expression <code>cib</code> change inner block contents / expression <code>yab</code> yank all block / expression <code>yib</code> yank inner block contents / expression"},{"location":"reference/vim-style/vim-quick-reference/#repeat-commands","title":"Repeat commands","text":"Key Action <code>.</code> repeat last command again <code>&lt;number&gt; &lt;cmd&gt;</code> repeat command a number of times <p>The <code>.</code> keybinding will repeat the last command in normal mode or the last text edit in insert mode.</p> <p>Type a number before a command and that command will run that number of times.</p> <p>Inserting a comment border</p> <p>Use the number repeat to create a border of 42 <code>;</code> characters.</p> <p>Type <code>42</code> to repeat the command 42 times</p> <p>Press <code>i</code> for insert mode</p> <p>Press <code>;</code> as the character to repeat insert</p> <p>Press <code>ESC</code> or <code>fd</code> to leave insert mode and insert all 42 <code>;</code> characters</p>"},{"location":"reference/vim-style/vim-quick-reference/#transposing-swap","title":"Transposing / swap","text":"Key Description <code>x p</code> transpose the current character with the next character"},{"location":"reference/vim-style/vim-quick-reference/#comments-works-for-all-major-modes","title":"Comments - works for all major modes","text":"<p><code>g c c</code> to comment out the current line</p> <p><code>g c</code> to comment out the currently selected region</p> <p>To comment multiple lines you can use the repeat command style, especially useful if you are using relative line numbers.</p> <p><code>g c 3 j</code> will comment the current line and the following two lines below.  Comment in reverse using <code>g c 3 k</code>.</p> <p>In Visual state, <code>v</code>, select the lines you wish to comment and use <code>g c</code> to comment all the marked lines.  Partially marked lines are not commented.</p>"},{"location":"reference/vim-style/vim-quick-reference/#managing-files","title":"Managing Files","text":"<p>Files in practicalli/neovim-config can be managed with Telescope plugin, although the neovim commands can also be used</p> <p><code>SPC p t</code> toggles a visual file explorer on as a leftmost window, providing a further way to navigate files and directories.</p> Key Description <code>SPC f f</code> find existing file (from current local root of neovim) <code>SPC f /</code> copy file - save current buffer with a new file name <code>SPC f b</code> browse files - <code>Esc</code> to run commands <code>SPC f b Esc r</code> change file name of current buffer <p>Telescope file browser opens in Insert mode to allow typing filenames, to narrow the results in the Telescope popup.</p>"},{"location":"reference/vim-style/vim-quick-reference/#telescope-browser-commands","title":"Telescope browser commands","text":"<p><code>SPC f b</code> opens telescope browser which allows commands to be run over the current file or directory.</p> <p><code>Esc</code> swiches the Telescope popup to normal mode, allowing commands to be used</p> <ul> <li><code>c</code> create file / directory  (any missing parts of a path are created)</li> <li><code>r</code> rename a file / directory</li> <li><code>R</code> replace</li> </ul> <p><code>TAB</code> selects files and directories, allowing for commands (i.e. rename) to be done in batch mode (acting on all selected files / directories)</p>"},{"location":"reference/vim-style/vim-quick-reference/#working-with-buffers","title":"Working with Buffers","text":"<p>To work with files in Neovim they are loaded into a Buffer.</p> <p>Buffers are displayed in a window and you can change the window to show any of the current buffers.</p> <p><code>SPC b</code> displays the buffer menu and the most common commands include:</p> Key Command Description <code>SPC b b</code> :Telescope buffers List current buffers <code>SPC b d</code> :bdelete Kill current buffer <code>SPC b n</code> :bnext Switch to next buffer <code>SPC b p</code> :bprevious Switch to previous buffer <code>SPC b a</code> :ball Switch to previous buffer"},{"location":"reference/vim-style/vim-quick-reference/#quit-or-restart-emacs","title":"Quit or Restart Emacs","text":"<p>I recommend using the Spacemacs menu from normal mode to quit / restart Spacemacs.</p> Key Action <code>SPC q a</code> Quit Neovim (blocked if unsaved change in buffers) <code>SPC q q</code> Quit buffer (blocked if unsaved change in buffers) <code>SPS q Q</code> Force quit of Neovim"},{"location":"reference/vim-style/vim-quick-reference/#external-commands","title":"External commands","text":"<p>run external commands using <code>:!</code> followed by a command.  For example:</p> <p><code>:!ls</code> - run the <code>ls</code> command</p>"},{"location":"reference/vim-style/vim-tips-for-developers/","title":"Vim editing for Clojure developers","text":"<p>Vim keybindings that drive Vim editing tools that are common for developers</p>"},{"location":"reference/vim-style/vim-tips-for-developers/#comments-and-commenting-code","title":"Comments and Commenting code","text":"<ul> <li><code>g c c</code>  comment line</li> <li><code>g c c</code>  comment line</li> <li><code>v (select) g c</code>  comment region</li> <li><code>g c 9 j</code>  comment 9 lines from current, downwards</li> </ul>"},{"location":"reference/vim-style/vim-tips-for-developers/#simulated-structural-editing-with-surround","title":"Simulated structural editing with surround","text":"Keybinding Description <code>v s ]</code> surround with [characters] without spaces <code>v s [</code> surround with [ characters ] without spaces <code>c s ( [</code> change surrounding from ( to [ <code>c i (</code> change in ( <code>c a (</code> change \u201caround\u201d ( <code>%</code> jump forwards to next paren, further <code>%</code> toggles between open and close parens. <code>x p</code> transpose characters (cut current, paste after)"},{"location":"reference/vim-style/vim-tips-for-developers/#moving-around-quickly","title":"Moving around quickly","text":"<p><code>f</code> to jump forward to a given character on the current line. <code>F</code> to jump backwards.</p> <p><code>zt</code>, <code>zz</code>, and <code>zb</code> to pull the current line to the top/middle/bottom of the screen.</p> <p><code>[number] G</code> jump to line number or <code>:22</code> to jump to line 22</p> <p><code>:7j</code> to jump 7 lines down</p> <p><code>gf</code> jump to file name under the cursor - try this in the summary.md file</p>"},{"location":"reference/vim-style/vim-tips-for-developers/#selection-find-and-replace","title":"Selection, find and replace","text":"<p><code>viw</code> to visual-select in (within) the current word </p>"},{"location":"reference/vim-style/vim-tips-for-developers/#source-code-and-configuration-files","title":"Source code and configuration files","text":"<p><code>g D</code>open definition in another window</p> <p><code>=</code> (code-aware indenting) operator. Nice with the <code>ap</code> (a paragraph) text object.</p> <p><code>C-]</code> Jump to definition of keyword under the cursor</p>"},{"location":"reference/vim-style/vim-tips-for-developers/#code-folding","title":"code folding","text":"<p><code>zc</code> and <code>zo</code> are useful to close and open folds, which can be a nice way of focusing on certain pieces of code.</p>"},{"location":"reference/vim-style/vim-tips-for-developers/#transposing-characters-and-sections","title":"Transposing characters and sections","text":"<p><code>x p</code>  simple transpose of the current and next character</p> <p><code>M-t</code> transpose words before and after cursor position</p> <p><code>{</code>, <code>}</code> motions jump to next and previous empty lines.  This motion makes it simple to rearrange paragraphs</p> <p><code>{ d }</code> will kill the paragraph (or multiple paragraphs)</p> <p><code>{</code> will jump to the start of the previous paragraph</p> <p><code>p</code> pastes the killed paragraph before the current paragraph</p> <p><code>&gt;</code> and <code>&lt;</code> (indent and dedent) operators, useful with the aforementioned <code>}</code>/<code>{</code> motions.</p> <p>/ ## multi-replace with iedit and narrowing /</p>"},{"location":"reference/vim-style/visual-select/","title":"Visual Select","text":"<p>Select characters, words, lines and regions with visual select.  The background changes color to visually indicate which text is selected</p> <p><code>v</code> enters visual select mode and can be with objects such as word <code>w</code> and locations such as end of line <code>$</code>.</p> <p><code>o</code> to expand from left side of selection and <code>O</code> to expand from the right side of a selection, using the <code>hjkl</code> navigation keys</p>"},{"location":"reference/vim-style/visual-select/#visual-line-selection","title":"Visual Line selection","text":"<p><code>V</code> to select by lines, using <code>j</code> and <code>k</code>.</p>"},{"location":"reference/vim-style/z-menu/","title":"Evil Z menu","text":"<p><code>z</code> in normal mode opens a menu of convenient utilities</p>"},{"location":"reference/vim-style/z-menu/#folding-code-comments-and-other-content","title":"Folding code, comments and other content","text":"<p>Code folding is very useful for hiding different levels of detail, for example you could hide everything but the function names in a namespace, showing just the API for that namespace.</p> <p>Comments and documentation can be folded to help you focus on a specific part of the content.</p> Key Description <code>z a</code> toggle fold of code, comment, section, etc. <code>z A</code> toggle all folds <code>z c</code> close fold <code>z f</code> create fold <code>z M</code> close all folds <code>z o</code> open fold <code>z O</code> open fold recursive (capital o) <code>z r</code> fewer folds <code>z R</code> open all folds <code>z x</code> update folds <p>See narrowing for a focused approach to editing.</p>"},{"location":"reference/vim-style/z-menu/#scrolling","title":"Scrolling","text":"<p>Jump the current line to the center, top or bottom of the buffer.</p> Key Description <code>z b</code> scroll the current line to bottom of buffer <code>z t</code> scroll the current line to top of buffer <code>z z</code> scroll the current line to center of buffer"},{"location":"reference/vim-style/z-menu/#spelling","title":"Spelling","text":"<p><code>z =</code> with the cursor on a word shows a list of possible spelling and similar words.</p> <p>Select a word using its number in tye list to repace the word under the cursor, or <code>q</code> to quit the spelling list.</p> Key Description <code>z =</code> spelling suggestions <code>z g</code> add word to spelling list <code>z w</code> mark word as misspelled"},{"location":"repl-driven-development/","title":"REPL Driven Development with Clojure","text":"<p>Conjure provides the REPL driven development workflow for Clojure (and many other fun languages) and includes a built-in tutorial.</p> <ul> <li>Vim style Editing</li> <li>Starting a REPL &amp; Evaluating code - using Conjure</li> <li>Structural Editing - parinfer or paredit</li> <li>Refactor tools - Language Server Protocol features</li> <li>Unit Testing - run REPL or external test runners</li> <li>Inspecting data, e.g.  Portal</li> </ul> <p>Practicalli Clojure CLI Config</p> <p> Practicalli Clojure CLI config contains aliases used extensively through the Clojure sections of this book</p> Practicalli Neovim config replaces some key bindings <p>practicalli/neovim-config-redux replaces several key bindings to make them consistent with other Clojure editors</p>"},{"location":"repl-driven-development/#references","title":"References","text":"<ul> <li>Which Clojure CLI execution option - M T X P - should be used</li> <li>Make task to simplify Clojure development</li> </ul>"},{"location":"repl-driven-development/conjure/","title":"Conjure","text":"<p>Conjure is the Clojure REPL client for Neovim.  Code in source code buffers can be evaluated and show the results in-line, providing instant feedback on the behaviour of the code as it develops.</p> <p>Conjure School interative tutorial</p> <p><code>:ConjureSchool</code> runs an interactive tutorial in Neovim, walking through the essential Conjure commands and key bindings. Use the commands provided to move through the guide or j / k to scroll through the guide content.</p>"},{"location":"repl-driven-development/conjure/#start-repl","title":"Start REPL","text":"<p>Start a REPL on the command line in the root of a Clojure project.  The REPL should also start an nREPL server for Conjure to connect too.</p> <p>Conjure will detect an nREPL server (via <code>.nrepl-port</code> file) when a Clojure file is opended (.clj .edn .cljs .cljc) and connect to the REPL process via that nREPL server.</p> Practicalli Clojure CLI ConfigManual Alias definition <p> Practicalli Clojure CLI config contains aliases to  start a REPL process that also start an nREPL server.</p> <p>Use <code>repl</code> make task for projects created by  Practicalli Project templates</p> <pre><code>make repl\n</code></pre> <p>Or use the Clojure CLI command with the <code>:repl/rebel</code> alias directly</p> <pre><code>clojure -M:repl/rebel\n</code></pre> Simplify the command line <p>Add a <code>Makefile</code> to define common tasks to simplify and add consistency to working with Clojure across projects  or shell script to simplify the commands used to call <code>clojure</code> to run common tasks</p> <pre><code>repl:  ## Run Clojure REPL with rich terminal UI (Rebel Readline)\n    $(info --------- Run Rebel REPL ---------)\n    clojure -M:env/dev:env/test:repl/rebel\n\n\nrepl-reloaded:  ## Run Clojure REPL with hotload, reload and rich terminal UI (Rebel Readline)\n    $(info --------- Run Rebel REPL ---------)\n    clojure -M:env/dev:env/test:lib/reloaded:repl/rebel\n</code></pre> <p>A <code>Makefile</code> can also include supporting commands, such as lint and format tools.</p> <pre><code># Run MegaLinter with custom configuration\nlint:\n    $(info --------- MegaLinter Runner ---------)\n    mega-linter-runner --flavor java --env 'MEGALINTER_CONFIG=.github/linters/mega-linter.yml'\n</code></pre> <p>practicalli/dotfiles/Makefile contains tasks for Clojure development, including running a REPL, preparing dependencies, building an uberjar, lint &amp; format Clojure and configuration files.</p> <p>Docker related tasks to build, run and compose common images and containers are also included.</p> <p>Add aliases to the user configuration for Clojure, e.g. <code>XDG_HOME_CONFIG/clojure/deps.edn</code> or <code>HOME/.clojure/deps.edn</code> <pre><code>  ;; Interactive client REPL with nREPL server for Clojure Editor support\n  :repl/basic\n  {:extra-deps {nrepl/nrepl       {:mvn/version \"1.0.0\"}\n                cider/cider-nrepl {:mvn/version \"0.40.0\"}}\n   :main-opts  [\"--main\" \"nrepl.cmdline\"\n                \"--middleware\" \"[cider.nrepl/cider-middleware]\"\n                \"--interactive\"]}\n\n  ;; Headless REPL with nREPL server for Clojure Editor support\n  :repl/headless\n  {:extra-deps {nrepl/nrepl       {:mvn/version \"1.0.0\"}\n                cider/cider-nrepl {:mvn/version \"0.40.0\"}}\n   :main-opts  [\"--main\" \"nrepl.cmdline\"\n                \"--middleware\" \"[cider.nrepl/cider-middleware]\"]}\n</code></pre></p> <p><code>clojure -M:repl/basic</code> starts a REPL with nREPL with a minimal REPL UI</p> <p><code>clojure -M:repl/headless</code> starts a REPL with nREPL server but without a REPL prompt (to prevent accidental interaction via the command line)</p> <p>Practicalli Clojure CLI Config aliases</p> <p> Practicalli Clojure CLI config defines aliases for a wide range of community tools and libraries that extend the features of Clojure CLI</p>"},{"location":"repl-driven-development/conjure/#evaluation","title":"Evaluation","text":"<p>Clojure REPL workflow encourages code expressions to be evaluated as the are written, providing instant feedback to ensure expected results are returned (or learn the kind of results a function returns).</p> <p>Results of evaluating an expression are shown in-line.  Open the REPL log to see larger results and a complete REPL history for the current session.</p> <p><code>,eb</code> - evaluate current buffer - used after first starting the REPL to load in a whole namespace and any required namespaces. Use to ensure all changes have been evaluated in the REPL (except those within a <code>(comment )</code> form or otherwise commented)</p> <p><code>,er</code> - evaluate top-level expression (root), ignoring a surrounding <code>(comment )</code> form to support the rich comments approach</p> <p><code>,ee</code> - evaluate expression (from start of current form) - especially useful for nested forms</p> <p><code>,ei</code> - interrupt evaluation (stop long running evaluations) - stop a long running evaluation</p> <p><code>,ew</code> - evaluate word (symbol) - inspect value of form - i.e. for def names</p> <p><code>,e!</code> - replace form with its result - helps understand a more complex function by replacing code with a specific value</p> <p><code>,emf</code> - evaluate marked form - mark forms regularly re-evaluted with <code>mf</code> (or any character with <code>m</code>) to avoid jumping to that form each time . A capital letter to mark form in a different namespace and evaluate  from the current buffer. </p> <p><code>\"cp</code> - paste contents of the register into buffer. The result of every evaluation is stored in a Neovim register as well as the log.</p>"},{"location":"repl-driven-development/conjure/#repl-log","title":"REPL log","text":"<p>The Conjure REPL log shows the results of every evaluation for the current session.</p> <p><code>,lt</code> opens log in a new tab page (tab), <code>,ls</code> in horizontal split, <code>,lv</code> in vertical tab</p> <p><code>,lq</code> - close log window / tab page</p> <p><code>,lr</code> - soft REPL reset, leave window open</p> <p><code>,lR</code> - hard REPL reset, close window &amp; delete buffer</p> <p>Inline evaluation over HUD log popup</p> <p> Practicalli Neovim configurations hide the HUD log popup that is otherwise shown when Conjure connects to the REPL process, i.e. <code>vim.g[\"conjure#log#hud#enabled\"] = false</code></p> <p>In-line evaluation results are the main feedback approach used by Practicalli when evaluating code.</p> <p>Practicalli recommends using the REPL log when larger results are returned</p> <p>Portal data inspector can be sent evaluation history and provides rich visualisation and navigation tools to explore that history in detail.</p>"},{"location":"repl-driven-development/conjure/#rich-comments","title":"Rich comments","text":"<p>Rich comments are a useful way to contain experimental expressions, or expresisons only evaluated directly by a person developing the code (e.g. starting / stoping services, testing api calls, etc.)</p> <p>Expressions in rich comments are not included when evaluating the buffer or when expressions are evaluated via a namespace require.</p> <p><code>,er</code> to evaluate the top level form within the rich comment, without evaluating the comment expression itself.</p> Start REPL from Neovim <p>Practicalli Configurations require the  vim-jack-in plugin to be added before this approach will work.</p> <p>Start Neovim with a Clojure file, e.g. <code>nvim src/practialli/playground.clj</code> or run <code>nvim</code> and open a Clojure file, e.g. <code>*.clj</code>, <code>*.cljc</code>, <code>*.cljs</code> or <code>.edn</code>.</p> <ul> <li><code>:Clj</code> command to start a REPL using Clojure CLI Tools</li> <li><code>:Lein</code> command to start a REPL using Leiningen</li> </ul> <p>Neovim switches to a terminal state, use <code>C-\\ C-n</code> to leave the terminal state.  Use <code>:N</code> or <code>:previous</code> to switch back to the source code buffer</p> <p><code>, c f</code> to connect to the REPL from Conjure, or simply open a Clojure file.  Automated connection will be added in a future version on Conjure.</p> <p>The <code>vim-jack-in</code> plugin enables Neovim to call out to Clojure tools or Leiningen to start a REPL and connect to it once its started.</p> <p>A full screen REPL log is displayed.  <code>, l q</code> to close the log window and return to the Clojure file. <code>, l v</code> to create a vertical split between code and REPL log, <code>, l s</code> for a horizontal split.</p>"},{"location":"repl-driven-development/refactor-tools/","title":"Refactor tools","text":"<p>Neovim and common plugins provide many text oriented tools useful for refactoring code.</p> <p>Clojure LSP server and Neovim LSP client support use static analysis of the project source code to allow provide common code refactor tools.</p>"},{"location":"repl-driven-development/refactor-tools/#language-server-protocol-lsp","title":"Language Server Protocol (LSP)","text":"<p>Using clojure-lsp server and Neovim Treesitter as an LSP client, code is statically analysed to provide auto-completion data, advanced editing actions such as refactor, live formatting, etc.</p> <p>Function help</p> <p><code>SPC l h</code> or K displays help for the function under the cursor</p> <p>Repeat the key binding to move the cursor to the documentation popup window and use j k to scroll the documentation</p>"},{"location":"repl-driven-development/refactor-tools/#key-maps","title":"Key maps","text":"Practicalli AstroNvim ConfigPracticalli Neovim Config Redux <ul> <li><code>&lt;leader&gt;la</code> code actions (popup with available actions)</li> <li><code>&lt;leader&gt;ld</code> hover diagnostics</li> <li><code>&lt;leader&gt;lD</code> search diagnostics</li> <li><code>&lt;leader&gt;lf</code> format buffer</li> <li><code>&lt;leader&gt;lG</code> search workspace symbols</li> <li><code>&lt;leader&gt;lh</code> function signature help</li> <li><code>&lt;leader&gt;li</code> information about the LSP client and running LSP servers</li> <li><code>&lt;leader&gt;lI</code> null-ls information (format &amp; lint tools)</li> <li><code>&lt;leader&gt;ll</code> code lens refresh</li> <li><code>&lt;leader&gt;lL</code> code lens run</li> <li><code>&lt;leader&gt;lr</code> rename current symbol (namespace rename not supported it seems)</li> <li><code>&lt;leader&gt;lR</code> search references</li> <li><code>&lt;leader&gt;ls</code> search symbols</li> <li><code>&lt;leader&gt;lS</code> symbols outline</li> </ul> <ul> <li><code>gd</code> Go to definition</li> <li><code>K</code> Show documentations</li> <li><code>&lt;leader&gt;ld</code> Function declarations</li> <li><code>&lt;leader&gt;lt</code> Type Definitions</li> <li><code>&lt;leader&gt;lh</code> Signature Help</li> <li><code>&lt;leader&gt;ln</code> Rename</li> <li><code>&lt;leader&gt;le</code> Show line diagnostics</li> <li><code>&lt;leader&gt;lq</code> Show all diagnostics information</li> <li><code>&lt;leader&gt;lf</code> Auto format</li> <li><code>&lt;leader&gt;lj</code> Go to next diagnostic</li> <li><code>&lt;leader&gt;lk</code> Go to previous diagnostic</li> <li><code>&lt;leader&gt;la</code> Open code actions menu (Using telescope plugin interface)</li> <li><code>&lt;leader&gt;la</code> Open code actions menu for the selected text in VISUAL mode (Using telescope plugin interface)</li> <li><code>&lt;leader&gt;lw</code> Open workspace diagnostics list (Using telescope plugin interface)</li> <li><code>&lt;leader&gt;lr</code> Show all references list for item under the cursor (Using telescope plugin interface)</li> <li><code>&lt;leader&gt;lr</code> Show all implementations list for item under the cursor (Using telescope plugin interface)</li> </ul>"},{"location":"repl-driven-development/refactor-tools/#troubleshooting","title":"Troubleshooting","text":"<p>Space l i shows the LSP server information for the current filetype, e.g. Clojure</p> <p> </p>"},{"location":"repl-driven-development/refactor-tools/#limitations-to-investigate","title":"Limitations to investigate","text":"<ul> <li>Neovim client does not seem to support namespace rename (AstroNvim)</li> </ul>"},{"location":"repl-driven-development/structural-editing/","title":"Structural Editing","text":"<p>Structural editing seeks to ensure that parenthesis (parens) and other pairs of characters remain balanced, i.e. an open paren is not removed without removing the closing paren.</p> <ul> <li>parinfer uses an indent approach, aligning code manages parens locations</li> <li>paredit uses a structural approach</li> </ul> AstroNvim Community Clojure Pack includes parinfer <p>nvim-parinfer plugin is included in the AstroNvim Community Clojure pack</p> <pre><code>  { import = \"astrocommunity.pack.clojure\" },\n</code></pre>"},{"location":"repl-driven-development/structural-editing/#parinfer","title":"Parinfer","text":"<p>Parinfer works very well with vim-style modal editing.</p> <p>The author of the code focuses on aligning code and parinfer takes care of balancing the parens.</p> <p>To include new lines of code within an expression, create a new line <code>o</code> and indent.</p> <p>Parinfer will move the preceeding closing paren(s) to the new line, enclosing the new code in the overall expression.</p> <p>Parinfer website </p>"},{"location":"repl-driven-development/testing/","title":"Unit tests and test runners","text":"<p>Run unit tests from within Neovim, showing a summary of test results or a full test report (especially if there are failures)</p> <p>Or run and external test runner via a terminal session, optionally using watch mode to re-run tests on every saved change.</p> Practicalli sets Kaocha test runner as default <p> practicalli/neovim-config-redux sets Kaocha as the default test runner</p> <p>Kaocha test runner set in  Astrocommunity Clojure language pack</p> Astrocommunity Clojure language pack<pre><code>{\n  \"Olical/conjure\",\n  -- load plugin on filetypes\n  ft = { \"clojure\" },\n  init = function()\n    vim.g[\"conjure#log#hud#width\"] = 1\n    vim.g[\"conjure#log#hud#enabled\"] = false\n    vim.g[\"conjure#log#hud#anchor\"] = \"SE\"\n    vim.g[\"conjure#log#botright\"] = true\n    vim.g[\"conjure#extract#context_header_lines\"] = 100\n    vim.g[\"conjure#eval#comment_prefix\"] = \";; \"\n    vim.g[\"conjure#client#clojure#nrepl#connection#auto_repl#enabled\"] = false\n    vim.g[\"conjure#client#clojure#nrepl#connection#auto_repl#hidden\"] = true\n    vim.g[\"conjure#client#clojure#nrepl#connection#auto_repl#cmd\"] = nil\n    vim.g[\"conjure#client#clojure#nrepl#eval#auto_require\"] = false\n    vim.g[\"conjure#client#clojure#nrepl#test#runner\"] = \"kaocha\"\n\n    vim.api.nvim_create_autocmd(\"BufNewFile\", {\n      group = vim.api.nvim_create_augroup(\"conjure_log_disable_lsp\", { clear = true }),\n      pattern = { \"conjure-log-*\" },\n      callback = function() vim.diagnostic.disable(0) end,\n      desc = \"Conjure Log disable LSP diagnostics\",\n    })\n</code></pre>"},{"location":"repl-driven-development/testing/#include-test-path","title":"Include test path","text":"<p>Ensure the <code>test</code> directory is included in the classpath when starting a REPL.  Use a project or user level alias which defines an <code>:extra-paths</code> key with the <code>[\"test\"]</code> path</p> <pre><code>clojure -M:test/env:repl/reloaded\n</code></pre>"},{"location":"repl-driven-development/testing/#conjure-test-runners","title":"Conjure Test runners","text":"<p><code>, t n</code> to run the tests for the current namespace</p> <p><code>, t a</code> to run all tests in the project</p> <p></p>"},{"location":"repl-driven-development/testing/#external-test-runner","title":"External test runner","text":"<p>Open a terminal in Neovim or a separate terminal session to run start a test runner in watch mode.  Tests run automatically when the code changes are saved</p> Practicalli Clojure CLI Config <p> Practicalli Clojure CLI config contains aliases for test runner tools</p> <ul> <li> <p><code>:test/run</code> uses Kaocha to run all tests, stopping on first failing test.  Add <code>:fail-fast? false</code> argument to run all tests regardless of failure</p> </li> <li> <p><code>:test/watch</code> as above and puts Kaocha in watch mode, triggering a test run each time a file is saved</p> </li> </ul> <p>Projects created with Practicalli Project Templates include a <code>test</code> and <code>test-watch</code> task to run Kaocha test runner</p> <p>Run all tests, stoping on first failing test</p> <pre><code>make test\n</code></pre> <p>Watch for changes and run all tests, stoping on first failing test</p> <pre><code>make test-watch\n</code></pre> <p>The make tasks call Clojure CLI with the appropriate alias, e.g. <code>clojure -X:test/run</code> and <code>clojure -X:test/watch</code></p> <p></p>"},{"location":"repl-driven-development/testing/#test-selectors","title":"Test Selectors","text":"<p>Use Test selectors to run a sub-set of tests based on selector meta data added to <code>deftest</code> code</p> <pre><code>(deftest ^:infrastructure function-name-test\n  (testing \"\"\n    (is ,,,))\n\n(deftest ^:persistence function-name-test\n  (testing \"\"\n    (is ,,,))\n</code></pre> Kaocha test runnerCognitect Labs Test Runner <p>Kaocha test runner can focus or skip on a sub-set of unit tests using test id, metadata, namespaces or a specific deftest. </p> <ul> <li><code>:focus</code> or <code>:skip</code> a given namespace or specific test var, i.e. <code>deftest</code> </li> <li><code>:focus-meta</code> or <code>:skip-meta</code> test selectors (metadata) on test vars, i.e. <code>^:persistence</code></li> </ul> <p>Specifying test <code>:id</code> in the <code>tests.edn</code> configuration file allows different test suites to be run, e.g. <code>:unit</code> for unit tests, <code>:spec</code> for specification tests </p> <p>Focus and skip works with a single test run or with a continuous watcher.</p> <p>Skip all tests with :persistence metadata</p> <pre><code>clojure -X:test/watch :skip-meta :persistence\n</code></pre> <p>Focus on a specific test namespace</p> <pre><code>clojure -X:test/watch :focus '[\"practicalli.gameboard.api.scoreboard-test\"]\n</code></pre> <p>Focus on a specific unit test (deftest)</p> <pre><code>clojure -X:test/watch :focus '[\"practicalli.gameboard.api.scoreboard-test/total-score-test\"]\n</code></pre> <p>Refine the tests that are watched</p> <p>Start the watcher with  focused or skiped tests by name or meta data (test selectors)</p> <p>Cognitect Labs Test Runner can include or exclude a sub-set of tests, identified by metadata on the var (<code>deftest</code>)</p> <p>Cognitect Labs Test Runner - inclusions &amp; exclusions </p>"},{"location":"termux/","title":"NeoVim on Termux","text":"<p>A smart phone or tablet and an external keyboard can make an excellent ultra-portable development environment, especially when travelling with limited space or restricted weight constraints.</p> <p>Termux can be installed using the F-Droid marketplace, as with installing any other Android app.</p> <p>Do not install Termux App from the Google Play store</p> <p>The Termux App in Google Play store is significantly out of date and will not work properly and probably not at all</p> <p></p>"},{"location":"termux/#keyboard","title":"Keyboard","text":"<p>Atreus from Keyboardio is an excellent travel keyboard and was used to write most of the Practicalli Neovim configuration and Neovim book (especially during delays at airports)</p> <p>Model 100 from Keyboardio is used by Practicalli at the office </p>"},{"location":"termux/#running-termux","title":"Running Termux","text":"<p>Run Termux from the app launcher added as an android app by the F-Droid install.</p> <p>A help menu will show the basic command needed to work with packages.</p> <p>Software keys for Termux specific controls are shown.  Keys can be toggled with the <code>Volume Up + q</code> key combination.</p> <p></p> <p>Termux may not display in fullscreen when Android productivity mode, usually activated on tablets when physical keyboard or mouse is attached.  Disabling productivity mode in the Android settings is recommended.</p>"},{"location":"termux/clojure-development/","title":"Clojure development environment","text":"<p>A comprehensive development environment for Clojure, supporting a REPL workflow and static analysis of code via Clojure Language Server Protocol.</p>"},{"location":"termux/clojure-development/#java-host-platform","title":"Java host platform","text":"<p>Install OpenJDK to host the Clojure REPL process and run packaged Clojure applications.</p> <p>Java 17 Long Term Support version is recommended as it is very stable, receives security updates and has the latest highly tested performance improvements.</p> <pre><code>pkg install openjdk-17\n</code></pre>"},{"location":"termux/clojure-development/#install-clojure","title":"Install Clojure","text":"<p>Clone practicalli/clojure-deps-edn to add a wide range of community tools to the Clojure CLI</p> <pre><code>git clone git@github.com:practicalli/clojure-deps-edn.git ~/.config/clojure\n</code></pre> <p>Use the Linux install with a prefix path pointing to Termux equivalent of <code>/usr/local</code>.  Find the path using <code>echo $PATH</code> and remove <code>bin</code> from the end.  Without the prefix Clojure will not install correctly</p> <pre><code>curl -O https://download.clojure.org/install/linux-install-1.11.1.1149.sh\n\nchmod +x linux-install-1.11.1.1149.sh\n\n./linux-install-1.11.1.1149.sh --prefix /data/data/com.termux/files/usr/\n</code></pre> <p><code>clojure</code> binary is installed in the existing bin, lib and share directories in <code>/data/..../usr/</code>, placing that binary on the system execution path.</p> <p>Test by running a REPL session, for example with Rebel Readline</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>optionally install rlwrap package if using the basic repl terminal UI</p>"},{"location":"termux/clojure-development/#install-clojure-lsp","title":"Install Clojure LSP","text":"<p>Visit clojure-lsp GitHub releases page and download the <code>clojure-lsp</code> file</p> <ul> <li>visit the relases page in firefox and copy the link to the file.</li> <li>use wget and paste the link to the file to download</li> <li>make executable <code>chmod 755 clojure-lsp</code></li> <li>test locally <code>./clojure-lsp --version</code> - should print clojure-lsp version and clj-kondo version</li> <li>copy or move file to path <code>mv clojure-lsp $PATH</code></li> </ul> <p>If the practicalli/clojure-lsp-config repository was cloned, move or link the <code>clojure-lsp</code> directory to <code>~/.config/clojure-lsp</code></p>"},{"location":"termux/custom-shell/","title":"Customise shell","text":"<p>Customising the shell is optional, although gives an enhanced experience.</p> <p>Zsh provides the richest command line experience, providing many advanced features over bash.  Oh My Zsh is a community configuration that provides a simple way to configure Zsh features and also supports powerline10k terminal theme, providing context specific information and a more engaging visual experience.</p> <p>Oh My Zsh community configuration enhances the Zsh experience.  Practicalli normally uses Prezto community configuration, unfortunately this did not work well on Termux.</p>"},{"location":"termux/custom-shell/#install-zsh","title":"Install Zsh","text":"<p>Install the zsh package using the Termux package manager</p> <pre><code>pkg install zsh\n</code></pre> <p>Start zsh, which will show a <code>%</code> character as the prompt</p> <pre><code>zsh\n</code></pre> <p>Set the shell to run zsh by default</p> <pre><code>chsh -s zsh\n</code></pre>"},{"location":"termux/custom-shell/#install-oh-my-zsh","title":"Install Oh My Zsh","text":"<p>Install Oh My Zsh via curl (or wget if preferred) in the <code>.oh-my-zsh/</code> directory</p> <pre><code>sh -c \"$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)\"\n</code></pre>"},{"location":"termux/custom-shell/#install-powerline10k","title":"Install Powerline10k","text":"<p>Powerline10k is a visually appealing prompt with a setup script to visually choose the presentation of the prompt.</p> <pre><code>git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k\n</code></pre> <p>Edit <code>~/.zshrc</code> and set the theme to <code>ZSH_THEME=\"powerlevel10k/powerlevel10k\"</code></p> <pre><code>nano ~/.zshrc\n</code></pre> <p>Save the changes <code>exit</code> termux.</p> <p>Next time zsh is run, powerline10k setup script will run.  If Meslo is not set as the terminal font, the setup script offers to install the font.  Installing the font will restart Termux (without prompting for a restart).</p> <p>The powerline10k setup script provides a wizard to configure each part of the prompt.</p> <p><code>p10k configure</code> command will manually run the powerline10k setup script.</p> Prezto Zsh community configuration <p>NOTE: previous attempts to use Prezto proved to have issues</p> <p>Clone prezto and its sub-modules into <code>XDG_CONFIG_HOME/zsh</code> which is typically <code>~/.config/zsh</code></p> <pre><code>git clone --recursive https://github.com/sorin-ionescu/prezto.git \"${ZDOTDIR:-${XDG_CONFIG_HOME:-$HOME/.config}/zsh}/.zprezto\"\n</code></pre> <p>Set the location of the Zsh configuration home with <code>$ZDOTDIR</code>, relative to the XDG locations</p> <pre><code>export ZDOTDIR=\"${ZDOTDIR:=$XDG_CONFIG_HOME/zsh}\"\n</code></pre> <p>Create a new Zsh configuration by copying/linking the Zsh configuration files provided:</p> <pre><code>setopt EXTENDED_GLOB\nfor rcfile in \"${ZDOTDIR:-$HOME}\"/.zprezto/runcoms/^README.md(.N); do\n  ln -s \"$rcfile\" \"${ZDOTDIR:-$HOME}/.${rcfile:t}\"\ndone\n</code></pre> <p>Practicalli Zsh configuration</p> <p>Clone practicalli/dotfiles and replace the symbolic links in <code>$XDG_CONFIG_HOME/zsh</code> with links to the respective Zsh configuration files in the cloned repository (or copy the files if you prefer)</p> <p>Copy or create a symbolic like for the <code>.p10k configuration or skip this to create your own configuration when next starting</code>zsh<code>.</code></p> <p>Edit <code>$XDG_CONFIG_HOME/.config/zsh/.zshenv</code> and add the following lines to enable zsh to find the prezto configuration</p> <pre><code>export XDG_CONFIG_HOME=\"${XDG_CONFIG_HOME:=$HOME/.config}\"\nexport ZDOTDIR=\"${ZDOTDIR:=$XDG_CONFIG_HOME/zsh}\"\n</code></pre> <p>Create a symbolic link from <code>$HOME/.zshenv</code> to <code>$XDG_CONFIG_HOME/.config/zsh/.zshenv</code> (or to the .zshenv file from practicalli/dotfiles)</p> <pre><code>ln -s $XDG_CONFIG_HOME/.config/zsh/.zshenv $HOME/.zshenv\n</code></pre> <p>Check the configuration is working by loading the .zshenv configuration</p> <pre><code>source \"$ZDOTDIR/.zshenv\"\n</code></pre> <p>Using Oh My Bash</p> <p>If preferring Bash, then ohmybash provides a nice command line experience, showing completions clearer, nice themes that provide information.</p>"},{"location":"termux/fdroid-install/","title":"Install Termux via the F-Droid App","text":"<p>Visit the FDroid app website and download F-Droid, which saves an F-Droid.apk file.  Android may display a security prompt stating the browser does not have permissions to install software.  The popup should include a configure link that opens the Android settings to allow the browser to install software.</p> <p>F-Droid should now be installed and its icon added to the Android system alongside all other Android apps.</p> <p>Open the F-Droid App and allow it to update its repositories, to ensure the latest list of apps are shown.</p> <p>Search for the Termux application, clicking on the Termux name if more details are required.</p> <p>Select the Install button.</p> <p></p> <p>When installing apps from F-Droid for the first time, a security prompt is show as F-Droid is an unknown source.</p> <p>Select Settings to open the Android settings and enable Allow from this source for the F-Droid app.</p> <p></p> <p>A Termux App launcher will be added to the Android screen.  Consider adding the Termux icon to the commonly used icons bar.</p>"},{"location":"termux/fdroid-install/#termux-styling","title":"Termux Styling","text":"<p>Styling is a Termux plugin that provides a visually richer experience. Styling contains beautiful color schemes and powerline-reaqdy fonts to customise the appearance of the terminal</p> <p>Install the package via F-Droid</p> <p></p> <p>The styling menu is accessed via a long press on the Termux app screen, showing a More &gt; Style option on the usual cut/copy/paste popup menu. Practicalli recommends <code>FiraCode</code> fonts.</p>"},{"location":"termux/git/","title":"Git version control","text":"<p>A Git client is used to version control projects and to clone projects and configuration from GitHub/GitLab.  Practicalli maintains several editor configurations in shared repositories on GitHub</p> <ul> <li>Install a Git Client (and optionally GitHub CLI)</li> <li>[optionally] clone the practicalli/dotfiles repository for the Git config and global ignores</li> <li>Configure an SSH key to access remote repositories (or Developer token if you cannot use SSH keys)</li> </ul>"},{"location":"termux/git/#install-a-git-client-and-github-cli","title":"Install a git client and GitHub CLI","text":"<pre><code>pkg install git gh\n</code></pre> <p>Clone the practicalli/dotfiles repository</p> <pre><code>git clone https://github.com/practicalli/dotfiles projects/dotfiles\n</code></pre> <p>Move or symbolically link the top-level directories to <code>~/.config</code>, e.g. for the Git configuration:</p> <pre><code>ln -s projects/dotfiles/git ~/.config/git\n</code></pre> <p>Edit the <code>.config/git/config</code> and update the <code>core.user</code>,  <code>core.name</code> and <code>github</code> or <code>gitlab</code> identities</p>"},{"location":"termux/git/#create-ssh-key-for-remote-repository-access","title":"Create SSH Key for remote repository access","text":"<p>Install the openssh package which contains the <code>ssh-keygen</code> command to generate a new public/private key combinations for use with GitHub SSH repository URLs</p> <pre><code>pkg install openssh\n</code></pre> <p>Generate a key using the email address of the GitHub or GitLab account</p> <pre><code>ssh-keygen -t rsa -C name@domain.tld\n</code></pre> <p>RET to confirm storing the keys in the default location.</p> <p>Usually a passphrase is recommended, however, termux does not seem to save a keyring to save the key passphrase using <code>ssh-add</code>.  So the passphrase must be entered each time the key is used, unless a blank passphrase is used.</p> <p>Vist your GitHub account settings and create a new SSH key</p> <p>Use <code>cat  ~/.ssh/id_rsa.pub</code> to show the public key contents.  Press the screen to select and copy the public key to the clipboard.</p> <p>Paste the public key into the GitHub new key form.</p>"},{"location":"termux/git/#optional-create-a-developer-token","title":"[optional] Create a developer token","text":"<p>A developer token (or ssh key) is required to access GitHub {and far more secure over password}</p> <p>Should the android device become lost or compromised, the developer token can be deleted to protect the repositories from any malicious access.  The developer token should be limited to the minimal access.  The developer token does not give access to the GitHub or GitLab account.</p> <p>HTTPS URLs should be used with a developer token.  git@git.com URLs are for SSH keys only.</p> <p>Visit GitHub / GitLab settings for your account</p> <p>Create a new developer token specifically for Termux</p> <p>Add a descriptive name for the token, based on the device Termuxc is runniung on, e.g. <code>Termux Pixel2XL</code></p> <p>Check the public_repo and status repo scopes</p> <p>Generate button creates a new token.</p> <p>Copy the token using the copy icon.</p> <p>Edit the <code>.config/git/config</code> file and add a github section with the GitHub account name and token</p> <pre><code>[github]\n    name = practicalli\n    token = ghp_************************************\n</code></pre> <p>Consider using GitHub CLI to cache the developer token rather than write the token to the Git configuration file for greater security.</p>"},{"location":"termux/neovim/","title":"Install neovim","text":"<p>Neovim version 8 availabe as current package</p> <pre><code>pkg install neovim\n</code></pre>"},{"location":"termux/neovim/#neovim-treesitter","title":"Neovim treesitter","text":"<p>Treesitter provides excellent language syntax parsing and highlighting and is a very attractive feature of the recent neovim releases.  Treesitter is a major attraction, bringing in a new audience for Neovim.</p> <p>The <code>nvim-treesitter</code> package is included in the practicalli/neovim-config-redux configuration.</p>"},{"location":"termux/neovim/#c-compiler","title":"C Compiler","text":"<p>Install C compiler for neovim-treesitter, to compile a parser for each specific programming language.</p> <pre><code>pkg install clang\n</code></pre> <p><code>gcc</code> is not packaged for Termux, although there are guides to install gcc if preferred. clang has proved to be capable of creating the parsers used in the Practicalli configuration.</p>"},{"location":"termux/neovim/#searching-files","title":"Searching files","text":"<p>Telescope and other packages that involve searching for files recommend using ripgrep, a highly optomised tool for finding files on the operating system.</p> <pre><code>pkg install ripgrep\n</code></pre>"},{"location":"termux/neovim/#optional-nodejs","title":"[optional] nodejs","text":"<p>Optional.  Only if node.js is required as a Neovim provider and JavaScript or ClojureScript development is to be done.</p> <pre><code>pkg install nodejs\n</code></pre>"},{"location":"termux/setup/","title":"Termux Setup","text":"<p>Launch Termux via its application icon.  A black terminal screen will appear with a bash shell prompt.</p>"},{"location":"termux/setup/#update-packages","title":"Update packages","text":"<p>Check for new packages and update them all</p> <pre><code>pkg upgrade -y\n</code></pre> <p>If you wish to first check the packages that will be updated, use <code>pkg --list-upgradable</code></p> <p>Select a specific region to minimise the number of mirrors checked during package upgrades, especially useful if on a limited data plan.</p> <pre><code>termux-change-repo\n</code></pre> <p></p> <p>At time of writing, the Termux package on F-Droid was around 6 months old so there will be a number of packages that should be updated before any further installation steps are undertaken.</p>"},{"location":"termux/setup/#configure-freedesktoporg-xdg-locations","title":"Configure Freedesktop.org XDG locations","text":"<p>Edit the <code>~/.profile</code> file, adding export directives to set the XDG locations:</p> <pre><code>nano ~/.profile\n</code></pre> XDG locations<pre><code># Common Free desktop.org locations\nexport XDG_CONFIG_HOME=$HOME/.config\nexport XDG_DATA_HOME=$HOME/.local/share\nexport XDG_STATE_HOME=$HOME/.local/state\nexport XDG_CACHE_HOME=$HOME/.cache\n\n# Set XDG location of Emacs Spacemacs configuration\nexport SPACEMACSDIR=\"$XDG_CONFIG_HOME/spacemacs\"\n</code></pre> <p>Load the environment variables into the shell, or exit Termux and restart.</p> Load .profile into shell<pre><code>source ~/.profile\n</code></pre> <p>nano editor installed by default</p> <p><code>nano</code> editor is used to edit the commands as the package is installed by default in termux. <code>vim</code>, <code>neovim</code>, <code>emacs</code> or any other Linux command line editor can be used if the package is first installed.  Termux will list packages to install when trying to run a command that is from a package not yet installed.</p>"},{"location":"termux/setup/#tools-to-download-binaries-and-configuration","title":"Tools to download binaries and configuration","text":"<p>Many tools can be installed via the <code>pkg</code> tool, although specific Clojure tools and configuration require additional tools:</p> <ul> <li><code>wget</code> and <code>curl</code> - download tools not packaged, i.e. clojure-lsp binary</li> <li><code>git</code> - clone configuration files and projects (see Git version control section)</li> <li><code>openssh</code> - SSH service and tools to generate SSH keys</li> </ul> <pre><code>pkg install curl wget git openssh\n</code></pre> <p>Configure a Git Identify and SSH key to before committing and pushing changes, or cloning repositories using the SSH protocol.  practicalli/dotfiles contains example configuration, ignore patterns and commit template for using Git.</p>"},{"location":"termux/setup/#optional-configure-termux-settings","title":"[Optional] Configure Termux Settings","text":"<p>Edit <code>~/.termux/termux.properties</code> to configure the default settings for termux.</p> <pre><code>nano ~/.termux/termux.properties\n</code></pre> <p>Load <code>termux.properties</code> if values are changed (restarting Termux is not enough to load setting changes)</p> <pre><code>termux-reload-settings\n</code></pre> <p>The defaults are suitable for the majority of uses, although you may wish to consider:</p> <ul> <li><code>fullscreen</code> set to <code>true</code> to us the whole screen, hiding Android menu bars, etc.</li> <li><code>hide-soft-keyboard-on-startup</code> set to <code>true</code> if always using a physical keyboard</li> <li><code>default-working-directory</code> to save files user files and directories in an alternative location,</li> </ul> <p>If swiping from left edge of the screen is already taken, set key bindings for creating a new termux session, naming a session and switching between sessions.  Alternatively, use byobu to create and switch between its tabs for multiple terminal sessions.</p>"},{"location":"termux/setup/#set-color-scheme-and-font","title":"Set Color Scheme and Font","text":"<p>The Termux:Styling plug provides menus for selecting terminal color scheme and font to use</p> <p>Press and hold on the Termux screen to show the context menu and select the Style menu.  On smaller screens select More &gt; Style</p> <p>If Termux:Styling plugin was not installed, a prompt will display asking if the plugin should be installed</p> <p>A menu appears with Choose Color and Choose Font</p> <p>Select Choose Color to select from the available list of colour schemes, e.g. Gruvbox Dark or Gruvbox Light</p> <p><code>~/.termux/colors.properties</code> file is added when selecting a colour scheme, defining Hex colors from the theme selected.</p> <p>Select Choose Font to select from the available fonts, e.g. FiraCode or Ubuntu</p> <p><code>~/.termux/font.ttf</code> font file is added when selecting a font.</p> <p>Termux:Styling uses NerdFonts for icons</p> <p>All fonts installed via <code>Termux:Styling</code> have been patched with NerdFonts, providing several thousand icons to use within the terminal prompt and Neovim itself (e.g. VimDevIcons).</p>"},{"location":"termux/using-termux/","title":"Using Termux","text":"<p>Start Termux app and a terminal prompt is shown, along with the standard Android software keyboard.  An extended keyboard is provided with common key bindings for the command line interface (Tab, Esc, Ctrl, arrow keys, etc.).</p> <p></p>"},{"location":"termux/using-termux/#keyboards","title":"Keyboards","text":"<p>Termux provides an extended keyboard with key combinations not possible with the Android software keyboard, i.e <code>Ctrl-c</code>, arrow keys, etc.  <code>TAB</code> is especially useful for driving command and filename completion.</p> <p><code>Volume Up + q</code> toggles the extended keyboard, so more screen is available when using a hardware keyboard.</p> <p>Connect a hardware keyboard for the best experience, e.g the Keyboard.io atreus is an excellent and highly portable mechanical keyboard. The software keyboard is automatically switched off when a hardware keyboard is connected, although the extended keyboard is still displayed by default.</p>"},{"location":"termux/using-termux/#adjusting-font-size","title":"Adjusting Font size","text":"<p>Pinch the screen inwards to zoom out making the text font smaller.</p> <p>Pinch the screen outwards to zoom in making the text font larger.</p>"},{"location":"termux/using-termux/#termux-menus","title":"Termux menus","text":"<p>Termux has three menus: A context menu, navigation drawer and Termux section of the Android notification.</p> <p>The context menu is shown by a long press anywhere on the terminal screen:</p> <ul> <li><code>Select</code> and <code>Paste</code> text to share text with other applications</li> <li><code>Reset</code> the terminal if it gets stuck or <code>Hangup</code> to exit the current terminal session</li> <li><code>Style</code> the terminal by selecting a font and a color scheme</li> </ul> <p>The navigation drawer is shown by swiping inwards from the left of the screen</p> <ul> <li>list and select terminal sessions, set a name for a session with a long press</li> <li>A button to toggle visibility of the touch keyboard.</li> <li>A button to create new terminal sessions (long press for creating a named session or a fail-safe one).</li> </ul> <p>If gesture navigation is enabled in Android, hold the edge of the screen briefly before swiping to bring up the navigation drawer</p> <p>The Android notification menu contains a Termux section. Press the Termux section to show the current terminal session or expand the Termux section to exiting all running terminal sessions or aquire a wake lock to avoid Termux entering sleep mode. A wake lock allows server and other background processes to run reliably and to continue to receive notifications</p>"},{"location":"termux/using-termux/#package-management","title":"Package management","text":"<p>Termux provides a Linux command line experience, providing a wide range of Unix tools and development environments.  Termux uses a Debian based system and packages are easily installed</p> <ul> <li><code>apt install</code> add tools and libraries to the Linux environment from the curated packages in the software center</li> <li><code>apt update</code> updates the list of packages fromhe software center</li> <li><code>apt list --upgradable</code> shows list of packages with new versions</li> <li><code>apt upgrade</code> install new versions of currently installed packages</li> <li><code>apt-cache search --names-only</code> - search for packages that include a specific pattern in their name.</li> <li><code>apt-cache show</code> - shows detail of the supplied package name, including a description</li> </ul> <p><code>pkg</code> is an alias for <code>apt</code>, the advance package tool, although there seems little benefit to using pkg if familiar with apt (they are both 3 characters)</p>"},{"location":"termux/using-termux/#byobu-terminal-tab-manager","title":"Byobu terminal tab manager","text":"<p>Byobu is an alternative to Termux provides a single terminal prompt. Byobu provides multiple shell prompts, allowing individual Clojure tools and editors to be run from the Termux prompt simultaneously.  Practicalli uses byobu to run Neovim, a Clojure REPL and unit test watcher in separate byobu tabs with the ability to add further tabs for other command line tools.</p> <pre><code>pkg install byobu\n</code></pre> <ul> <li><code>F2</code> to create a new tab</li> <li><code>F3</code> to select previous tab</li> <li><code>F4</code> to select next tab</li> </ul> <p><code>byobu-enable</code> command will configure the current shell to run byobu on startup.  Test this is working by typing <code>exit</code> in Termux and start Termux app again. <code>byobu-disable</code> stops this behaviour and byobu will need to be run manually after starting Termux.</p> <p>Run the <code>byobu-enable</code> command again if zsh is configured after this step or if adding any other shell to Termux.</p>"},{"location":"version-control/","title":"Version Control","text":"<p>There are several ways to interact with Git version control, although Practicalli recommends Neogit interactive git client and Octo to manage GitHub issues and pull requests</p> <ul> <li>lazygit terminal UI, embedded in Neovim (AstroNvim only)</li> <li>Neogit git client similar to Emacs Magit, with Diffview integration</li> <li>Octo for GitHub Issue and Pull Requests</li> <li>Open in GitHub</li> <li>Shell out to the command line, <code>:!</code> </li> <li>Git commands in Neovim terminal buffer</li> </ul>"},{"location":"version-control/#init-local-repository","title":"Init local repository","text":"AstroNvim <p>Space t f opens floating terminal window in the current project directory root (or which ever directory Neovim was started from).</p> <p>Initialise a local git repository in the current directory. <pre><code>git init .\n</code></pre></p>"},{"location":"version-control/#stage-in-buffer","title":"Stage in buffer","text":"AstroNvimPracticalli Neovim Config Redux <p>The current hunk or the whole buffer can be staged from the buffer using Git Signs, saving a trip to the Git Status buffer.</p> <p>Space g H stages the current hunk</p> <p>Space g S stages the current buffer</p> <p>Not supported.  </p>"},{"location":"version-control/#git-status","title":"Git Status","text":"AstroNvimPracticalli Neovim Config Redux <p><code>SPC g g</code> opens lazygit status, for minimal UI</p> <p> </p> <p>Space g s Space g n ++\"t\" opens neogit in a new tab for Magit style experience</p> <p><code>SPC g s</code> opens Git Status tab, by running <code>:Neogit</code></p> <p></p>"},{"location":"version-control/#github-integration","title":"GitHub integration","text":"<p>Interact with the remote GitHub repository using Octo</p> <p>List issues from a specific repository</p> <pre><code>:Octo issue list practicalli/neovim\n</code></pre> <p></p> <p>Create a pull request on a specific repository</p> <pre><code>:Octo pr create practicalli/neovim\n</code></pre>"},{"location":"version-control/diff/","title":"Diff","text":"<p>Compare differences between different files or between a file and its versions.</p> <p><code>:diffsplit filename</code> Neovim command opens a split containing the selected filename, showing a diff comparision to the currently opened file </p> <p>file path completion helps select the correct file for comparison</p>"},{"location":"version-control/diff/#git-diff","title":"Git Diff","text":"<p>DiffView compares working space and staged changes side by side, or a diff for git merge conflicts.</p> <p>++SPC++ g d or <code>d</code> in neogit status buffer (<code>SPC g s</code>) will open diffview in a new tab</p> <p><code>q</code> to return to neogit status buffer</p> <p></p> <ul> <li>Green - added lines</li> <li>Yellow - changed line</li> <li>Red - deleted lines</li> </ul> AstroNvimPracticalli Neovim Config <p>Ctrl h / j / k / l to navigate between open splits</p> <p><code>SPC b</code> toggles the sidebar buffer</p> <p><code>SPC w l</code> and <code>SPC w h</code> to move cursor between diff buffer and sidebar buffer</p> <p></p>"},{"location":"version-control/lazygit/","title":"Lazygit version control","text":"Command Line or AstroNvim configuration <p>Lazygit interface not provided by Practicalli Neovim Config Redux</p>"},{"location":"version-control/lazygit/#requirements","title":"Requirements","text":"<p>Install lazygit command line tool</p>"},{"location":"version-control/lazygit/#open-lazygit","title":"Open Lazygit","text":"AstroNvimCommand Line <p><code>SPC g g</code> to open git status with lazygit in a popup window</p> <p>Change to the root directory of the git managed project.</p> <p>Run the lazygit rich terminal UI</p> <pre><code>lazygit\n</code></pre>"},{"location":"version-control/lazygit/#use-lazygit","title":"Use Lazygit","text":"<p><code>SPC</code> to stage files or directories in the files section of the UI</p> <p><code>c</code> for a simple commit message prompt in the lazygit UI</p> <p><code>C</code> to create a commit message within the</p> <p>Define Editor for Git Commit Messages</p> <p>Set <code>core.editor</code> in the user Git configuration (i.e. <code>.config/git/config</code>) to the name of the editor to use for commit messages, e.g. <code>nvim</code>, <code>emacsclient</code>) <code>shell title= git config --global core.editor = nvim</code> Alternatively, use the <code>VISUAL</code> or <code>EDITOR</code> environment variable to the choice of editor</p>"},{"location":"version-control/neogit/","title":"Neogit - interactive client for Git","text":"<p>Neogit is an interactive git client that provides the core features of version control with Git.  Neogit emulates many of the features found in magit.</p> <p><code>SPC g s</code> to open <code>:Neogit</code> status buffer</p> <p><code>TAB</code> toggles expansion of sections, files and hunks</p> <p><code>d</code> provide a side-by-side view of changes</p> <p><code>q</code> to quit Neogit and return to the previous tab</p> <p></p> <p>Neovim is configured to use the magit style key bindings in practicalli/neovim-config-redux</p>"},{"location":"version-control/neogit/#branching","title":"Branching","text":"<p><code>b</code> opens the branch menu,</p> <ul> <li><code>b</code> - checkout a branch</li> <li><code>c</code> - create a new branch</li> <li><code>d</code> - delete a branch, <code>D</code> deletes local and remote branch</li> <li><code>l</code> - checkout a remote branch and create a local tracking branch</li> <li><code>m</code> - rename an existing local branch</li> <li><code>n</code> - create a new branch</li> </ul>"},{"location":"version-control/neogit/#staging-changes","title":"Staging changes","text":"<p><code>s</code> to stage change under cursor, either file or hunk. <code>S</code> to stage all changes</p> <p><code>u</code> to unstage change under cursor, <code>U</code> to unstage all changes</p> <p><code>v</code> to select lines to stage within a hunk using <code>s</code> or unstage with <code>u</code></p>"},{"location":"version-control/neogit/#commit","title":"Commit","text":"<p><code>c</code> for the commit menu</p> <p><code>c</code> for a new commit, <code>a</code> to amend the latest commit, <code>w</code> to reword a commit message, <code>e</code> to add staged changes to existing commit</p> <p>A new commit or amend commit qill open a new window to write a commit message (using a git commit message template if defined)</p> <p><code>:wq</code> to save a commit message and initiate the commit.</p> <p><code>:q!</code>  to cancel the commit from the commit message buffer.</p>"},{"location":"version-control/neogit/#stashing-changes","title":"Stashing changes","text":"<p><code>Z</code> to open the stash menu</p> <p><code>z</code> to stash the working copy and staged files (index)</p> <p><code>i</code> to only stash the staged files (index)</p>"},{"location":"version-control/neogit/#remote-changes","title":"Remote changes","text":"<p><code>F</code> to open the pull menu, <code>p</code> to pull changes (fetch and merge) from the remote repository, <code>u</code> t pull from the upstream repository, or <code>e</code> to specify the remote and branch names.</p> <p><code>P</code> to open the push menu to open, <code>-u</code> to push to the current remote</p> Confused when remote is not origin <p>Use <code>e</code> option to push to elsewhere when the remote name is not set to <code>origin</code>.  The <code>e</code> option will prompt for a remote name and branch.</p>"},{"location":"version-control/neogit/#commit-history","title":"Commit history","text":"<p><code>L l</code> to view git commit history log</p> <p><code>RET</code> on a log entry shows the commit details in a new window (split)</p> <p><code>q</code> to close the commit details window</p>"},{"location":"version-control/neogit/#modify-git-commit-history","title":"Modify Git commit history","text":"<p><code>r</code> opens the rebase menu</p>"},{"location":"version-control/octo/","title":"Octo - GitHub issues and PRs","text":"<p>List, create and edit issues and pull requests from Neovim with Octo package.</p> <p>Octo connects to GitHub via the GitHub CLI, using a developer token for authentication</p> <p>Neogit provides a Magit style client, creating commits, pull &amp; push changes with remote repositories.</p>"},{"location":"version-control/octo/#github-interaction","title":"GitHub interaction","text":"<p>GitHub CLI</p> <p>Work with GitHub issues and Pull Requests from the comfort of Neovim.</p> <p>GitHub CLI to authentication to a GitHub account.  Successful login creates a local developer token that is used by Octo to communicate with GitHub.</p> <pre><code>gh auth login\n</code></pre>"},{"location":"version-control/octo/#octo-commands","title":"Octo commands","text":"<p>Command line form: <code>Octo &lt;object&gt; &lt;action&gt; [arguments]</code> - Object, Action and Arguments commands</p> <p>List issues from current project (optionally add a specific repository)</p> <pre><code>:Octo issue list practicalli/neovim\n</code></pre> <p>The account/repository-name is required if Octo cannot find the repository</p> <p></p> <p>Create a pull requests from current project</p> <pre><code>:Octo pr create\n</code></pre> <p>Add a comment to the current topic (issue/pr) <pre><code>:Octo comment add\n</code></pre></p> <pre><code>:Octo gist list\n</code></pre> <p></p> <p>Octo.nvim configuration options</p> <p>Octo.nvim configuration options</p>"},{"location":"version-control/open-in-github/","title":"Open In GitHub","text":"<p>Open a file under local version control in the GitHub web UI (browser window).</p> Neovim <p><code>:OpenInGHFile</code></p> <p><code>:OpenInGHRepo</code></p>"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index d141be72..e1c35281 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ