From 7f0958a91688932a40f34fb4de6cd1aef60e6001 Mon Sep 17 00:00:00 2001
From:  <>
Date: Sun, 26 May 2024 15:50:29 +0000
Subject: [PATCH] Deployed 796abee with MkDocs version: 1.6.0

---
 .../astronvim/config-design/index.html        | 508 ++++++++----------
 search/search_index.json                      |   2 +-
 2 files changed, 240 insertions(+), 270 deletions(-)

diff --git a/configuration/astronvim/config-design/index.html b/configuration/astronvim/config-design/index.html
index 03cf4ed1..3dac15e0 100644
--- a/configuration/astronvim/config-design/index.html
+++ b/configuration/astronvim/config-design/index.html
@@ -889,9 +889,9 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#user-config-overview" class="md-nav__link">
+  <a href="#files-overview" class="md-nav__link">
     <span class="md-ellipsis">
-      User Config overview
+      Files overview
     </span>
   </a>
   
@@ -2911,9 +2911,9 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#user-config-overview" class="md-nav__link">
+  <a href="#files-overview" class="md-nav__link">
     <span class="md-ellipsis">
-      User Config overview
+      Files overview
     </span>
   </a>
   
@@ -3053,21 +3053,52 @@
 
 
 <h1 id="practicalli-astronvim-config-design">📦 Practicalli AstroNvim Config Design<a class="headerlink" href="#practicalli-astronvim-config-design" title="Permanent link">λ︎</a></h1>
-<p>A guide to the AstroNvim Config user configuration created by Practicalli to support Clojure development.</p>
+<p>A guide to the design of AstroNvim Config created by Practicalli to support a comprehensive development workflow.</p>
 <details class="info">
-<summary>AstroCommunity used where possible</summary>
+<summary>AstroCommunity Plugin Configurations used where available</summary>
+<p>Plugin configurations from AstroCommunity are used to minimise the code size and maintenance of the Practicalli configuration</p>
 </details>
-<p>Plugins and configuration is added vial AstroCommunity were possible, to minimise the code size and maintenance of the configuration</p>
-<h2 id="user-config-overview">User Config overview<a class="headerlink" href="#user-config-overview" title="Permanent link">λ︎</a></h2>
-<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>
+<h2 id="files-overview">Files overview<a class="headerlink" href="#files-overview" title="Permanent link">λ︎</a></h2>
+<p>The file structure as taken from the AstroNvim template and new files were created to minimise changes, making it simpler to add updates from the original template repository.</p>
+<div class="admonition info">
+<p class="admonition-title">Key: AstroNvim template file changes</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>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V6h-2.75A1.75 1.75 0 0 1 9 4.25V1.5Zm6.75.062V4.25c0 .138.112.25.25.25h2.688l-.011-.013-2.914-2.914-.013-.011Z"/></svg></span> unchanged </li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M1 1.75C1 .784 1.784 0 2.75 0h7.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16H2.75A1.75 1.75 0 0 1 1 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h10.5a.25.25 0 0 0 .25-.25V4.664a.25.25 0 0 0-.073-.177l-2.914-2.914a.25.25 0 0 0-.177-.073ZM8 3.25a.75.75 0 0 1 .75.75v1.5h1.5a.75.75 0 0 1 0 1.5h-1.5v1.5a.75.75 0 0 1-1.5 0V7h-1.5a.75.75 0 0 1 0-1.5h1.5V4A.75.75 0 0 1 8 3.25Zm-3 8a.75.75 0 0 1 .75-.75h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1-.75-.75Z"/></svg></span> changed </li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V4.664a.25.25 0 0 0-.073-.177l-2.914-2.914a.25.25 0 0 0-.177-.073Zm4.48 3.758a.75.75 0 0 1 .755.745l.01 1.497h1.497a.75.75 0 0 1 0 1.5H9v1.507a.75.75 0 0 1-1.5 0V9.005l-1.502.01a.75.75 0 0 1-.01-1.5l1.507-.01-.01-1.492a.75.75 0 0 1 .745-.755Z"/></svg></span> added</li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 20c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-18C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2m2.59 6L12 10.59 9.41 8 8 9.41 10.59 12 8 14.59 9.41 16 12 13.41 14.59 16 16 14.59 13.41 12 16 9.41 14.59 8Z"/></svg></span> config not activated (comment <code>if</code> statement to activate)</li>
+</ul>
+</div>
+<p><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V6h-2.75A1.75 1.75 0 0 1 9 4.25V1.5Zm6.75.062V4.25c0 .138.112.25.25.25h2.688l-.011-.013-2.914-2.914-.013-.011Z"/></svg></span> <code>init.lua</code> ensures the Lazy package manager is available when Neovim starts up. This file is unchanged from the AstroNvim template.</p>
+<p><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M1 1.75C1 .784 1.784 0 2.75 0h7.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16H2.75A1.75 1.75 0 0 1 1 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h10.5a.25.25 0 0 0 .25-.25V4.664a.25.25 0 0 0-.073-.177l-2.914-2.914a.25.25 0 0 0-.177-.073ZM8 3.25a.75.75 0 0 1 .75.75v1.5h1.5a.75.75 0 0 1 0 1.5h-1.5v1.5a.75.75 0 0 1-1.5 0V7h-1.5a.75.75 0 0 1 0-1.5h1.5V4A.75.75 0 0 1 8 3.25Zm-3 8a.75.75 0 0 1 .75-.75h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1-.75-.75Z"/></svg></span> <code>lua/lazy_setup.lua</code> configures the Lazy package manager.  <code>zipPlugin</code> enabled to support Clojure docs and source navigation inside libraries. </p>
+<p><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M1 1.75C1 .784 1.784 0 2.75 0h7.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16H2.75A1.75 1.75 0 0 1 1 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h10.5a.25.25 0 0 0 .25-.25V4.664a.25.25 0 0 0-.073-.177l-2.914-2.914a.25.25 0 0 0-.177-.073ZM8 3.25a.75.75 0 0 1 .75.75v1.5h1.5a.75.75 0 0 1 0 1.5h-1.5v1.5a.75.75 0 0 1-1.5 0V7h-1.5a.75.75 0 0 1 0-1.5h1.5V4A.75.75 0 0 1 8 3.25Zm-3 8a.75.75 0 0 1 .75-.75h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1-.75-.75Z"/></svg></span> <code>lua/community.lua</code> imports plugin configurations from AstroCommunity, including the Clojure pack.</p>
+<p><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V6h-2.75A1.75 1.75 0 0 1 9 4.25V1.5Zm6.75.062V4.25c0 .138.112.25.25.25h2.688l-.011-.013-2.914-2.914-.013-.011Z"/></svg></span> <span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 20c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-18C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2m2.59 6L12 10.59 9.41 8 8 9.41 10.59 12 8 14.59 9.41 16 12 13.41 14.59 16 16 14.59 13.41 12 16 9.41 14.59 8Z"/></svg></span> <code>lua/polish.lua</code> general lua configuration loaded after AstroNvim configs.</p>
+<p><code>lua/plugins/</code> for additional plugins organised logically. All <code>.lua</code> files are automatically loaded from this directory when starting Neovim.</p>
+<ul>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V6h-2.75A1.75 1.75 0 0 1 9 4.25V1.5Zm6.75.062V4.25c0 .138.112.25.25.25h2.688l-.011-.013-2.914-2.914-.013-.011Z"/></svg></span> <span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 20c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-18C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2m2.59 6L12 10.59 9.41 8 8 9.41 10.59 12 8 14.59 9.41 16 12 13.41 14.59 16 16 14.59 13.41 12 16 9.41 14.59 8Z"/></svg></span> <code>astrocore.lua</code>, <code>astrolsp.lua</code>, <code>astroui.lua</code> examples of overriding AstroNvim defaults</li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V4.664a.25.25 0 0 0-.073-.177l-2.914-2.914a.25.25 0 0 0-.177-.073Zm4.48 3.758a.75.75 0 0 1 .755.745l.01 1.497h1.497a.75.75 0 0 1 0 1.5H9v1.507a.75.75 0 0 1-1.5 0V9.005l-1.502.01a.75.75 0 0 1-.01-1.5l1.507-.01-.01-1.492a.75.75 0 0 1 .745-.755Z"/></svg></span> <code>clojure.lua</code> alternative approach to configure clojure, extending the AstroNvim Clojure pack</li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V4.664a.25.25 0 0 0-.073-.177l-2.914-2.914a.25.25 0 0 0-.177-.073Zm4.48 3.758a.75.75 0 0 1 .755.745l.01 1.497h1.497a.75.75 0 0 1 0 1.5H9v1.507a.75.75 0 0 1-1.5 0V9.005l-1.502.01a.75.75 0 0 1-.01-1.5l1.507-.01-.01-1.492a.75.75 0 0 1 .745-.755Z"/></svg></span> <code>github.lua</code> issue &amp; PR management with octo.nvim (requires GitHub CLI)</li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V6h-2.75A1.75 1.75 0 0 1 9 4.25V1.5Zm6.75.062V4.25c0 .138.112.25.25.25h2.688l-.011-.013-2.914-2.914-.013-.011Z"/></svg></span> <span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 20c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-18C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2m2.59 6L12 10.59 9.41 8 8 9.41 10.59 12 8 14.59 9.41 16 12 13.41 14.59 16 16 14.59 13.41 12 16 9.41 14.59 8Z"/></svg></span> <code>mason.lua</code> ensure tools are installed by default (LSP servers, format &amp; lint tools, DAP debug tools)</li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V6h-2.75A1.75 1.75 0 0 1 9 4.25V1.5Zm6.75.062V4.25c0 .138.112.25.25.25h2.688l-.011-.013-2.914-2.914-.013-.011Z"/></svg></span> <span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 20c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-18C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2m2.59 6L12 10.59 9.41 8 8 9.41 10.59 12 8 14.59 9.41 16 12 13.41 14.59 16 16 14.59 13.41 12 16 9.41 14.59 8Z"/></svg></span> <code>neo-tree.lua</code> visual file navigator - example config</li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V6h-2.75A1.75 1.75 0 0 1 9 4.25V1.5Zm6.75.062V4.25c0 .138.112.25.25.25h2.688l-.011-.013-2.914-2.914-.013-.011Z"/></svg></span> <span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 20c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-18C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2m2.59 6L12 10.59 9.41 8 8 9.41 10.59 12 8 14.59 9.41 16 12 13.41 14.59 16 16 14.59 13.41 12 16 9.41 14.59 8Z"/></svg></span> <code>none-ls.lua</code> example config for format &amp; lint tools</li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V4.664a.25.25 0 0 0-.073-.177l-2.914-2.914a.25.25 0 0 0-.177-.073Zm4.48 3.758a.75.75 0 0 1 .755.745l.01 1.497h1.497a.75.75 0 0 1 0 1.5H9v1.507a.75.75 0 0 1-1.5 0V9.005l-1.502.01a.75.75 0 0 1-.01-1.5l1.507-.01-.01-1.492a.75.75 0 0 1 .745-.755Z"/></svg></span> <span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 20c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-18C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2m2.59 6L12 10.59 9.41 8 8 9.41 10.59 12 8 14.59 9.41 16 12 13.41 14.59 16 16 14.59 13.41 12 16 9.41 14.59 8Z"/></svg></span> <code>platuml.lua</code> UML diagrams defined with code - requires plantuml.com install</li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V4.664a.25.25 0 0 0-.073-.177l-2.914-2.914a.25.25 0 0 0-.177-.073Zm4.48 3.758a.75.75 0 0 1 .755.745l.01 1.497h1.497a.75.75 0 0 1 0 1.5H9v1.507a.75.75 0 0 1-1.5 0V9.005l-1.502.01a.75.75 0 0 1-.01-1.5l1.507-.01-.01-1.492a.75.75 0 0 1 .745-.755Z"/></svg></span> <code>practicalli.lua</code> theme, dashboard &amp; key binding preferences enjoyed by Practicalli</li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V4.664a.25.25 0 0 0-.073-.177l-2.914-2.914a.25.25 0 0 0-.177-.073Zm4.48 3.758a.75.75 0 0 1 .755.745l.01 1.497h1.497a.75.75 0 0 1 0 1.5H9v1.507a.75.75 0 0 1-1.5 0V9.005l-1.502.01a.75.75 0 0 1-.01-1.5l1.507-.01-.01-1.492a.75.75 0 0 1 .745-.755Z"/></svg></span> <code>snippets.lua</code> load JSON style snippet definitions</li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V4.664a.25.25 0 0 0-.073-.177l-2.914-2.914a.25.25 0 0 0-.177-.073Zm4.48 3.758a.75.75 0 0 1 .755.745l.01 1.497h1.497a.75.75 0 0 1 0 1.5H9v1.507a.75.75 0 0 1-1.5 0V9.005l-1.502.01a.75.75 0 0 1-.01-1.5l1.507-.01-.01-1.492a.75.75 0 0 1 .745-.755Z"/></svg></span><code>telescope.lua</code> ensure Treesitter languages are installed (AstroCommunity language packs also ensure parsers installed)</li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V6h-2.75A1.75 1.75 0 0 1 9 4.25V1.5Zm6.75.062V4.25c0 .138.112.25.25.25h2.688l-.011-.013-2.914-2.914-.013-.011Z"/></svg></span> <span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 20c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-18C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2m2.59 6L12 10.59 9.41 8 8 9.41 10.59 12 8 14.59 9.41 16 12 13.41 14.59 16 16 14.59 13.41 12 16 9.41 14.59 8Z"/></svg></span> <code>treesittter.lua</code> ensure Treesitter languages are installed (AstroCommunity language packs also ensure parsers installed)</li>
+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V6h-2.75A1.75 1.75 0 0 1 9 4.25V1.5Zm6.75.062V4.25c0 .138.112.25.25.25h2.688l-.011-.013-2.914-2.914-.013-.011Z"/></svg></span> <span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 20c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-18C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2m2.59 6L12 10.59 9.41 8 8 9.41 10.59 12 8 14.59 9.41 16 12 13.41 14.59 16 16 14.59 13.41 12 16 9.41 14.59 8Z"/></svg></span> <code>user.lua</code> example user configuration, added via <code>lua/plugins/practicalli.lua</code></li>
 </ul>
 <h2 id="clojure-support">Clojure support<a class="headerlink" href="#clojure-support" title="Permanent link">λ︎</a></h2>
-<p>The <a href="https://github.com/AstroNvim/astrocommunity/"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><!--! Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg></span> AstroCommunity</a> 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>
-<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">AstroCommunity Pack</label><label for="__tabbed_1_2">Manually add plugins</label></div>
+<p>The <a href="https://github.com/AstroNvim/astrocommunity/"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><!--! Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg></span> AstroCommunity</a> provides a Clojure language pack that ensures <code>clojure</code> Treesitter parser and <code>clojure-lsp</code> support and installed automatically.</p>
+<p>The pack contains 4 Neovim plugins:</p>
+<ul>
+<li>conjure REPL client to evaluate code</li>
+<li>nvim-parinfer code indenting structural editing</li>
+<li>nvim-treesitter-sexp paredit (slurp/barf etc) structural editing </li>
+<li>ts-comment.nvim Clojure comment patterns</li>
+</ul>
+<p>!!! INFO: "Practicalli AstroNvim Config includes Clojure pack"</p>
+<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">AstroCommunity Clojure Pack</label><label for="__tabbed_1_2">Manually add plugins</label></div>
 <div class="tabbed-content">
 <div class="tabbed-block">
 <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>
@@ -3076,58 +3107,65 @@ <h2 id="clojure-support">Clojure support<a class="headerlink" href="#clojure-sup
 <a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="p">{</span> <span class="n">import</span> <span class="o">=</span> <span class="s2">&quot;astrocommunity.pack.clojure&quot;</span> <span class="p">},</span>
 </code></pre></div>
 <details class="hint">
-<summary>Override AstroCommunity Pack</summary>
-<p>Create a <code>plugins/clojure.lua</code> file and add the AstroCommunity repository, Clojure pack and additional configuration to your own preferences</p>
-<div class="admonition example">
-<p class="admonition-title">Clojure configuration with user configration overrides</p>
+<summary>Exclude a plugin from the pack</summary>
+<p>The Clojure pack includes parinfer and paredit tools for structural editing, which both work together without issue.  Should one or both of these plugins not be reqiured, set enabled to false
 <div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="kr">return</span> <span class="p">{</span>
 <a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>  <span class="s2">&quot;AstroNvim/astrocommunity&quot;</span><span class="p">,</span>
 <a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>  <span class="p">{</span> <span class="n">import</span> <span class="o">=</span> <span class="s2">&quot;astrocommunity.pack.clojure&quot;</span> <span class="p">},</span>
-<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a>  <span class="p">{</span>
-<a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a>    <span class="s2">&quot;Olical/conjure&quot;</span><span class="p">,</span>
-<a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a>    <span class="c1">-- load plugin on filetypes</span>
-<a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a>    <span class="n">ft</span> <span class="o">=</span> <span class="p">{</span> <span class="s2">&quot;clojure&quot;</span><span class="p">,</span> <span class="s2">&quot;fennel&quot;</span> <span class="p">},</span>
-<a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a>    <span class="n">config</span> <span class="o">=</span> <span class="kr">function</span><span class="p">()</span>
-<a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a>      <span class="c1">-- HUD</span>
-<a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a>      <span class="c1">-- Example: Set to `&quot;SE&quot;` and HUD width to `1.0` for full width HUD at bottom of screen</span>
-<a id="__codelineno-1-11" name="__codelineno-1-11" href="#__codelineno-1-11"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">[</span><span class="s2">&quot;conjure#log#hud#width&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span> <span class="c1">-- Width of HUD as percentage of the editor width, 0.0 and 1.0.</span>
-<a id="__codelineno-1-12" name="__codelineno-1-12" href="#__codelineno-1-12"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">[</span><span class="s2">&quot;conjure#log#hud#enabled&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">false</span> <span class="c1">-- Display HUD</span>
-<a id="__codelineno-1-13" name="__codelineno-1-13" href="#__codelineno-1-13"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">[</span><span class="s2">&quot;conjure#log#hud#anchor&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;SE&quot;</span> <span class="c1">-- Preferred corner position for the HUD</span>
-<a id="__codelineno-1-14" name="__codelineno-1-14" href="#__codelineno-1-14"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">[</span><span class="s2">&quot;conjure#log#botright&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">true</span> <span class="c1">-- Open log at bottom or far right of editor</span>
-<a id="__codelineno-1-15" name="__codelineno-1-15" href="#__codelineno-1-15"></a>      <span class="c1">-- REPL</span>
-<a id="__codelineno-1-16" name="__codelineno-1-16" href="#__codelineno-1-16"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">[</span><span class="s2">&quot;conjure#extract#context_header_lines&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">100</span> <span class="c1">-- Number of lines to check for `ns` form</span>
-<a id="__codelineno-1-17" name="__codelineno-1-17" href="#__codelineno-1-17"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">[</span><span class="s2">&quot;conjure#client#clojure#nrepl#connection#auto_repl#enabled&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">false</span> <span class="c1">-- ;; Start &quot;auto-repl&quot; process, eg. babashka</span>
-<a id="__codelineno-1-18" name="__codelineno-1-18" href="#__codelineno-1-18"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">[</span><span class="s2">&quot;conjure#client#clojure#nrepl#connection#auto_repl#hidden&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">true</span> <span class="c1">-- ;; Hide auto-repl buffer when triggered</span>
-<a id="__codelineno-1-19" name="__codelineno-1-19" href="#__codelineno-1-19"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">[</span><span class="s2">&quot;conjure#client#clojure#nrepl#connection#auto_repl#cmd&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">nil</span> <span class="c1">-- ;; Command to start the auto-repl</span>
-<a id="__codelineno-1-20" name="__codelineno-1-20" href="#__codelineno-1-20"></a>      <span class="c1">-- ;; Automatically require namespace of new buffer or current buffer after connection</span>
-<a id="__codelineno-1-21" name="__codelineno-1-21" href="#__codelineno-1-21"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">[</span><span class="s2">&quot;conjure#client#clojure#nrepl#eval#auto_require&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">false</span>
-<a id="__codelineno-1-22" name="__codelineno-1-22" href="#__codelineno-1-22"></a>      <span class="c1">-- Reloading code</span>
-<a id="__codelineno-1-23" name="__codelineno-1-23" href="#__codelineno-1-23"></a>      <span class="c1">-- Function to call on refresh (reloading) the log, namespace-qualified name of a zero-arity</span>
-<a id="__codelineno-1-24" name="__codelineno-1-24" href="#__codelineno-1-24"></a>      <span class="c1">-- vim.g[&quot;conjure#client#clojure#nrepl#refresh#after&quot;] = nil</span>
-<a id="__codelineno-1-25" name="__codelineno-1-25" href="#__codelineno-1-25"></a>      <span class="c1">-- The namespace-qualified name of a zero-arity function to call before reloading.</span>
-<a id="__codelineno-1-26" name="__codelineno-1-26" href="#__codelineno-1-26"></a>      <span class="c1">-- vim.g[&quot;conjure#client#clojure#nrepl#refresh#before&quot;] = nil</span>
-<a id="__codelineno-1-27" name="__codelineno-1-27" href="#__codelineno-1-27"></a>      <span class="c1">-- List of directories to scan. If no directories given, defaults to all directories on the classpath.</span>
-<a id="__codelineno-1-28" name="__codelineno-1-28" href="#__codelineno-1-28"></a>      <span class="c1">-- vim.g[&quot;conjure#client#clojure#nrepl#refresh#dirs&quot;] = nil</span>
-<a id="__codelineno-1-29" name="__codelineno-1-29" href="#__codelineno-1-29"></a>      <span class="c1">-- Testing</span>
-<a id="__codelineno-1-30" name="__codelineno-1-30" href="#__codelineno-1-30"></a>      <span class="c1">-- ;; Test runner called from the test key mappings</span>
-<a id="__codelineno-1-31" name="__codelineno-1-31" href="#__codelineno-1-31"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">[</span><span class="s2">&quot;conjure#client#clojure#nrepl#test#runner&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;kaocha&quot;</span>
-<a id="__codelineno-1-32" name="__codelineno-1-32" href="#__codelineno-1-32"></a>      <span class="c1">-- Print raw test evaluation result, suppressing prefix for stdout lines `; (out)`</span>
-<a id="__codelineno-1-33" name="__codelineno-1-33" href="#__codelineno-1-33"></a>      <span class="c1">-- vim.g[&quot;conjure#client#clojure#nrepl#test#raw_out&quot;] = nil</span>
-<a id="__codelineno-1-34" name="__codelineno-1-34" href="#__codelineno-1-34"></a>      <span class="c1">-- Override string appended to the end of the test runner calls</span>
-<a id="__codelineno-1-35" name="__codelineno-1-35" href="#__codelineno-1-35"></a>      <span class="c1">-- vim.g[&quot;conjure#client#clojure#nrepl#test#call_suffix&quot;] = nil</span>
-<a id="__codelineno-1-36" name="__codelineno-1-36" href="#__codelineno-1-36"></a>    <span class="kr">end</span>
-<a id="__codelineno-1-37" name="__codelineno-1-37" href="#__codelineno-1-37"></a>  <span class="p">},</span>
-<a id="__codelineno-1-38" name="__codelineno-1-38" href="#__codelineno-1-38"></a>  <span class="p">{</span>
-<a id="__codelineno-1-39" name="__codelineno-1-39" href="#__codelineno-1-39"></a>    <span class="s2">&quot;gpanders/nvim-parinfer&quot;</span><span class="p">,</span>
-<a id="__codelineno-1-40" name="__codelineno-1-40" href="#__codelineno-1-40"></a>    <span class="n">ft</span> <span class="o">=</span> <span class="p">{</span> <span class="s2">&quot;clojure&quot;</span> <span class="p">},</span>
-<a id="__codelineno-1-41" name="__codelineno-1-41" href="#__codelineno-1-41"></a>    <span class="n">config</span> <span class="o">=</span> <span class="kr">function</span><span class="p">()</span>
-<a id="__codelineno-1-42" name="__codelineno-1-42" href="#__codelineno-1-42"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">.</span><span class="n">parinfer_force_balance</span> <span class="o">=</span> <span class="kc">true</span>
-<a id="__codelineno-1-43" name="__codelineno-1-43" href="#__codelineno-1-43"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">.</span><span class="n">parinfer_comment_chars</span> <span class="o">=</span> <span class="s2">&quot;;;&quot;</span>
-<a id="__codelineno-1-44" name="__codelineno-1-44" href="#__codelineno-1-44"></a>    <span class="kr">end</span><span class="p">,</span>
-<a id="__codelineno-1-45" name="__codelineno-1-45" href="#__codelineno-1-45"></a>  <span class="p">},</span>
-<a id="__codelineno-1-46" name="__codelineno-1-46" href="#__codelineno-1-46"></a><span class="p">}</span>
+<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a>  <span class="p">{</span> <span class="s2">&quot;gpanders/nvim-parinfer&quot;</span><span class="p">,</span> <span class="n">enabled</span> <span class="o">=</span> <span class="kc">false</span> <span class="p">},</span>
+</code></pre></div></p>
+</details>
+<div class="admonition example">
+<p class="admonition-title">Override Conjure configration</p>
+<p>Add the AstroCommunity Clojure pack and additional configuration to create a tailored experience </p>
+<p><code>:help conjure</code> for general Conjure options.</p>
+<p><code>:help conjure-client-clojure-nrepl</code> for Clojure specific options.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="kr">return</span> <span class="p">{</span>
+<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>  <span class="s2">&quot;AstroNvim/astrocommunity&quot;</span><span class="p">,</span>
+<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a>  <span class="p">{</span> <span class="n">import</span> <span class="o">=</span> <span class="s2">&quot;astrocommunity.pack.clojure&quot;</span> <span class="p">},</span>
+<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a>  <span class="p">{</span>
+<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a>    <span class="s2">&quot;AstroNvim/astrocore&quot;</span><span class="p">,</span>
+<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a>    <span class="n">opts</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a>      <span class="n">options</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a>        <span class="n">g</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a>          <span class="c1">-- show HUD REPL log at startup</span>
+<a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a>          <span class="p">[</span><span class="s2">&quot;conjure#log#hud#enabled&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>
+<a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a>
+<a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a>          <span class="c1">-- Hightlight evaluated forms</span>
+<a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a>          <span class="c1">-- [&quot;conjure#highlight#enabled&quot;] = true,</span>
+<a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a>
+<a id="__codelineno-2-15" name="__codelineno-2-15" href="#__codelineno-2-15"></a>          <span class="c1">-- Trim log after number of lines. Default: `10000`</span>
+<a id="__codelineno-2-16" name="__codelineno-2-16" href="#__codelineno-2-16"></a>          <span class="c1">-- [&quot;conjure#log#trim#at&quot;] = 200,</span>
+<a id="__codelineno-2-17" name="__codelineno-2-17" href="#__codelineno-2-17"></a>          <span class="c1">-- Trim log to number of lines. Default: `7000`</span>
+<a id="__codelineno-2-18" name="__codelineno-2-18" href="#__codelineno-2-18"></a>          <span class="c1">-- [&quot;conjure#log#trim#to&quot;] = 100,</span>
+<a id="__codelineno-2-19" name="__codelineno-2-19" href="#__codelineno-2-19"></a>
+<a id="__codelineno-2-20" name="__codelineno-2-20" href="#__codelineno-2-20"></a>          <span class="c1">-- auto repl (babashka)</span>
+<a id="__codelineno-2-21" name="__codelineno-2-21" href="#__codelineno-2-21"></a>          <span class="p">[</span><span class="s2">&quot;conjure#client#clojure#nrepl#connection#auto_repl#enabled&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>
+<a id="__codelineno-2-22" name="__codelineno-2-22" href="#__codelineno-2-22"></a>          <span class="p">[</span><span class="s2">&quot;conjure#client#clojure#nrepl#connection#auto_repl#hidden&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>
+<a id="__codelineno-2-23" name="__codelineno-2-23" href="#__codelineno-2-23"></a>          <span class="p">[</span><span class="s2">&quot;conjure#client#clojure#nrepl#connection#auto_repl#cmd&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">nil</span><span class="p">,</span>
+<a id="__codelineno-2-24" name="__codelineno-2-24" href="#__codelineno-2-24"></a>          <span class="p">[</span><span class="s2">&quot;conjure#client#clojure#nrepl#eval#auto_require&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>
+<a id="__codelineno-2-25" name="__codelineno-2-25" href="#__codelineno-2-25"></a>
+<a id="__codelineno-2-26" name="__codelineno-2-26" href="#__codelineno-2-26"></a>          <span class="c1">-- Test runner: &quot;clojure&quot;, &quot;clojuresCRipt&quot;, &quot;kaocha&quot;</span>
+<a id="__codelineno-2-27" name="__codelineno-2-27" href="#__codelineno-2-27"></a>          <span class="p">[</span><span class="s2">&quot;conjure#client#clojure#nrepl#test#runner&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;kaocha&quot;</span><span class="p">,</span>
+<a id="__codelineno-2-28" name="__codelineno-2-28" href="#__codelineno-2-28"></a>        <span class="p">},</span>
+<a id="__codelineno-2-29" name="__codelineno-2-29" href="#__codelineno-2-29"></a>      <span class="p">},</span>
+<a id="__codelineno-2-30" name="__codelineno-2-30" href="#__codelineno-2-30"></a>    <span class="p">},</span>
+<a id="__codelineno-2-31" name="__codelineno-2-31" href="#__codelineno-2-31"></a>  <span class="p">},</span>
+<a id="__codelineno-2-32" name="__codelineno-2-32" href="#__codelineno-2-32"></a><span class="p">}</span>
 </code></pre></div>
 </div>
+<details class="info">
+<summary>Config comment for parinfer</summary>
+<p>The parinfer comment configuration may not be required when using ts-comment.nvim to set the Clojure comment pattern.
+<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="p">{</span>
+<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a>  <span class="s2">&quot;gpanders/nvim-parinfer&quot;</span><span class="p">,</span>
+<a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a>  <span class="n">filetype</span> <span class="o">=</span> <span class="p">{</span> <span class="s2">&quot;clojure&quot;</span> <span class="p">},</span>
+<a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a>  <span class="n">config</span> <span class="o">=</span> <span class="kr">function</span><span class="p">()</span>
+<a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a>    <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">.</span><span class="n">parinfer_force_balance</span> <span class="o">=</span> <span class="kc">true</span>
+<a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a>    <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">.</span><span class="n">parinfer_comment_chars</span> <span class="o">=</span> <span class="s2">&quot;;;&quot;</span>
+<a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a>  <span class="kr">end</span><span class="p">,</span>
+<a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a><span class="p">},</span>
+</code></pre></div></p>
 </details>
 </div>
 <div class="tabbed-block">
@@ -3142,15 +3180,6 @@ <h2 id="clojure-support">Clojure support<a class="headerlink" href="#clojure-sup
     -- load plugin on filetypes
     ft = { &quot;clojure&quot;, &quot;fennel&quot; },
   },
-
-  {
-    &quot;gpanders/nvim-parinfer&quot;,
-    ft = { &quot;clojure&quot;, &quot;fennel&quot; },
-    config = function()
-      vim.g.parinfer_force_balance = true
-      vim.g.parinfer_comment_chars = &quot;;;&quot;
-    end,
-  },
 }
 ```
 </code></pre></div>
@@ -3158,20 +3187,20 @@ <h2 id="clojure-support">Clojure support<a class="headerlink" href="#clojure-sup
 <p>Improve syntax highlighting by installing the Clojure parser for Treesitter.</p>
 <div class="admonition example">
 <p class="admonition-title">Treesitter Parser for clojure in AstroNvim user configuration</p>
-<div class="highlight"><span class="filename">.config/astronvim-config/plugins/treesitter.lua</span><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="kr">return</span> <span class="p">{</span>
-<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a>  <span class="s2">&quot;nvim-treesitter/nvim-treesitter&quot;</span><span class="p">,</span>
-<a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a>  <span class="n">opts</span> <span class="o">=</span> <span class="kr">function</span><span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">opts</span><span class="p">)</span>
-<a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a>    <span class="c1">-- add more things to the ensure_installed table protecting against community packs modifying it</span>
-<a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a>    <span class="n">opts</span><span class="p">.</span><span class="n">ensure_installed</span> <span class="o">=</span> <span class="nb">require</span><span class="p">(</span><span class="s2">&quot;astronvim.utils&quot;</span><span class="p">).</span><span class="n">list_insert_unique</span><span class="p">(</span><span class="n">opts</span><span class="p">.</span><span class="n">ensure_installed</span><span class="p">,</span> <span class="p">{</span>
-<a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a>      <span class="c1">-- &quot;lua&quot;</span>
-<a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a><span class="hll">    <span class="s2">&quot;clojure&quot;</span>
-</span><a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a>    <span class="p">})</span>
-<a id="__codelineno-3-9" name="__codelineno-3-9" href="#__codelineno-3-9"></a>  <span class="kr">end</span><span class="p">,</span>
-<a id="__codelineno-3-10" name="__codelineno-3-10" href="#__codelineno-3-10"></a><span class="p">}</span>
+<div class="highlight"><span class="filename">.config/astronvim-config/plugins/treesitter.lua</span><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="kr">return</span> <span class="p">{</span>
+<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a>  <span class="s2">&quot;nvim-treesitter/nvim-treesitter&quot;</span><span class="p">,</span>
+<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a>  <span class="n">opts</span> <span class="o">=</span> <span class="kr">function</span><span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">opts</span><span class="p">)</span>
+<a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a>    <span class="c1">-- add more things to the ensure_installed table protecting against community packs modifying it</span>
+<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a>    <span class="n">opts</span><span class="p">.</span><span class="n">ensure_installed</span> <span class="o">=</span> <span class="nb">require</span><span class="p">(</span><span class="s2">&quot;astronvim.utils&quot;</span><span class="p">).</span><span class="n">list_insert_unique</span><span class="p">(</span><span class="n">opts</span><span class="p">.</span><span class="n">ensure_installed</span><span class="p">,</span> <span class="p">{</span>
+<a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a>      <span class="c1">-- &quot;lua&quot;</span>
+<a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a><span class="hll">    <span class="s2">&quot;clojure&quot;</span>
+</span><a id="__codelineno-5-8" name="__codelineno-5-8" href="#__codelineno-5-8"></a>    <span class="p">})</span>
+<a id="__codelineno-5-9" name="__codelineno-5-9" href="#__codelineno-5-9"></a>  <span class="kr">end</span><span class="p">,</span>
+<a id="__codelineno-5-10" name="__codelineno-5-10" href="#__codelineno-5-10"></a><span class="p">}</span>
 </code></pre></div>
 </div>
 <div class="admonition hint">
-<p class="admonition-title">Install Treesitter Clojure Parser manually</p>
+<p class="admonition-title">Manual install of Treesitter Clojure Parser</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>
 </div>
 </div>
@@ -3181,15 +3210,15 @@ <h2 id="clojure-support">Clojure support<a class="headerlink" href="#clojure-sup
 <summary>Switch to Parinfer Parens mode for Paredit structural editing</summary>
 <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>
-<div class="highlight"><span class="filename">plugins/community.lua</span><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>  <span class="p">{</span>
-<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a>    <span class="s2">&quot;gpanders/nvim-parinfer&quot;</span><span class="p">,</span>
-<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a>    <span class="n">ft</span> <span class="o">=</span> <span class="p">{</span> <span class="s2">&quot;clojure&quot;</span> <span class="p">},</span>
-<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a>    <span class="n">config</span> <span class="o">=</span> <span class="kr">function</span><span class="p">()</span>
-<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">.</span><span class="n">parinfer_force_balance</span> <span class="o">=</span> <span class="kc">true</span>
-<a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">.</span><span class="n">parinfer_comment_chars</span> <span class="o">=</span> <span class="s2">&quot;;;&quot;</span>
-<a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">.</span><span class="n">parinfer_mode</span> <span class="o">=</span> <span class="s2">&quot;paren&quot;</span>
-<a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a>    <span class="kr">end</span><span class="p">,</span>
-<a id="__codelineno-4-9" name="__codelineno-4-9" href="#__codelineno-4-9"></a>  <span class="p">},</span>
+<div class="highlight"><span class="filename">plugins/community.lua</span><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>  <span class="p">{</span>
+<a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a>    <span class="s2">&quot;gpanders/nvim-parinfer&quot;</span><span class="p">,</span>
+<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a>    <span class="n">ft</span> <span class="o">=</span> <span class="p">{</span> <span class="s2">&quot;clojure&quot;</span> <span class="p">},</span>
+<a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a>    <span class="n">config</span> <span class="o">=</span> <span class="kr">function</span><span class="p">()</span>
+<a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">.</span><span class="n">parinfer_force_balance</span> <span class="o">=</span> <span class="kc">true</span>
+<a id="__codelineno-6-6" name="__codelineno-6-6" href="#__codelineno-6-6"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">.</span><span class="n">parinfer_comment_chars</span> <span class="o">=</span> <span class="s2">&quot;;;&quot;</span>
+<a id="__codelineno-6-7" name="__codelineno-6-7" href="#__codelineno-6-7"></a>      <span class="n">vim</span><span class="p">.</span><span class="n">g</span><span class="p">.</span><span class="n">parinfer_mode</span> <span class="o">=</span> <span class="s2">&quot;paren&quot;</span>
+<a id="__codelineno-6-8" name="__codelineno-6-8" href="#__codelineno-6-8"></a>    <span class="kr">end</span><span class="p">,</span>
+<a id="__codelineno-6-9" name="__codelineno-6-9" href="#__codelineno-6-9"></a>  <span class="p">},</span>
 </code></pre></div>
 </details>
 <h3 id="clojure-mappings">Clojure Mappings<a class="headerlink" href="#clojure-mappings" title="Permanent link">λ︎</a></h3>
@@ -3201,28 +3230,28 @@ <h3 id="clojure-mappings">Clojure Mappings<a class="headerlink" href="#clojure-m
 <details class="example">
 <summary>Set localleader in user config</summary>
 <p><code>options.lua</code> in the user configuration provides a consistent way to set Neovim options.</p>
-<div class="highlight"><span class="filename">.config/astronvim-config/options.lua</span><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="c1">-- set vim options here (vim.&lt;first_key&gt;.&lt;second_key&gt; = value)</span>
-<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="kr">return</span> <span class="p">{</span>
-<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a>  <span class="n">opt</span> <span class="o">=</span> <span class="p">{</span>
-<a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a>    <span class="c1">-- set to true or false etc.</span>
-<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a>    <span class="n">relativenumber</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span> <span class="c1">-- sets vim.opt.relativenumber</span>
-<a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a>    <span class="n">number</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>         <span class="c1">-- sets vim.opt.number</span>
-<a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a>    <span class="n">spell</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>         <span class="c1">-- sets vim.opt.spell</span>
-<a id="__codelineno-5-8" name="__codelineno-5-8" href="#__codelineno-5-8"></a>    <span class="n">signcolumn</span> <span class="o">=</span> <span class="s2">&quot;auto&quot;</span><span class="p">,</span>   <span class="c1">-- sets vim.opt.signcolumn to auto</span>
-<a id="__codelineno-5-9" name="__codelineno-5-9" href="#__codelineno-5-9"></a>    <span class="n">wrap</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>          <span class="c1">-- sets vim.opt.wrap</span>
-<a id="__codelineno-5-10" name="__codelineno-5-10" href="#__codelineno-5-10"></a>  <span class="p">},</span>
-<a id="__codelineno-5-11" name="__codelineno-5-11" href="#__codelineno-5-11"></a>  <span class="n">g</span> <span class="o">=</span> <span class="p">{</span>
-<a id="__codelineno-5-12" name="__codelineno-5-12" href="#__codelineno-5-12"></a>    <span class="n">mapleader</span> <span class="o">=</span> <span class="s2">&quot; &quot;</span><span class="p">,</span>                 <span class="c1">-- sets vim.g.mapleader</span>
-<a id="__codelineno-5-13" name="__codelineno-5-13" href="#__codelineno-5-13"></a><span class="hll">    <span class="n">maplocalleader</span> <span class="o">=</span> <span class="s2">&quot;,&quot;</span><span class="p">,</span>            <span class="c1">-- Set local leader key binding (supports Conjure key bindings)</span>
-</span><a id="__codelineno-5-14" name="__codelineno-5-14" href="#__codelineno-5-14"></a>    <span class="n">autoformat_enabled</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>       <span class="c1">-- enable or disable auto formatting at start (lsp.formatting.format_on_save must be enabled)</span>
-<a id="__codelineno-5-15" name="__codelineno-5-15" href="#__codelineno-5-15"></a>    <span class="n">cmp_enabled</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>              <span class="c1">-- enable completion at start</span>
-<a id="__codelineno-5-16" name="__codelineno-5-16" href="#__codelineno-5-16"></a>    <span class="n">autopairs_enabled</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>        <span class="c1">-- enable autopairs at start</span>
-<a id="__codelineno-5-17" name="__codelineno-5-17" href="#__codelineno-5-17"></a>    <span class="n">diagnostics_mode</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span>            <span class="c1">-- set the visibility of diagnostics in the UI (0=off, 1=only show in status line, 2=virtual text off, 3=all on)</span>
-<a id="__codelineno-5-18" name="__codelineno-5-18" href="#__codelineno-5-18"></a>    <span class="n">icons_enabled</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>            <span class="c1">-- disable icons in the UI (disable if no nerd font is available, requires :PackerSync after changing)</span>
-<a id="__codelineno-5-19" name="__codelineno-5-19" href="#__codelineno-5-19"></a>    <span class="n">ui_notifications_enabled</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span> <span class="c1">-- disable notifications when toggling UI elements</span>
-<a id="__codelineno-5-20" name="__codelineno-5-20" href="#__codelineno-5-20"></a>    <span class="n">VM_leader</span> <span class="o">=</span> <span class="s2">&quot;gm&quot;</span>                 <span class="c1">-- Visual Multi Leader (multiple cursors)</span>
-<a id="__codelineno-5-21" name="__codelineno-5-21" href="#__codelineno-5-21"></a>  <span class="p">},</span>
-<a id="__codelineno-5-22" name="__codelineno-5-22" href="#__codelineno-5-22"></a><span class="p">}</span>
+<div class="highlight"><span class="filename">.config/astronvim-config/options.lua</span><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="c1">-- set vim options here (vim.&lt;first_key&gt;.&lt;second_key&gt; = value)</span>
+<a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="kr">return</span> <span class="p">{</span>
+<a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a>  <span class="n">opt</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-7-4" name="__codelineno-7-4" href="#__codelineno-7-4"></a>    <span class="c1">-- set to true or false etc.</span>
+<a id="__codelineno-7-5" name="__codelineno-7-5" href="#__codelineno-7-5"></a>    <span class="n">relativenumber</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span> <span class="c1">-- sets vim.opt.relativenumber</span>
+<a id="__codelineno-7-6" name="__codelineno-7-6" href="#__codelineno-7-6"></a>    <span class="n">number</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>         <span class="c1">-- sets vim.opt.number</span>
+<a id="__codelineno-7-7" name="__codelineno-7-7" href="#__codelineno-7-7"></a>    <span class="n">spell</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>         <span class="c1">-- sets vim.opt.spell</span>
+<a id="__codelineno-7-8" name="__codelineno-7-8" href="#__codelineno-7-8"></a>    <span class="n">signcolumn</span> <span class="o">=</span> <span class="s2">&quot;auto&quot;</span><span class="p">,</span>   <span class="c1">-- sets vim.opt.signcolumn to auto</span>
+<a id="__codelineno-7-9" name="__codelineno-7-9" href="#__codelineno-7-9"></a>    <span class="n">wrap</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>          <span class="c1">-- sets vim.opt.wrap</span>
+<a id="__codelineno-7-10" name="__codelineno-7-10" href="#__codelineno-7-10"></a>  <span class="p">},</span>
+<a id="__codelineno-7-11" name="__codelineno-7-11" href="#__codelineno-7-11"></a>  <span class="n">g</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-7-12" name="__codelineno-7-12" href="#__codelineno-7-12"></a>    <span class="n">mapleader</span> <span class="o">=</span> <span class="s2">&quot; &quot;</span><span class="p">,</span>                 <span class="c1">-- sets vim.g.mapleader</span>
+<a id="__codelineno-7-13" name="__codelineno-7-13" href="#__codelineno-7-13"></a><span class="hll">    <span class="n">maplocalleader</span> <span class="o">=</span> <span class="s2">&quot;,&quot;</span><span class="p">,</span>            <span class="c1">-- Set local leader key binding (supports Conjure key bindings)</span>
+</span><a id="__codelineno-7-14" name="__codelineno-7-14" href="#__codelineno-7-14"></a>    <span class="n">autoformat_enabled</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>       <span class="c1">-- enable or disable auto formatting at start (lsp.formatting.format_on_save must be enabled)</span>
+<a id="__codelineno-7-15" name="__codelineno-7-15" href="#__codelineno-7-15"></a>    <span class="n">cmp_enabled</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>              <span class="c1">-- enable completion at start</span>
+<a id="__codelineno-7-16" name="__codelineno-7-16" href="#__codelineno-7-16"></a>    <span class="n">autopairs_enabled</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>        <span class="c1">-- enable autopairs at start</span>
+<a id="__codelineno-7-17" name="__codelineno-7-17" href="#__codelineno-7-17"></a>    <span class="n">diagnostics_mode</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span>            <span class="c1">-- set the visibility of diagnostics in the UI (0=off, 1=only show in status line, 2=virtual text off, 3=all on)</span>
+<a id="__codelineno-7-18" name="__codelineno-7-18" href="#__codelineno-7-18"></a>    <span class="n">icons_enabled</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>            <span class="c1">-- disable icons in the UI (disable if no nerd font is available, requires :PackerSync after changing)</span>
+<a id="__codelineno-7-19" name="__codelineno-7-19" href="#__codelineno-7-19"></a>    <span class="n">ui_notifications_enabled</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span> <span class="c1">-- disable notifications when toggling UI elements</span>
+<a id="__codelineno-7-20" name="__codelineno-7-20" href="#__codelineno-7-20"></a>    <span class="n">VM_leader</span> <span class="o">=</span> <span class="s2">&quot;gm&quot;</span>                 <span class="c1">-- Visual Multi Leader (multiple cursors)</span>
+<a id="__codelineno-7-21" name="__codelineno-7-21" href="#__codelineno-7-21"></a>  <span class="p">},</span>
+<a id="__codelineno-7-22" name="__codelineno-7-22" href="#__codelineno-7-22"></a><span class="p">}</span>
 </code></pre></div>
 </details>
 <h2 id="clojure-lsp">Clojure LSP<a class="headerlink" href="#clojure-lsp" title="Permanent link">λ︎</a></h2>
@@ -3230,62 +3259,41 @@ <h2 id="clojure-lsp">Clojure LSP<a class="headerlink" href="#clojure-lsp" title=
 <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>
 <details class="example">
 <summary>Manual user config of clojure lsp server</summary>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="c1">-- customize mason plugins</span>
-<a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a><span class="kr">return</span> <span class="p">{</span>
-<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a>  <span class="c1">-- use mason-lspconfig to configure LSP installations</span>
-<a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a>  <span class="p">{</span>
-<a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a>    <span class="s2">&quot;williamboman/mason-lspconfig.nvim&quot;</span><span class="p">,</span>
-<a id="__codelineno-6-6" name="__codelineno-6-6" href="#__codelineno-6-6"></a>    <span class="c1">-- overrides `require(&quot;mason-lspconfig&quot;).setup(...)`</span>
-<a id="__codelineno-6-7" name="__codelineno-6-7" href="#__codelineno-6-7"></a>    <span class="n">opts</span> <span class="o">=</span> <span class="kr">function</span><span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">opts</span><span class="p">)</span>
-<a id="__codelineno-6-8" name="__codelineno-6-8" href="#__codelineno-6-8"></a>      <span class="c1">-- add more things to the ensure_installed table protecting against community packs modifying it</span>
-<a id="__codelineno-6-9" name="__codelineno-6-9" href="#__codelineno-6-9"></a>      <span class="n">opts</span><span class="p">.</span><span class="n">ensure_installed</span> <span class="o">=</span> <span class="nb">require</span><span class="p">(</span><span class="s2">&quot;astronvim.utils&quot;</span><span class="p">).</span><span class="n">list_insert_unique</span><span class="p">(</span><span class="n">opts</span><span class="p">.</span><span class="n">ensure_installed</span><span class="p">,</span> <span class="p">{</span>
-<a id="__codelineno-6-10" name="__codelineno-6-10" href="#__codelineno-6-10"></a>        <span class="c1">-- &quot;clojure_lsp&quot;,  -- provide by Clojure pack</span>
-<a id="__codelineno-6-11" name="__codelineno-6-11" href="#__codelineno-6-11"></a>        <span class="s2">&quot;marksman&quot;</span><span class="p">,</span> <span class="c1">-- Markdown structure (also in markdown pack)</span>
-<a id="__codelineno-6-12" name="__codelineno-6-12" href="#__codelineno-6-12"></a>        <span class="s2">&quot;yamlls&quot;</span><span class="p">,</span>
-<a id="__codelineno-6-13" name="__codelineno-6-13" href="#__codelineno-6-13"></a>      <span class="p">})</span>
-<a id="__codelineno-6-14" name="__codelineno-6-14" href="#__codelineno-6-14"></a>    <span class="kr">end</span><span class="p">,</span>
-<a id="__codelineno-6-15" name="__codelineno-6-15" href="#__codelineno-6-15"></a>  <span class="p">},</span>
-<a id="__codelineno-6-16" name="__codelineno-6-16" href="#__codelineno-6-16"></a><span class="p">}</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="c1">-- customize mason plugins</span>
+<a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a><span class="kr">return</span> <span class="p">{</span>
+<a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a>  <span class="c1">-- use mason-lspconfig to configure LSP installations</span>
+<a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a>  <span class="p">{</span>
+<a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a>    <span class="s2">&quot;williamboman/mason-lspconfig.nvim&quot;</span><span class="p">,</span>
+<a id="__codelineno-8-6" name="__codelineno-8-6" href="#__codelineno-8-6"></a>    <span class="c1">-- overrides `require(&quot;mason-lspconfig&quot;).setup(...)`</span>
+<a id="__codelineno-8-7" name="__codelineno-8-7" href="#__codelineno-8-7"></a>    <span class="n">opts</span> <span class="o">=</span> <span class="kr">function</span><span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">opts</span><span class="p">)</span>
+<a id="__codelineno-8-8" name="__codelineno-8-8" href="#__codelineno-8-8"></a>      <span class="c1">-- add more things to the ensure_installed table protecting against community packs modifying it</span>
+<a id="__codelineno-8-9" name="__codelineno-8-9" href="#__codelineno-8-9"></a>      <span class="n">opts</span><span class="p">.</span><span class="n">ensure_installed</span> <span class="o">=</span> <span class="nb">require</span><span class="p">(</span><span class="s2">&quot;astronvim.utils&quot;</span><span class="p">).</span><span class="n">list_insert_unique</span><span class="p">(</span><span class="n">opts</span><span class="p">.</span><span class="n">ensure_installed</span><span class="p">,</span> <span class="p">{</span>
+<a id="__codelineno-8-10" name="__codelineno-8-10" href="#__codelineno-8-10"></a>        <span class="c1">-- &quot;clojure_lsp&quot;,  -- provide by Clojure pack</span>
+<a id="__codelineno-8-11" name="__codelineno-8-11" href="#__codelineno-8-11"></a>        <span class="s2">&quot;marksman&quot;</span><span class="p">,</span> <span class="c1">-- Markdown structure (also in markdown pack)</span>
+<a id="__codelineno-8-12" name="__codelineno-8-12" href="#__codelineno-8-12"></a>        <span class="s2">&quot;yamlls&quot;</span><span class="p">,</span>
+<a id="__codelineno-8-13" name="__codelineno-8-13" href="#__codelineno-8-13"></a>      <span class="p">})</span>
+<a id="__codelineno-8-14" name="__codelineno-8-14" href="#__codelineno-8-14"></a>    <span class="kr">end</span><span class="p">,</span>
+<a id="__codelineno-8-15" name="__codelineno-8-15" href="#__codelineno-8-15"></a>  <span class="p">},</span>
+<a id="__codelineno-8-16" name="__codelineno-8-16" href="#__codelineno-8-16"></a><span class="p">}</span>
 </code></pre></div>
 </details>
 <h2 id="snippets">Snippets<a class="headerlink" href="#snippets" title="Permanent link">λ︎</a></h2>
 <p>The AstroNvim user example includes a commented LuaSnip configuration</p>
-<div class="highlight"><span class="filename">.config/astronvim-config/plugins/core.lua</span><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a>  <span class="c1">-- {</span>
-<a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a>  <span class="c1">--   &quot;L3MON4D3/LuaSnip&quot;,</span>
-<a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a>  <span class="c1">--   config = function(plugin, opts)</span>
-<a id="__codelineno-7-4" name="__codelineno-7-4" href="#__codelineno-7-4"></a>  <span class="c1">--     require &quot;plugins.configs.luasnip&quot; (plugin, opts)  -- include the default astronvim config that calls the setup call</span>
-<a id="__codelineno-7-5" name="__codelineno-7-5" href="#__codelineno-7-5"></a>  <span class="c1">--     -- add more custom luasnip configuration such as filetype extend or custom snippets</span>
-<a id="__codelineno-7-6" name="__codelineno-7-6" href="#__codelineno-7-6"></a>  <span class="c1">--     local luasnip = require &quot;luasnip&quot;</span>
-<a id="__codelineno-7-7" name="__codelineno-7-7" href="#__codelineno-7-7"></a>  <span class="c1">--     luasnip.filetype_extend(&quot;javascript&quot;, { &quot;javascriptreact&quot; })</span>
-<a id="__codelineno-7-8" name="__codelineno-7-8" href="#__codelineno-7-8"></a>  <span class="c1">--   end,</span>
-<a id="__codelineno-7-9" name="__codelineno-7-9" href="#__codelineno-7-9"></a>  <span class="c1">-- },</span>
-</code></pre></div>
-<p>AstroNvim includes a <a href="https://astronvim.com/Recipes/snippets">Recipe for custom snippets</a></p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="kr">return</span> <span class="p">{</span>
-<a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a>  <span class="n">plugins</span> <span class="o">=</span> <span class="p">{</span>
-<a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a>    <span class="p">{</span>
-<a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a>      <span class="s2">&quot;L3MON4D3/LuaSnip&quot;</span><span class="p">,</span>
-<a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a>      <span class="n">config</span> <span class="o">=</span> <span class="kr">function</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">opts</span><span class="p">)</span>
-<a id="__codelineno-8-6" name="__codelineno-8-6" href="#__codelineno-8-6"></a>        <span class="nb">require</span> <span class="s2">&quot;plugins.configs.luasnip&quot;</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">opts</span><span class="p">)</span> <span class="c1">-- include the default astronvim config that calls the setup call</span>
-<a id="__codelineno-8-7" name="__codelineno-8-7" href="#__codelineno-8-7"></a>        <span class="nb">require</span><span class="p">(</span><span class="s2">&quot;luasnip.loaders.from_vscode&quot;</span><span class="p">).</span><span class="n">lazy_load</span> <span class="p">{</span> <span class="n">paths</span> <span class="o">=</span> <span class="p">{</span> <span class="s2">&quot;./lua/user/snippets&quot;</span> <span class="p">}</span> <span class="p">}</span> <span class="c1">-- load snippets paths</span>
-<a id="__codelineno-8-8" name="__codelineno-8-8" href="#__codelineno-8-8"></a>      <span class="kr">end</span><span class="p">,</span>
-<a id="__codelineno-8-9" name="__codelineno-8-9" href="#__codelineno-8-9"></a>    <span class="p">},</span>
-<a id="__codelineno-8-10" name="__codelineno-8-10" href="#__codelineno-8-10"></a>  <span class="p">},</span>
-<a id="__codelineno-8-11" name="__codelineno-8-11" href="#__codelineno-8-11"></a><span class="p">}</span>
-</code></pre></div>
-<p>Practicalli AstroNvim Config combines the two examples to get</p>
 <div class="admonition example">
-<p class="admonition-title">AstroNvim config with custom VS Code style snippets</p>
-<div class="highlight"><span class="filename">.config/astronvim-config/plugins/core.lua</span><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="p">{</span>
-<a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a>  <span class="s2">&quot;L3MON4D3/LuaSnip&quot;</span><span class="p">,</span>
-<a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></a>  <span class="n">config</span> <span class="o">=</span> <span class="kr">function</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">opts</span><span class="p">)</span>
-<a id="__codelineno-9-4" name="__codelineno-9-4" href="#__codelineno-9-4"></a>    <span class="nb">require</span> <span class="s2">&quot;plugins.configs.luasnip&quot;</span> <span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">opts</span><span class="p">)</span> <span class="c1">-- include the default astronvim config that calls the setup call</span>
-<a id="__codelineno-9-5" name="__codelineno-9-5" href="#__codelineno-9-5"></a>    <span class="c1">-- add more custom luasnip configuration such as filetype extend or custom snippets</span>
-<a id="__codelineno-9-6" name="__codelineno-9-6" href="#__codelineno-9-6"></a>    <span class="nb">require</span><span class="p">(</span><span class="s2">&quot;luasnip.loaders.from_vscode&quot;</span><span class="p">).</span><span class="n">lazy_load</span> <span class="p">{</span> <span class="n">paths</span> <span class="o">=</span> <span class="p">{</span> <span class="s2">&quot;./lua/user/snippets&quot;</span> <span class="p">}</span> <span class="p">}</span> <span class="c1">-- load snippets paths</span>
-<a id="__codelineno-9-7" name="__codelineno-9-7" href="#__codelineno-9-7"></a>    <span class="kd">local</span> <span class="n">luasnip</span> <span class="o">=</span> <span class="nb">require</span> <span class="s2">&quot;luasnip&quot;</span>
-<a id="__codelineno-9-8" name="__codelineno-9-8" href="#__codelineno-9-8"></a>    <span class="n">luasnip</span><span class="p">.</span><span class="n">filetype_extend</span><span class="p">(</span><span class="s2">&quot;javascript&quot;</span><span class="p">,</span> <span class="p">{</span> <span class="s2">&quot;javascriptreact&quot;</span> <span class="p">})</span>
-<a id="__codelineno-9-9" name="__codelineno-9-9" href="#__codelineno-9-9"></a><span class="kr">end</span><span class="p">,</span>
-<a id="__codelineno-9-10" name="__codelineno-9-10" href="#__codelineno-9-10"></a><span class="p">},</span>
+<p class="admonition-title">LuaSnip with json format snippets in <code>snippets/</code> directory</p>
+<div class="highlight"><span class="filename">.config/astronvim-config/plugins/core.lua</span><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="kr">return</span> <span class="p">{</span>
+<a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a>  <span class="c1">--LuaSnip with json format snippets in `snippets/` directory</span>
+<a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></a>  <span class="p">{</span>
+<a id="__codelineno-9-4" name="__codelineno-9-4" href="#__codelineno-9-4"></a>    <span class="s2">&quot;L3MON4D3/LuaSnip&quot;</span><span class="p">,</span>
+<a id="__codelineno-9-5" name="__codelineno-9-5" href="#__codelineno-9-5"></a>    <span class="n">config</span> <span class="o">=</span> <span class="kr">function</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">opts</span><span class="p">)</span>
+<a id="__codelineno-9-6" name="__codelineno-9-6" href="#__codelineno-9-6"></a>      <span class="nb">require</span> <span class="s2">&quot;astronvim.plugins.configs.luasnip&quot;</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">opts</span><span class="p">)</span> <span class="c1">-- include the default astronvim config that calls the setup call</span>
+<a id="__codelineno-9-7" name="__codelineno-9-7" href="#__codelineno-9-7"></a>      <span class="c1">-- add more custom luasnip configuration such as filetype extend or custom snippets</span>
+<a id="__codelineno-9-8" name="__codelineno-9-8" href="#__codelineno-9-8"></a>      <span class="nb">require</span><span class="p">(</span><span class="s2">&quot;luasnip.loaders.from_vscode&quot;</span><span class="p">).</span><span class="n">lazy_load</span> <span class="p">{</span> <span class="n">paths</span> <span class="o">=</span> <span class="p">{</span> <span class="s2">&quot;./snippets&quot;</span> <span class="p">}</span> <span class="p">}</span> <span class="c1">-- include JSON style snippets</span>
+<a id="__codelineno-9-9" name="__codelineno-9-9" href="#__codelineno-9-9"></a>      <span class="kd">local</span> <span class="n">luasnip</span> <span class="o">=</span> <span class="nb">require</span> <span class="s2">&quot;luasnip&quot;</span>
+<a id="__codelineno-9-10" name="__codelineno-9-10" href="#__codelineno-9-10"></a>      <span class="n">luasnip</span><span class="p">.</span><span class="n">filetype_extend</span><span class="p">(</span><span class="s2">&quot;javascript&quot;</span><span class="p">,</span> <span class="p">{</span> <span class="s2">&quot;javascriptreact&quot;</span> <span class="p">})</span>
+<a id="__codelineno-9-11" name="__codelineno-9-11" href="#__codelineno-9-11"></a>    <span class="kr">end</span><span class="p">,</span>
+<a id="__codelineno-9-12" name="__codelineno-9-12" href="#__codelineno-9-12"></a>  <span class="p">},</span>
+<a id="__codelineno-9-13" name="__codelineno-9-13" href="#__codelineno-9-13"></a><span class="p">}</span>
 </code></pre></div>
 </div>
 <h2 id="astronvim-community-packages">AstroNvim Community packages<a class="headerlink" href="#astronvim-community-packages" title="Permanent link">λ︎</a></h2>
@@ -3330,56 +3338,18 @@ <h2 id="themes">Themes<a class="headerlink" href="#themes" title="Permanent link
 <p><a href="https://github.com/sainnhe/everforest">Everforest</a> provides a good dark and light theme and supports the background option to toggle between each colorscheme.</p>
 <div class="admonition exmaple">
 <p class="admonition-title">Practicalli AstroNvim Config - default theme</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="n">colorscheme</span> <span class="o">=</span> <span class="s2">&quot;everforest&quot;</span><span class="p">,</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a>  <span class="p">{</span>
+<a id="__codelineno-12-2" name="__codelineno-12-2" href="#__codelineno-12-2"></a>    <span class="c1">-- AstroUI provides the basis for configuring the AstroNvim User Interface</span>
+<a id="__codelineno-12-3" name="__codelineno-12-3" href="#__codelineno-12-3"></a>    <span class="c1">-- Configuration documentation can be found with `:h astroui`</span>
+<a id="__codelineno-12-4" name="__codelineno-12-4" href="#__codelineno-12-4"></a>    <span class="s2">&quot;AstroNvim/astroui&quot;</span><span class="p">,</span>
+<a id="__codelineno-12-5" name="__codelineno-12-5" href="#__codelineno-12-5"></a>    <span class="c1">---@type AstroUIOpts</span>
+<a id="__codelineno-12-6" name="__codelineno-12-6" href="#__codelineno-12-6"></a>    <span class="n">opts</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-12-7" name="__codelineno-12-7" href="#__codelineno-12-7"></a>      <span class="n">colorscheme</span> <span class="o">=</span> <span class="s2">&quot;everforest&quot;</span><span class="p">,</span>
+<a id="__codelineno-12-8" name="__codelineno-12-8" href="#__codelineno-12-8"></a>    <span class="p">},</span>
+<a id="__codelineno-12-9" name="__codelineno-12-9" href="#__codelineno-12-9"></a>  <span class="p">},</span>
 </code></pre></div>
 </div>
 <p><a class="md-button" href="https://github.com/AstroNvim/astrocommunity/tree/main/lua/astrocommunity/colorscheme" target="_blank"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><!--! Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg></span> AstroCommunity themes</a></p>
-<div class="admonition exmaple">
-<p class="admonition-title">Practicalli AstroNvim Config themes</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a><span class="kr">return</span> <span class="p">{</span>
-<a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a><span class="p">{</span>
-<a id="__codelineno-13-3" name="__codelineno-13-3" href="#__codelineno-13-3"></a><span class="s2">&quot;AstroNvim/astrotheme&quot;</span><span class="p">,</span> <span class="c1">-- default AstroNvim theme</span>
-<a id="__codelineno-13-4" name="__codelineno-13-4" href="#__codelineno-13-4"></a><span class="n">lazy</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>
-<a id="__codelineno-13-5" name="__codelineno-13-5" href="#__codelineno-13-5"></a><span class="p">},</span>
-<a id="__codelineno-13-6" name="__codelineno-13-6" href="#__codelineno-13-6"></a>  <span class="c1">-- Add the community repository of plugin specifications</span>
-<a id="__codelineno-13-7" name="__codelineno-13-7" href="#__codelineno-13-7"></a>  <span class="s2">&quot;AstroNvim/astrocommunity&quot;</span><span class="p">,</span>
-<a id="__codelineno-13-8" name="__codelineno-13-8" href="#__codelineno-13-8"></a>  <span class="p">{</span> <span class="n">import</span> <span class="o">=</span> <span class="s2">&quot;astrocommunity.colorscheme.everforest&quot;</span> <span class="p">},</span>
-<a id="__codelineno-13-9" name="__codelineno-13-9" href="#__codelineno-13-9"></a>  <span class="p">{</span>
-<a id="__codelineno-13-10" name="__codelineno-13-10" href="#__codelineno-13-10"></a>    <span class="s2">&quot;sainnhe/everforest&quot;</span><span class="p">,</span>
-<a id="__codelineno-13-11" name="__codelineno-13-11" href="#__codelineno-13-11"></a>    <span class="n">lazy</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>
-<a id="__codelineno-13-12" name="__codelineno-13-12" href="#__codelineno-13-12"></a>  <span class="p">},</span>
-<a id="__codelineno-13-13" name="__codelineno-13-13" href="#__codelineno-13-13"></a>  <span class="p">{</span> <span class="n">import</span> <span class="o">=</span> <span class="s2">&quot;astrocommunity.colorscheme.nightfox-nvim&quot;</span> <span class="p">},</span>
-<a id="__codelineno-13-14" name="__codelineno-13-14" href="#__codelineno-13-14"></a>  <span class="p">{</span>
-<a id="__codelineno-13-15" name="__codelineno-13-15" href="#__codelineno-13-15"></a>    <span class="s2">&quot;EdenEast/nightfox.nvim&quot;</span><span class="p">,</span>
-<a id="__codelineno-13-16" name="__codelineno-13-16" href="#__codelineno-13-16"></a>    <span class="n">lazy</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>
-<a id="__codelineno-13-17" name="__codelineno-13-17" href="#__codelineno-13-17"></a>  <span class="p">},</span>
-<a id="__codelineno-13-18" name="__codelineno-13-18" href="#__codelineno-13-18"></a>  <span class="p">{</span> <span class="n">import</span> <span class="o">=</span> <span class="s2">&quot;astrocommunity.colorscheme.kanagawa-nvim&quot;</span> <span class="p">},</span>
-<a id="__codelineno-13-19" name="__codelineno-13-19" href="#__codelineno-13-19"></a>  <span class="p">{</span>
-<a id="__codelineno-13-20" name="__codelineno-13-20" href="#__codelineno-13-20"></a>    <span class="s2">&quot;rebelot/kanagawa.nvim&quot;</span><span class="p">,</span>
-<a id="__codelineno-13-21" name="__codelineno-13-21" href="#__codelineno-13-21"></a>    <span class="n">lazy</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>
-<a id="__codelineno-13-22" name="__codelineno-13-22" href="#__codelineno-13-22"></a>  <span class="p">},</span>
-<a id="__codelineno-13-23" name="__codelineno-13-23" href="#__codelineno-13-23"></a>  <span class="p">{</span> <span class="n">import</span> <span class="o">=</span> <span class="s2">&quot;astrocommunity.colorscheme.github-nvim-theme&quot;</span> <span class="p">},</span> <span class="c1">-- no background support</span>
-<a id="__codelineno-13-24" name="__codelineno-13-24" href="#__codelineno-13-24"></a>  <span class="p">{</span>
-<a id="__codelineno-13-25" name="__codelineno-13-25" href="#__codelineno-13-25"></a>    <span class="s2">&quot;projekt0n/github-nvim-theme&quot;</span><span class="p">,</span>
-<a id="__codelineno-13-26" name="__codelineno-13-26" href="#__codelineno-13-26"></a>    <span class="n">lazy</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>
-<a id="__codelineno-13-27" name="__codelineno-13-27" href="#__codelineno-13-27"></a>  <span class="p">},</span>
-</code></pre></div>
-</div>
-<!--
-  -- Theme testing for visual appeal:
-  -- colorscheme = "astrodark",  (default theme, no background support I think)
-  -- colorscheme = "catppuccin",   -- light color to pale, lacks contrast
-  -- colorscheme = "dayfox",
-  colorscheme = "everforest",
-  -- colorscheme = "github_light",  -- no background support, otherwise quite nice
-  -- colorscheme = "gruvbox",  -- status and tablines inverted - doesnt look good, - requires highlight setting in user config
-  -- colorscheme = "gruvbox-baby", -- no background support
-  -- colorscheme = "kanagawa",  -- nice
-  -- colorscheme = "onigiri",  -- nice
-  -- colorscheme = "oxocarbon", -- written in Fennel
-  -- colorscheme = "rose-pine", -- light colour very bright
--->
-
 <h3 id="configure-lazy-plugins">Configure Lazy plugins<a class="headerlink" href="#configure-lazy-plugins" title="Permanent link">λ︎</a></h3>
 <p><a class="md-button" href="https://github.com/folke/lazy.nvim#-plugin-spec" target="_blank"><img alt="🌐" class="twemoji" src="https://cdn.jsdelivr.net/gh/jdecked/twemoji@15.0.3/assets/svg/1f310.svg" title=":globe_with_meridians:" /> Lazy.nvim Plugin specification</a></p>
 <h2 id="config-format-and-lint-tools">Config Format and Lint tools<a class="headerlink" href="#config-format-and-lint-tools" title="Permanent link">λ︎</a></h2>
@@ -3398,22 +3368,22 @@ <h2 id="config-format-and-lint-tools">Config Format and Lint tools<a class="head
 <details class="example">
 <summary>Override null-ls builtin configuration</summary>
 <p>Specify configuration files to use that override the null-ls builtin configuration</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a><span class="kr">return</span> <span class="p">{</span>
-<a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a>  <span class="s2">&quot;jose-elias-alvarez/null-ls.nvim&quot;</span><span class="p">,</span>
-<a id="__codelineno-14-3" name="__codelineno-14-3" href="#__codelineno-14-3"></a>  <span class="n">opts</span> <span class="o">=</span> <span class="kr">function</span><span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">config</span><span class="p">)</span>
-<a id="__codelineno-14-4" name="__codelineno-14-4" href="#__codelineno-14-4"></a>    <span class="c1">-- config variable is the default configuration table for the setup function call</span>
-<a id="__codelineno-14-5" name="__codelineno-14-5" href="#__codelineno-14-5"></a>    <span class="kd">local</span> <span class="n">null_ls</span> <span class="o">=</span> <span class="nb">require</span> <span class="s2">&quot;null-ls&quot;</span>
-<a id="__codelineno-14-6" name="__codelineno-14-6" href="#__codelineno-14-6"></a>    <span class="n">config</span><span class="p">.</span><span class="n">sources</span> <span class="o">=</span> <span class="p">{</span>
-<a id="__codelineno-14-7" name="__codelineno-14-7" href="#__codelineno-14-7"></a>      <span class="n">null_ls</span><span class="p">.</span><span class="n">builtins</span><span class="p">.</span><span class="n">formatting</span><span class="p">.</span><span class="n">markdownlint</span><span class="p">.</span><span class="n">with</span> <span class="p">{</span>
-<a id="__codelineno-14-8" name="__codelineno-14-8" href="#__codelineno-14-8"></a>        <span class="c1">-- pass arguments to modify/override the null-ls builtin configuration</span>
-<a id="__codelineno-14-9" name="__codelineno-14-9" href="#__codelineno-14-9"></a><span class="hll">        <span class="n">extra_args</span> <span class="o">=</span> <span class="p">{</span> 
-</span><a id="__codelineno-14-10" name="__codelineno-14-10" href="#__codelineno-14-10"></a><span class="hll">          <span class="s2">&quot;--config-path&quot;</span><span class="p">,</span> 
-</span><a id="__codelineno-14-11" name="__codelineno-14-11" href="#__codelineno-14-11"></a><span class="hll">          <span class="n">vim</span><span class="p">.</span><span class="n">fn</span><span class="p">.</span><span class="n">expand</span><span class="p">(</span><span class="s2">&quot;~/.config/astro-config/tool-config/markdownlint.yaml&quot;</span><span class="p">)</span> <span class="p">},</span>
-</span><a id="__codelineno-14-12" name="__codelineno-14-12" href="#__codelineno-14-12"></a><span class="hll">      <span class="p">},</span>
-</span><a id="__codelineno-14-13" name="__codelineno-14-13" href="#__codelineno-14-13"></a>    <span class="p">}</span>
-<a id="__codelineno-14-14" name="__codelineno-14-14" href="#__codelineno-14-14"></a>    <span class="kr">return</span> <span class="n">config</span> <span class="c1">-- return final config table</span>
-<a id="__codelineno-14-15" name="__codelineno-14-15" href="#__codelineno-14-15"></a>  <span class="kr">end</span><span class="p">,</span>
-<a id="__codelineno-14-16" name="__codelineno-14-16" href="#__codelineno-14-16"></a><span class="p">}</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a><span class="kr">return</span> <span class="p">{</span>
+<a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a>  <span class="s2">&quot;jose-elias-alvarez/null-ls.nvim&quot;</span><span class="p">,</span>
+<a id="__codelineno-13-3" name="__codelineno-13-3" href="#__codelineno-13-3"></a>  <span class="n">opts</span> <span class="o">=</span> <span class="kr">function</span><span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">config</span><span class="p">)</span>
+<a id="__codelineno-13-4" name="__codelineno-13-4" href="#__codelineno-13-4"></a>    <span class="c1">-- config variable is the default configuration table for the setup function call</span>
+<a id="__codelineno-13-5" name="__codelineno-13-5" href="#__codelineno-13-5"></a>    <span class="kd">local</span> <span class="n">null_ls</span> <span class="o">=</span> <span class="nb">require</span> <span class="s2">&quot;null-ls&quot;</span>
+<a id="__codelineno-13-6" name="__codelineno-13-6" href="#__codelineno-13-6"></a>    <span class="n">config</span><span class="p">.</span><span class="n">sources</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-13-7" name="__codelineno-13-7" href="#__codelineno-13-7"></a>      <span class="n">null_ls</span><span class="p">.</span><span class="n">builtins</span><span class="p">.</span><span class="n">formatting</span><span class="p">.</span><span class="n">markdownlint</span><span class="p">.</span><span class="n">with</span> <span class="p">{</span>
+<a id="__codelineno-13-8" name="__codelineno-13-8" href="#__codelineno-13-8"></a>        <span class="c1">-- pass arguments to modify/override the null-ls builtin configuration</span>
+<a id="__codelineno-13-9" name="__codelineno-13-9" href="#__codelineno-13-9"></a><span class="hll">        <span class="n">extra_args</span> <span class="o">=</span> <span class="p">{</span> 
+</span><a id="__codelineno-13-10" name="__codelineno-13-10" href="#__codelineno-13-10"></a><span class="hll">          <span class="s2">&quot;--config-path&quot;</span><span class="p">,</span> 
+</span><a id="__codelineno-13-11" name="__codelineno-13-11" href="#__codelineno-13-11"></a><span class="hll">          <span class="n">vim</span><span class="p">.</span><span class="n">fn</span><span class="p">.</span><span class="n">expand</span><span class="p">(</span><span class="s2">&quot;~/.config/astro-config/tool-config/markdownlint.yaml&quot;</span><span class="p">)</span> <span class="p">},</span>
+</span><a id="__codelineno-13-12" name="__codelineno-13-12" href="#__codelineno-13-12"></a><span class="hll">      <span class="p">},</span>
+</span><a id="__codelineno-13-13" name="__codelineno-13-13" href="#__codelineno-13-13"></a>    <span class="p">}</span>
+<a id="__codelineno-13-14" name="__codelineno-13-14" href="#__codelineno-13-14"></a>    <span class="kr">return</span> <span class="n">config</span> <span class="c1">-- return final config table</span>
+<a id="__codelineno-13-15" name="__codelineno-13-15" href="#__codelineno-13-15"></a>  <span class="kr">end</span><span class="p">,</span>
+<a id="__codelineno-13-16" name="__codelineno-13-16" href="#__codelineno-13-16"></a><span class="p">}</span>
 </code></pre></div>
 <blockquote>
 <p><code>vim.fn.expand()</code> reports luacheck error <code>accessing undefined variable</code> but seems to work regardless</p>
@@ -3421,34 +3391,34 @@ <h2 id="config-format-and-lint-tools">Config Format and Lint tools<a class="head
 </details>
 <details class="example">
 <summary>General configuration for LSP Servers</summary>
-<div class="highlight"><span class="filename">.config/astronvim-config/init.lua</span><pre><span></span><code><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a>  <span class="n">lsp</span> <span class="o">=</span> <span class="p">{</span>
-<a id="__codelineno-15-2" name="__codelineno-15-2" href="#__codelineno-15-2"></a>    <span class="c1">-- customize lsp formatting options</span>
-<a id="__codelineno-15-3" name="__codelineno-15-3" href="#__codelineno-15-3"></a>    <span class="n">formatting</span> <span class="o">=</span> <span class="p">{</span>
-<a id="__codelineno-15-4" name="__codelineno-15-4" href="#__codelineno-15-4"></a>      <span class="c1">-- control auto formatting on save</span>
-<a id="__codelineno-15-5" name="__codelineno-15-5" href="#__codelineno-15-5"></a>      <span class="n">format_on_save</span> <span class="o">=</span> <span class="p">{</span>
-<a id="__codelineno-15-6" name="__codelineno-15-6" href="#__codelineno-15-6"></a>        <span class="n">enabled</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>     <span class="c1">-- format on save globally</span>
-<a id="__codelineno-15-7" name="__codelineno-15-7" href="#__codelineno-15-7"></a>        <span class="n">allow_filetypes</span> <span class="o">=</span> <span class="p">{</span> <span class="c1">-- format on save for specified filetypes only</span>
-<a id="__codelineno-15-8" name="__codelineno-15-8" href="#__codelineno-15-8"></a>          <span class="c1">-- &quot;go&quot;,</span>
-<a id="__codelineno-15-9" name="__codelineno-15-9" href="#__codelineno-15-9"></a>        <span class="p">},</span>
-<a id="__codelineno-15-10" name="__codelineno-15-10" href="#__codelineno-15-10"></a>        <span class="n">ignore_filetypes</span> <span class="o">=</span> <span class="p">{</span> <span class="c1">-- turn off format on save for specified filetypes</span>
-<a id="__codelineno-15-11" name="__codelineno-15-11" href="#__codelineno-15-11"></a>          <span class="c1">-- &quot;python&quot;,</span>
-<a id="__codelineno-15-12" name="__codelineno-15-12" href="#__codelineno-15-12"></a>        <span class="p">},</span>
-<a id="__codelineno-15-13" name="__codelineno-15-13" href="#__codelineno-15-13"></a>      <span class="p">},</span>
-<a id="__codelineno-15-14" name="__codelineno-15-14" href="#__codelineno-15-14"></a><span class="hll">      <span class="n">disabled</span> <span class="o">=</span> <span class="p">{</span> <span class="c1">-- switch off formatting capabilities for the listed language servers</span>
-</span><a id="__codelineno-15-15" name="__codelineno-15-15" href="#__codelineno-15-15"></a><span class="hll">        <span class="c1">-- turn off lua_ls formatting capability if you want to use StyLua to format your lua code</span>
-</span><a id="__codelineno-15-16" name="__codelineno-15-16" href="#__codelineno-15-16"></a><span class="hll">        <span class="c1">-- &quot;lua_ls&quot;,</span>
-</span><a id="__codelineno-15-17" name="__codelineno-15-17" href="#__codelineno-15-17"></a><span class="hll">        <span class="s2">&quot;markdownlint&quot;</span><span class="p">,</span>
-</span><a id="__codelineno-15-18" name="__codelineno-15-18" href="#__codelineno-15-18"></a>      <span class="p">},</span>
-<a id="__codelineno-15-19" name="__codelineno-15-19" href="#__codelineno-15-19"></a>      <span class="n">timeout_ms</span> <span class="o">=</span> <span class="mi">1000</span><span class="p">,</span> <span class="c1">-- default format timeout</span>
-<a id="__codelineno-15-20" name="__codelineno-15-20" href="#__codelineno-15-20"></a>      <span class="c1">-- filter = function(client) -- fully override the default formatting function</span>
-<a id="__codelineno-15-21" name="__codelineno-15-21" href="#__codelineno-15-21"></a>      <span class="c1">--   return true</span>
-<a id="__codelineno-15-22" name="__codelineno-15-22" href="#__codelineno-15-22"></a>      <span class="c1">-- end</span>
-<a id="__codelineno-15-23" name="__codelineno-15-23" href="#__codelineno-15-23"></a>    <span class="p">},</span>
-<a id="__codelineno-15-24" name="__codelineno-15-24" href="#__codelineno-15-24"></a>    <span class="c1">-- enable servers that you already have installed without mason</span>
-<a id="__codelineno-15-25" name="__codelineno-15-25" href="#__codelineno-15-25"></a>    <span class="n">servers</span> <span class="o">=</span> <span class="p">{</span>
-<a id="__codelineno-15-26" name="__codelineno-15-26" href="#__codelineno-15-26"></a>      <span class="c1">-- &quot;pyright&quot;</span>
-<a id="__codelineno-15-27" name="__codelineno-15-27" href="#__codelineno-15-27"></a>    <span class="p">},</span>
-<a id="__codelineno-15-28" name="__codelineno-15-28" href="#__codelineno-15-28"></a>  <span class="p">},</span>
+<div class="highlight"><span class="filename">.config/astronvim-config/init.lua</span><pre><span></span><code><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a>  <span class="n">lsp</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a>    <span class="c1">-- customize lsp formatting options</span>
+<a id="__codelineno-14-3" name="__codelineno-14-3" href="#__codelineno-14-3"></a>    <span class="n">formatting</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-14-4" name="__codelineno-14-4" href="#__codelineno-14-4"></a>      <span class="c1">-- control auto formatting on save</span>
+<a id="__codelineno-14-5" name="__codelineno-14-5" href="#__codelineno-14-5"></a>      <span class="n">format_on_save</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-14-6" name="__codelineno-14-6" href="#__codelineno-14-6"></a>        <span class="n">enabled</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>     <span class="c1">-- format on save globally</span>
+<a id="__codelineno-14-7" name="__codelineno-14-7" href="#__codelineno-14-7"></a>        <span class="n">allow_filetypes</span> <span class="o">=</span> <span class="p">{</span> <span class="c1">-- format on save for specified filetypes only</span>
+<a id="__codelineno-14-8" name="__codelineno-14-8" href="#__codelineno-14-8"></a>          <span class="c1">-- &quot;go&quot;,</span>
+<a id="__codelineno-14-9" name="__codelineno-14-9" href="#__codelineno-14-9"></a>        <span class="p">},</span>
+<a id="__codelineno-14-10" name="__codelineno-14-10" href="#__codelineno-14-10"></a>        <span class="n">ignore_filetypes</span> <span class="o">=</span> <span class="p">{</span> <span class="c1">-- turn off format on save for specified filetypes</span>
+<a id="__codelineno-14-11" name="__codelineno-14-11" href="#__codelineno-14-11"></a>          <span class="c1">-- &quot;python&quot;,</span>
+<a id="__codelineno-14-12" name="__codelineno-14-12" href="#__codelineno-14-12"></a>        <span class="p">},</span>
+<a id="__codelineno-14-13" name="__codelineno-14-13" href="#__codelineno-14-13"></a>      <span class="p">},</span>
+<a id="__codelineno-14-14" name="__codelineno-14-14" href="#__codelineno-14-14"></a><span class="hll">      <span class="n">disabled</span> <span class="o">=</span> <span class="p">{</span> <span class="c1">-- switch off formatting capabilities for the listed language servers</span>
+</span><a id="__codelineno-14-15" name="__codelineno-14-15" href="#__codelineno-14-15"></a><span class="hll">        <span class="c1">-- turn off lua_ls formatting capability if you want to use StyLua to format your lua code</span>
+</span><a id="__codelineno-14-16" name="__codelineno-14-16" href="#__codelineno-14-16"></a><span class="hll">        <span class="c1">-- &quot;lua_ls&quot;,</span>
+</span><a id="__codelineno-14-17" name="__codelineno-14-17" href="#__codelineno-14-17"></a><span class="hll">        <span class="s2">&quot;markdownlint&quot;</span><span class="p">,</span>
+</span><a id="__codelineno-14-18" name="__codelineno-14-18" href="#__codelineno-14-18"></a>      <span class="p">},</span>
+<a id="__codelineno-14-19" name="__codelineno-14-19" href="#__codelineno-14-19"></a>      <span class="n">timeout_ms</span> <span class="o">=</span> <span class="mi">1000</span><span class="p">,</span> <span class="c1">-- default format timeout</span>
+<a id="__codelineno-14-20" name="__codelineno-14-20" href="#__codelineno-14-20"></a>      <span class="c1">-- filter = function(client) -- fully override the default formatting function</span>
+<a id="__codelineno-14-21" name="__codelineno-14-21" href="#__codelineno-14-21"></a>      <span class="c1">--   return true</span>
+<a id="__codelineno-14-22" name="__codelineno-14-22" href="#__codelineno-14-22"></a>      <span class="c1">-- end</span>
+<a id="__codelineno-14-23" name="__codelineno-14-23" href="#__codelineno-14-23"></a>    <span class="p">},</span>
+<a id="__codelineno-14-24" name="__codelineno-14-24" href="#__codelineno-14-24"></a>    <span class="c1">-- enable servers that you already have installed without mason</span>
+<a id="__codelineno-14-25" name="__codelineno-14-25" href="#__codelineno-14-25"></a>    <span class="n">servers</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-14-26" name="__codelineno-14-26" href="#__codelineno-14-26"></a>      <span class="c1">-- &quot;pyright&quot;</span>
+<a id="__codelineno-14-27" name="__codelineno-14-27" href="#__codelineno-14-27"></a>    <span class="p">},</span>
+<a id="__codelineno-14-28" name="__codelineno-14-28" href="#__codelineno-14-28"></a>  <span class="p">},</span>
 </code></pre></div>
 </details>
 <h2 id="override-key-binding">Override Key binding<a class="headerlink" href="#override-key-binding" title="Permanent link">λ︎</a></h2>
@@ -3457,24 +3427,24 @@ <h2 id="override-key-binding">Override Key binding<a class="headerlink" href="#o
 <p>In the user configuration, return a function that sets key bindings to overide the <code>keys</code> table provided by astrocommunity</p>
 <details class="example">
 <summary>Override Key bindings for vim highlighter</summary>
-<div class="highlight"><span class="filename">.config/astronvim-config/plugins/community.lua</span><pre><span></span><code><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a><span class="p">{</span>
-<a id="__codelineno-16-2" name="__codelineno-16-2" href="#__codelineno-16-2"></a>    <span class="s2">&quot;vim-highlighter&quot;</span><span class="p">,</span>
-<a id="__codelineno-16-3" name="__codelineno-16-3" href="#__codelineno-16-3"></a>    <span class="n">keys</span> <span class="o">=</span> <span class="kr">function</span><span class="p">()</span> 
-<a id="__codelineno-16-4" name="__codelineno-16-4" href="#__codelineno-16-4"></a>        <span class="kr">return</span> <span class="p">{</span>
-<a id="__codelineno-16-5" name="__codelineno-16-5" href="#__codelineno-16-5"></a>            <span class="p">{</span> <span class="s2">&quot;&lt;leader&gt;nn&quot;</span><span class="p">,</span> <span class="s2">&quot;&lt;cmd&gt;Hi&gt;&lt;CR&gt;&quot;</span><span class="p">,</span> <span class="n">desc</span> <span class="o">=</span> <span class="s2">&quot;Next Recently Set Highlight&quot;</span> <span class="p">},</span>
-<a id="__codelineno-16-6" name="__codelineno-16-6" href="#__codelineno-16-6"></a>            <span class="p">{</span> <span class="s2">&quot;&lt;leader&gt;ng&quot;</span><span class="p">,</span> <span class="s2">&quot;&lt;cmd&gt;Hi&lt;&lt;CR&gt;&quot;</span><span class="p">,</span> <span class="n">desc</span> <span class="o">=</span> <span class="s2">&quot;Previous Recently Set Highlight&quot;</span> <span class="p">},</span>
-<a id="__codelineno-16-7" name="__codelineno-16-7" href="#__codelineno-16-7"></a>            <span class="p">{</span> <span class="s2">&quot;&lt;leader&gt;n[&quot;</span><span class="p">,</span> <span class="s2">&quot;&lt;cmd&gt;Hi{&lt;CR&gt;&quot;</span><span class="p">,</span> <span class="n">desc</span> <span class="o">=</span> <span class="s2">&quot;Next Nearest Highlight&quot;</span> <span class="p">},</span>
-<a id="__codelineno-16-8" name="__codelineno-16-8" href="#__codelineno-16-8"></a>            <span class="p">{</span> <span class="s2">&quot;&lt;leader&gt;n]&quot;</span><span class="p">,</span> <span class="s2">&quot;&lt;cmd&gt;Hi}&lt;CR&gt;&quot;</span><span class="p">,</span> <span class="n">desc</span> <span class="o">=</span> <span class="s2">&quot;Previous Nearest Highlight&quot;</span> <span class="p">},</span>
-<a id="__codelineno-16-9" name="__codelineno-16-9" href="#__codelineno-16-9"></a>        <span class="p">}</span>
-<a id="__codelineno-16-10" name="__codelineno-16-10" href="#__codelineno-16-10"></a>    <span class="kr">end</span><span class="p">,</span>
-<a id="__codelineno-16-11" name="__codelineno-16-11" href="#__codelineno-16-11"></a><span class="p">}</span>
+<div class="highlight"><span class="filename">.config/astronvim-config/plugins/community.lua</span><pre><span></span><code><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a><span class="p">{</span>
+<a id="__codelineno-15-2" name="__codelineno-15-2" href="#__codelineno-15-2"></a>    <span class="s2">&quot;vim-highlighter&quot;</span><span class="p">,</span>
+<a id="__codelineno-15-3" name="__codelineno-15-3" href="#__codelineno-15-3"></a>    <span class="n">keys</span> <span class="o">=</span> <span class="kr">function</span><span class="p">()</span> 
+<a id="__codelineno-15-4" name="__codelineno-15-4" href="#__codelineno-15-4"></a>        <span class="kr">return</span> <span class="p">{</span>
+<a id="__codelineno-15-5" name="__codelineno-15-5" href="#__codelineno-15-5"></a>            <span class="p">{</span> <span class="s2">&quot;&lt;leader&gt;nn&quot;</span><span class="p">,</span> <span class="s2">&quot;&lt;cmd&gt;Hi&gt;&lt;CR&gt;&quot;</span><span class="p">,</span> <span class="n">desc</span> <span class="o">=</span> <span class="s2">&quot;Next Recently Set Highlight&quot;</span> <span class="p">},</span>
+<a id="__codelineno-15-6" name="__codelineno-15-6" href="#__codelineno-15-6"></a>            <span class="p">{</span> <span class="s2">&quot;&lt;leader&gt;ng&quot;</span><span class="p">,</span> <span class="s2">&quot;&lt;cmd&gt;Hi&lt;&lt;CR&gt;&quot;</span><span class="p">,</span> <span class="n">desc</span> <span class="o">=</span> <span class="s2">&quot;Previous Recently Set Highlight&quot;</span> <span class="p">},</span>
+<a id="__codelineno-15-7" name="__codelineno-15-7" href="#__codelineno-15-7"></a>            <span class="p">{</span> <span class="s2">&quot;&lt;leader&gt;n[&quot;</span><span class="p">,</span> <span class="s2">&quot;&lt;cmd&gt;Hi{&lt;CR&gt;&quot;</span><span class="p">,</span> <span class="n">desc</span> <span class="o">=</span> <span class="s2">&quot;Next Nearest Highlight&quot;</span> <span class="p">},</span>
+<a id="__codelineno-15-8" name="__codelineno-15-8" href="#__codelineno-15-8"></a>            <span class="p">{</span> <span class="s2">&quot;&lt;leader&gt;n]&quot;</span><span class="p">,</span> <span class="s2">&quot;&lt;cmd&gt;Hi}&lt;CR&gt;&quot;</span><span class="p">,</span> <span class="n">desc</span> <span class="o">=</span> <span class="s2">&quot;Previous Nearest Highlight&quot;</span> <span class="p">},</span>
+<a id="__codelineno-15-9" name="__codelineno-15-9" href="#__codelineno-15-9"></a>        <span class="p">}</span>
+<a id="__codelineno-15-10" name="__codelineno-15-10" href="#__codelineno-15-10"></a>    <span class="kr">end</span><span class="p">,</span>
+<a id="__codelineno-15-11" name="__codelineno-15-11" href="#__codelineno-15-11"></a><span class="p">}</span>
 </code></pre></div>
 </details>
 <h2 id="plugin-key-binding">Plugin Key binding<a class="headerlink" href="#plugin-key-binding" title="Permanent link">λ︎</a></h2>
 <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>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a><span class="kr">if</span> <span class="n">is_available</span> <span class="s2">&quot;plugin-name&quot;</span> <span class="kr">then</span>
-<a id="__codelineno-17-2" name="__codelineno-17-2" href="#__codelineno-17-2"></a>  <span class="p">,,,</span>
-<a id="__codelineno-17-3" name="__codelineno-17-3" href="#__codelineno-17-3"></a><span class="kr">else</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a><span class="kr">if</span> <span class="n">is_available</span> <span class="s2">&quot;plugin-name&quot;</span> <span class="kr">then</span>
+<a id="__codelineno-16-2" name="__codelineno-16-2" href="#__codelineno-16-2"></a>  <span class="p">,,,</span>
+<a id="__codelineno-16-3" name="__codelineno-16-3" href="#__codelineno-16-3"></a><span class="kr">else</span>
 </code></pre></div>
 <!--
 
@@ -3581,7 +3551,7 @@ <h2 id="plugin-key-binding">Plugin Key binding<a class="headerlink" href="#plugi
     <span class="md-icon" title="Last update">
       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1-2.1-2M12.5 7v5.2l4 2.4-1 1L11 13V7h1.5M11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2v1.8Z"/></svg>
     </span>
-    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">October 19, 2023</span>
+    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">May 26, 2024</span>
   </span>
 
     
diff --git a/search/search_index.json b/search/search_index.json
index b20a1d06..2b399cb0 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>Practicalli Neovim provides install &amp; user guide focused on a simple, powerful and joyful REPL driven workflow for Clojure.</p> <p>Practicalli recommends using AstroNvim community configuration which provides Conjure REPL client and Clojure editing support (parinfer &amp; paredit).</p> <p></p>"},{"location":"#quick-start","title":"Quick Start","text":"<p>Install Clojure, Neovim 0.10.0 and Practicalli AstroNvim user config</p>"},{"location":"#neovim-overview","title":"Neovim overview","text":"<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>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> </p>"},{"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-practicalli","title":"Sponsor Practicalli","text":"<p>All sponsorship funds are used to support the continued development of Practicalli series of books and videos, although most work is done at personal cost and time.</p> <p>Thanks 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 is based on AstroNvim, a thoughtful configuration that supports the latest Neovim stable releases, provides a polished UI and many community extensions.</p> <p>Practicalli AstroNvim User Config provides a complete Clojure config on top of AstroNvim.</p> <p>Install Practicalli AstroNvim Config </p> <p>NOTE: Practicalli Neovim Config Redux was a learning experiment that provided mnemonic key bindings, packer, telescope selector, written in Fennel.  This project has now been archived in favour of AstroNvim</p>"},{"location":"configuration/#multiple-configurations","title":"Multiple Configurations","text":"<p>Many Neovim configurations can be installed in <code>$HOME/.config/</code> using unique directory names, e.g. AstroNvim, lazyvim, Nvchad, practicalli. </p> <p>Set <code>NVIM_APPNAME</code> to a configuration directory name (relative to $HOME/.config/`) to run Neovim with that specific config.</p> <p>Run AstroNvim config in <code>$HOME/.config/astronvim/</code></p> <pre><code>NVIM_APPNAME=astronvim nvim\n</code></pre> <p>The configuration directory name is used to save local <code>share</code>, <code>state</code> and <code>cache</code> files for that specific configuration.</p>"},{"location":"configuration/#configure-shell-alias","title":"Configure shell alias","text":"<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>Add alias to <code>.bashrc</code> for Bash shell or <code>.zshrc</code> for Zsh</p> <p>Define Shell Aliases to run each configuration</p> <pre><code>alias astro=\"NVIM_APPNAME=astronvim nvim\"\nalias lazy=\"NVIM_APPNAME=lazyvim nvim\"\nalias practicalli=\"NVIM_APPNAME=neovim-config nvim\"\n</code></pre>"},{"location":"configuration/#shell-aliases-for-bash-and-zsh","title":"shell-aliases for bash and zsh","text":"<p>Create a <code>.config/shell-aliases</code> file containing all shell aliases when often switching between different shells, avoiding the need to define aliases twice</p> <p>Source the <code>.config/shell-aliases</code> file from within <code>.bashrc</code> or <code>.zshrc</code></p> ZshBash .zshrc<pre><code># Shell Aliases\n[[ ! -f ~/.config/shell-aliases ]] || source ~/.config/shell-aliases\n</code></pre> .bashrc<pre><code># Shell Aliases\nif [ -f ~/.config/shell-aliases ]; then\n    . ~/.config/shell-aliases\nfi\n</code></pre>"},{"location":"configuration/#zsh-terminal-config-selector","title":"Zsh Terminal config selector","text":"<p>Optionalliy define a terminal UI selection to choose a configuration if using zsh.</p> <p>Z Shell nvim-selector script</p> .local/bin/nvim-selector<pre><code>function nvim-selector() {\n  items=(\"astronvim\" \"practicalli\" \"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 User Config is a user configuration that extends AstroNvim and imports packages from the  AstroNvim Community.</p>"},{"location":"configuration/astronvim/#astronvim-install","title":"AstroNvim Install","text":"<p> Practicalli AstroNvim User Config is Clojure development focused configuration, an extension of the AstroNvim template.</p> <p> AstroNvim template repository provide a general configuration for Neovim.  AstroNvim Community provides plugin configs to make it easier to extend the general feature of AstroNvim.</p> Practicalli AstroNvim User ConfigAstroNvim template <p>Clone the  Practicalli AstroNvim User Config which provides Clojure support on top of AstroNvim.</p> <pre><code>git clone http://github.com/practicalli/astronvim-user-config $HOME/.config/astronvim\n</code></pre> <p>Create your own user configuration using the  AstroNvim template repository to create a new GitHub repository.</p> <p>Clone the newly created repository</p> <pre><code>git clone git@github.com/AstroNvim/template $HOME/.config/astronvim\n</code></pre> <p>Use Shell Aliases if using multiple Neovim configurations</p> <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>Lazy package manager will run automatically and download all plugins.  Treesitter languages are automatically installed.  </p> <p>q to close the lazy package manager popup.</p> <p><code>NVIM_APPNAME=astronvim4 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_APPNAME=astronvim4 nvim --headless\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/astrocommunity/","title":"Override Astrocommunity Configuration","text":"<p>Configuration in the AstroNvim Community clojure language pack can be overridden and plugins disabled to meet your needs</p>"},{"location":"configuration/astronvim/astrocommunity/#parinfer","title":"Parinfer","text":"<p>By aligning clojure code correctly, parinfer will automatically correct the position of parenthesis and other delimiters, i.e. <code>()</code>, <code>[]</code>, <code>{}</code></p> <p>Parinfer can be disabled if preferred and the more traditional slurp/barf structural editing be done via nvim-treesitter-sexp</p> <p>Include the Clojure language pack and disable the parinfer plugin by setting the plugin name to equal false</p> <pre><code>  { import = \"astrocommunity.pack.clojure\" },\n  { \"gpanders/nvim-parinfer\", enabled = false },\n</code></pre>"},{"location":"configuration/astronvim/astrocommunity/#conjure","title":"Conjure","text":"<p>Configure the Clojure REPL client via the conjure plugin.</p> <p>NOTE: <code>:help conjure-client-clojure-nrepl</code> for full list of Conjure options for Clojure.</p> <p>Set HUD location to full width along the bottom of the screen. The HUD appears in the top right corner of the screen by default.</p> <pre><code>            [\"conjure#log#hud#enabled\"] = true,  -- enable HUD\n            [\"conjure#log#hud#width\"] = 1,\n            [\"conjure#log#hud#anchor\"] = \"SE\",\n            [\"conjure#log#botright\"] = true,\n</code></pre> <p>Disable the auto repl (babashka) if an nREPL process is not listening, i.e. <code>.nrepl-port</code> file does not exist or does not contain a port number.</p> <pre><code>            -- Disable auto repl (babashka)\n            [\"conjure#client#clojure#nrepl#connection#auto_repl#enabled\"] = false,\n            [\"conjure#client#clojure#nrepl#connection#auto_repl#hidden\"] = true,\n            [\"conjure#client#clojure#nrepl#connection#auto_repl#cmd\"] = nil,\n            [\"conjure#client#clojure#nrepl#eval#auto_require\"] = false,\n</code></pre> <p>Change the test runner used by Conjure. <code>clojure.test</code> runner is used by default</p> <ul> <li><code>\"clojure\"</code> clojure.test (default)</li> <li>`\"clojuresCRipt\" cljs.test</li> <li><code>\"kaocha\"</code> lambdaisland/kaocha</li> </ul> <pre><code>            -- Set Test runner: \"clojure\", \"clojuresCRipt\", \"kaocha\"\n            [\"conjure#client#clojure#nrepl#test#runner\"] = \"kaocha\",\n</code></pre> <p>Working example with additional configuration options to show HUD along bottom, enable auto repl if no nREPL process found and set test runner to use lambdaisland/kaocha.</p> <pre><code>  { import = \"astrocommunity.pack.clojure\" },\n  {\n    \"AstroNvim/astrocore\",\n    opts = {\n      options = {\n        g = {\n          -- Enable HUD and show full lenght along bottom\n          [\"conjure#log#hud#enabled\"] = true, -- show log by default?\n          [\"conjure#log#hud#width\"] = 1,\n          [\"conjure#log#hud#anchor\"] = \"SE\",\n          [\"conjure#log#botright\"] = true,\n\n          -- Disable auto repl (babashka)\n          [\"conjure#client#clojure#nrepl#connection#auto_repl#enabled\"] = false,\n          [\"conjure#client#clojure#nrepl#connection#auto_repl#hidden\"] = true,\n          [\"conjure#client#clojure#nrepl#connection#auto_repl#cmd\"] = nil,\n          [\"conjure#client#clojure#nrepl#eval#auto_require\"] = false,\n\n          -- Set Test runner: \"clojure\", \"clojuresCRipt\", \"kaocha\"\n          [\"conjure#client#clojure#nrepl#test#runner\"] = \"kaocha\",\n        },\n      },\n    },\n  },\n</code></pre>"},{"location":"configuration/astronvim/astrocommunity/#nvim-treesitter-sexp","title":"nvim-treesitter-sexp","text":"<p>Treesitter based structural editing with normal mode key mappings, which can be set to false to disable. Two commands are disabled in the example.</p> <p>Additional which-key keymaps can be included for greater discoverability. Example includes keymaps inspired by Spacemacs Lisp mode, <code>SPC k</code>.</p> <pre><code>  { import = \"astrocommunity.pack.clojure\" },\n  {\n    \"PaterJason/nvim-treesitter-sexp\",\n    dependencies = {\n      \"AstroNvim/astrocore\",\n      opts = {\n        -- configuration &amp; keymaps overrides:\n        -- https://github.com/PaterJason/nvim-treesitter-sexp#configuration\n        -- enabled = false,  -- Set to false to disable individual keymaps\n        -- set_cursor = true,\n        -- keymaps = {\n        -- Default key bindings - set to false to disable\n        --   commands = {\n        --     promote_elem = false,\n        --     promote_form = false,\n        --   },\n        --   motions = {\n        --   },\n        --   textobjects = {\n        --   },\n        -- },\n        options = {\n          g = {},\n        },\n        mappings = {\n          n = {\n            -- Additional Which-key key bindings for nvim-treesitter-sexp\n            [\"&lt;Leader&gt;k\"] = { name = \"Structural Editing\" },\n            [\"&lt;Leader&gt;kE\"] = { \"&lt;Cmd&gt;TSSexp swap_prev_elem&lt;CR&gt;\", desc = \"Swap Previous Element\" },\n            [\"&lt;Leader&gt;ke\"] = { \"&lt;Cmd&gt;TSSexp swap_next_elem&lt;CR&gt;\", desc = \"Swap Previous Element\" },\n            [\"&lt;Leader&gt;kF\"] = { \"&lt;Cmd&gt;TSSexp swap_prev_form&lt;CR&gt;\", desc = \"Swap Previous Form\" },\n            [\"&lt;Leader&gt;kf\"] = { \"&lt;Cmd&gt;TSSexp swap_next_form&lt;CR&gt;\", desc = \"Swap Previous Form\" },\n            [\"&lt;Leader&gt;kk\"] = { \"&lt;Cmd&gt;TSSexp promote_elem&lt;CR&gt;\", desc = \"Promote Element\" },\n            [\"&lt;Leader&gt;kr\"] = { \"&lt;Cmd&gt;TSSexp promote_form&lt;CR&gt;\", desc = \"Promote Form\" },\n            [\"&lt;Leader&gt;k@\"] = { \"&lt;Cmd&gt;TSSexp splice&lt;CR&gt;\", desc = \"Splice\" },\n            [\"&lt;Leader&gt;kS\"] = { \"&lt;Cmd&gt;TSSexp slurp_left&lt;CR&gt;\", desc = \"Slurp Left\" },\n            [\"&lt;Leader&gt;ks\"] = { \"&lt;Cmd&gt;TSSexp slurp_right&lt;CR&gt;\", desc = \"Slurp Right\" },\n            [\"&lt;Leader&gt;kB\"] = { \"&lt;Cmd&gt;TSSexp barf_left&lt;CR&gt;\", desc = \"Barf Left\" },\n            [\"&lt;Leader&gt;kb\"] = { \"&lt;Cmd&gt;TSSexp barf_right&lt;CR&gt;\", desc = \"Barf Right\" },\n            [\"&lt;Leader&gt;kI\"] = { \"&lt;Cmd&gt;TSSexp barf_right&lt;CR&gt;\", desc = \"Insert Head\" },\n            [\"&lt;Leader&gt;ki\"] = { \"&lt;Cmd&gt;TSSexp barf_right&lt;CR&gt;\", desc = \"Insert Tail\" },\n          },\n          t = {\n            -- terminal? mode key bindings\n          },\n          v = {\n            -- visual mode key bindings\n          },\n        },\n      },\n    },\n  },\n</code></pre>"},{"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 Config Redux has been archived</p> <p>Practicalli Neovim uses the AstroNvim config.</p> <p></p> <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> Kitty Terminal</li> <li>Clojure tooling and a Java SDK (Java Virtual Machine)</li> <li>Neovim 0.10.x</li> <li>Practicalli AstroNvim User Config rich community configuration which is highly configurable</li> <li>NerdFonts icon support in themes and status line</li> <li>Optional: Neovide GUI for Neovim</li> </ul> <p>Neovim 0.10.0 latest stable release</p> <p>Content and configuration in this book has been tested against Neovim 0.10.0 but not against Neovim nightly builds.</p> <p>Already installed?</p> <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/neovide/","title":"Neovide GUI","text":"<p>Neovide provides a GUI for Neovim and supports the use of AstroNvim community configuration.</p> <p> Neovide features</p>"},{"location":"install/neovide/#install-neovide","title":"Install Neovide","text":"<p> Download from Neovide.dev website</p> DebianMacOSX <p>Download neovide.AppImage</p> <p>Move the <code>neovide.AppImage</code> to the execution path, e.g. <code>$HOME/.local/bin</code></p> <p>Create the <code>$HOME/.local/bin/neovide</code> symbolic link pointing to the neovide.AppImage</p> <pre><code>ln -s $HOME/.local/bin/neovide.AppImage $HOME/.local/bin/neovide\n</code></pre> <p>Download the MacOSX dmg.zip file</p> <p>Extract the .zip file </p> <p>Run the extracted dmg file and use the install wizard to copy Neovide to the Applications directory.</p> <p>Create symbolic link from Neovide install to <code>~/.local/bin</code> </p> <pre><code>ln -s /Applications/neovide.app/Contents/MacOS/neovide ~/.local/bin/neovide\n</code></pre> <p>Add alias to use neovide with astronvim configuration to <code>.bashrc</code> , <code>.zshrc</code> or shared <code>shell-aliases</code> file</p> <pre><code>alias neovide=\"NVIM_APPNAME=astronvim neovide\"\n</code></pre>"},{"location":"install/neovide/#neovide-with-nvim_appname","title":"Neovide with NVIM_APPNAME","text":"<p><code>NVIM_APPNAME</code> sets the configuration used when starting Neovim.</p> <p>Use a shell alias to run Neovide with a specific configuration</p> <pre><code># Neovide alias with AstroNvim configuration\nalias neovide=\"NVIM_APPNAME=astronvim neovide\"\n</code></pre>"},{"location":"install/neovide/#set-neovide-font","title":"Set Neovide Font","text":"<p>The <code>guifont</code> Neovim option is used to set a font family and size specifically for a GUI appliction, i.e. Neovide.  It is not used by Neovim itself.</p> <p>Neovide font family and size</p> <pre><code>guifont = \"Fira Code:h16\"\n</code></pre> <p>AstroNvim Neovide font family and size</p> <p> Practicalli AstroNvim Config includes the <code>guifont</code> option in the <code>options.lua</code> file.</p> options.lua<pre><code>return {\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 = true,           -- sets vim.opt.wrap\n    -- showtabline = 0,    -- sets vim.opt.showtabline - zero hides tabs\n    timeoutlen = 420,\n    -- neovide font family &amp; size\n    guifont = \"Fira Code:h16\",\n  },\n}\n</code></pre> <p></p>"},{"location":"install/neovim/","title":"Install Neovim","text":"<p>The  Neovim release page includes install steps for specific operating system.</p> <p>Neovim 0.9 is the minimum version for this configuration and Neovim 0.9.4 is currently being used by Practicalli.</p> <p>Follow the install Neovim guide for the specific operating system.</p> <p> Neovim releases</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>Install the following tools to support Neovim and AstroNvim</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> x11 clipboard as a provider for Neovim copy/paste (Linux only)</li> <li><code>luarocks</code> for LSP servers (AstroNvim)</li> </ul> <p>Treesitter requires a C compiler</p> <p>nvim-treesitter requires a C compiler , e.g. <code>gcc</code> for Linux or <code>clang</code> for android/termix</p> <p>The C compiler is used to compile langauge support for treesiter.</p> <p>AstroNvim requires node.js</p> <p>AstroNvim uses Mason to install LSP servers, format and lint tools. Many of the LSP servers require node.</p> <p>Node.js install - Practicalli Engineering Playbook </p> Debian PackagesMacOSX Homebrew <pre><code>sudo apt install fd-find 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</p> <pre><code>sudo apt install wl-clipboard\n</code></pre> <p>MacOSX requires the libintl and gettext tools as well as the other supporting tools.</p> <pre><code>brew install libintl gettext ripgrep fd luarocks\n</code></pre>"},{"location":"install/neovim/#install-neovim_1","title":"Install Neovim","text":"<p>Use the GitHub releases for the latest version of Neovim, or use a Package manager for the operating system if the version of Neovim is 0.9.x</p> Linux AppImageMacOSX HomebrewMacOSX GitHub ReleaseDebian PackageBuild from Source <p>Download the Linux 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 $HOME/.local/bin/nvim.appimage\n</code></pre> <p>Create a symbolic link called <code>nvim</code> to the nvim.appimage file.</p> <pre><code>ln -s $HOME/.local/bin/nvim.appimage $HOME/.local/bin/nvim\n</code></pre> <p><code>nvim</code> command can now be run in a terminal from any directory.</p> <p>Install from Homebrew or via the Neovim Release page</p> <p>Homebrew <pre><code>brew install neovim\n</code></pre></p> <p>Neovim Release</p> <p>Download <code>nvim-macos.tar.gz</code> From the Neovim GitHub release page</p> <p>Avoid \"unknown developer\" warning from MacOSX</p> <pre><code>xattr -c ./nvim-macos.tar.gz\n</code></pre> <p>Make a local apps directory for neovim (and other things like node.js, etc.)</p> <pre><code>mkdir -P ~/.local/apps\n</code></pre> <p>Extract the neovim archive</p> <pre><code>tar zvxf nvim-macos.tar.gz -C ~/.local/apps/\n</code></pre> <p>Create the <code>~/.local/bin/nvim</code> symbolic link to include Neovim on the OS execution path </p> <p><code>echo $PATH</code> to check <code>.local/bin</code> is included in the execution the path by the Operating System command line shell</p> <pre><code>ln -s ~/.local/apps/nvim-macos/bin/nvim ~/.local/bin/nvim\n</code></pre> <p>Run\u00a0<code>nvim</code>  (or setup a Neovim configuration first, e.g. AstroNvim)</p> <p>From the Neovim GitHub release page:</p> <ol> <li>Install\u00a0<code>libintl</code>and\u00a0<code>gettext</code>\u00a0(e.g. via\u00a0<code>brew install libintl gettext</code>)</li> <li>Download\u00a0nvim-macos.tar.gz</li> <li>Run\u00a0<code>xattr -c ./nvim-macos.tar.gz</code>\u00a0(to avoid \"unknown developer\" warning)</li> <li>Make local apps directory for neovim (and other things like node.js, etc.)</li> </ol> <pre><code>mkdir -P ~/.local/apps\n</code></pre> <ol> <li>Extract the neovim download</li> </ol> <pre><code>tar zvxf nvim-macos.tar.gz -C ~/.local/apps/\n</code></pre> <ol> <li>Create nvim symbolic link in <code>~/.local/bin</code> to include Neovim on the OS execution path (check <code>.local/bin</code> is added to the execution the path by the Operating System command line shell)</li> </ol> <pre><code>ln -s ~/.local/apps/nvim-macos/bin/nvim ~/.local/bin/nvim\n</code></pre> <p>Linux version only packaged as AppImage from Neovim 0.9 onward</p> <p>A <code>.deb</code> file can be created after building Neovim from source.</p> <p> Neovim build guide</p> <p> Neovim Build Prerequisites for each operating system</p> 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> <pre><code>git clone --origin neovim https://github.com/neovim/neovim.git\n</code></pre> <p>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\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":"install/tools-fonts/","title":"Recommended Tools and Fonts","text":"<p>Neovim is a terminal based application so use of a quality terminal is recommended, e.g. Kitty Terminal (or iTerm2 if only on MacOSX)</p> <p>External Command line tools support search and other system information based features presented in AstroNvim.</p> <p>Nodejs supports Language Server protocol servers, format and lint tools installed by Mason.</p>"},{"location":"install/tools-fonts/#kitty-terminal-with-nerd-fonts","title":"\"Kitty Terminal with Nerd Fonts\"","text":"<p>Neovim runs in a terminal, so using Kitty (or iTerm2 - MacOSX only) are good options.  Nerd fonts provides additional symbols on top of the terminal font, providing a richer experience.</p> <p> Kitty Terminal - Practicalli Engineering Playbook provides examples of using Nerd Fonts or Nerd Font symbols with the Kitty terminal.</p> <p>Nerd Fonts </p>"},{"location":"install/tools-fonts/#command-line-tools","title":"Command line tools","text":"<ul> <li>ripgrep text search tool</li> <li>fzf fuzzy finder </li> <li>gdu </li> <li>btm from  GitHub repository releases</li> </ul> Debian packagesHomebrew <p>Install fzf, gdu and node.js via debian package manager <pre><code>apt install fzf gdu\n</code></pre></p> <p>Install fzf, gdu and node.js via Homebrew package manager <pre><code>brew install fzf gdu\n</code></pre></p> <p>Install btm from its  GitHub repository release page</p>"},{"location":"install/tools-fonts/#nodejs-for-lsp-format-lint-tools","title":"nodejs for LSP, format &amp; lint tools","text":"<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>"},{"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>Pull Request Commits must be cryptographically signed</p> <p>All commits contributed to Practicalli must be signed via a legitimate SSH or GPG key to avoid the risk of commit spoofing.</p> <p>Configure commit signing with SSH key - Practicalli Engineering</p> <p>All pull requests must include an entry in CHANGELOG.md or will not be merged.  A changelog entry allows the community to follow the changes to the book.</p> <p>Each pull request will have a number of CI workflows run against the contribution, checking the format of the content and if a changelog entry has been provided.</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 be closed without merging as these take considerable time to review.</p> <p>Issues such as grammar improvements are typically a sign of a rushed section that requires a rewrite, so a pull request to fix a typeographic error will probably not be merged.  Raise an issue, or post a thread in the  Clojurians Slack #practicall channel</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>Neovim News for new developments</p> <p>Keep up to date with new features within Neovim</p> <p><pre><code>:help news.txt\n</code></pre> Use the version name to view specific features of a release <pre><code>:help news-0.9.5.txt\n</code></pre></p>"},{"location":"introduction/features/#neovim-features-for-development","title":"Neovim features for development","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> Configure hidden files <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 / 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>Space W was added to Practicalli Astro Config as a key binding for <code>:write path/to/filename</code> which writes the current buffer to a new file, prompting for the file name.</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/#directories","title":"Directories","text":"<p>a in Neotree to create a file or by adding a ++forward-slash++ at the end of the name a directory is created.</p> <p>Use the <code>mkdir</code> shell command to create a new directory, which is created relative to the current path, which can be checked with <code>:lcd</code></p> <p><code>:!mkdir full/path/to/new/directory</code></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> <pre><code>:!mkdir -p %:h\n</code></pre> <p><code>mkdir -p</code> - the UNIX command to create a folder, the <code>-p</code> option creating any parts of the path required to make the full path</p> <p><code>%</code> - name of the current file </p> <p><code>:h</code> - for the current directory (the \u201chead\u201d of the path). </p> <p><code>!</code> - the NeoVim terminal shell command</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>Multi-modal editing has several states optomised for interacting with text</p> <ul> <li>normal - manipulating and navigating existing text (default state)</li> <li>insert - writing new text</li> <li>visual - selecting blocks of text</li> </ul> <p>Normal mode to insert mode:</p> <ul> <li>i insert before the cursor</li> <li>a append after the curor</li> <li>o insert on new line after current line</li> <li>i insert a new line previous to current line</li> </ul> <p>v to enter visual select, using navigation and/or motions to select a range.</p> <p>Esc to leave insert or visual mode and return to normal mode.</p>"},{"location":"neovim-basics/multi-modal-editing/#command-language","title":"Command language","text":"<p>Learn to speak modal editing commands as sentences to effectively learn Multi-modal editing</p> <p>Verbs start the sentence and are the action to perform</p> <ul> <li>c change</li> <li>d delete</li> <li>f find character</li> <li>g go</li> <li>s substitute</li> <li>v visual select</li> <li>y yank (copy)</li> </ul> <p>Modifiers (motions) follow verbs and define where the cursor moves to.</p> <ul> <li>' a mark location</li> <li>{ } beginning/end of paragraph</li> <li>a around</li> <li>f find (includes character)</li> <li>i inside</li> <li>S surround (nvim-surround) t till (up until)</li> </ul> <p>Text objects provide scope for verbs and modifiers</p> <ul> <li>b block/parentheses</li> <li>p paragraph</li> <li>s sentence  </li> <li>t tag, e.g. html/xml tag</li> <li>w word</li> <li>W word delimited by only space</li> </ul> Examples of speaking Evil <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 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>SPC v s \"</code> visually select current work and surround with <code>\"\"</code> <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>) <p>Evil Reference and Tips</p> <p>Evil quick reference guide Evil tips for developers Speaking Vim</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> <p>Practicalli Spacemacs - Evil reference</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/navigation/","title":"Navigation","text":"<p>Move the cursor one space at a time </p> <ul> <li>h move left</li> <li>j move down</li> <li>k move up</li> <li>l move right</li> </ul>"},{"location":"neovim-basics/navigation/#jump-along-line","title":"Jump along line","text":"<p>Move to specific points within a line</p> <ul> <li>w jump to start of next word</li> <li>b jump to start of word</li> <li>e jump to end of next word</li> <li>$ jumps to end of line</li> <li>0 jumps to start of line</li> <li>^ jumps to first character of line</li> </ul> <p>Uppercase w b e consider word delimited by blank characters</p> <p>Jump joined-word using W B E </p> <p>Use w b e movement with a number to move the cursor larger distances</p> jump 3 words forward<pre><code>3w\n</code></pre> <p>f jumps forward in the current line to the given character</p> jump to next q character<pre><code>fq\n</code></pre> <p>F jumps backward in the current line to the given character</p> jump to previous [ character<pre><code>F[\n</code></pre> <p>t jumps forward in the current line to before the given character</p> jump before q character<pre><code>tq\n</code></pre> <p>T jumps backward in the current line to after the given character</p> jump after [ character<pre><code>T[\n</code></pre>"},{"location":"neovim-basics/navigation/#jump-around-buffer","title":"Jump around buffer","text":"<ul> <li>H jump to top of window</li> <li>M jump to middle of window</li> <li>L jump to bottom of window</li> <li>{ jump to previous paragraph</li> <li>} jump to next paragraph</li> <li>gg jump to first character of line</li> <li>G jump to first character of line</li> </ul> <p>Use cursor movement with a number to move the cursor larger distances</p> jump down 12 lines<pre><code>12j\n</code></pre> Relative line numbers for line navigation <p>Enable relative line numbers to show how far away from the current line each other line is.</p> <pre><code>set relativenumber\nset number\n</code></pre> <p>Practicalli AstroNvim-Config enables relative line numbers</p> <p>Jump to a specific line using the number as a command</p> jump to line number<pre><code>:127\n</code></pre>"},{"location":"neovim-basics/navigation/#navigate-position-history","title":"Navigate position history","text":"<p>++ctrl+\"o\" jumps to a previous postion in the cursor history</p> <p>++ctrl+\"i\" jumps to a previous postion in the cursor history</p>"},{"location":"neovim-basics/navigation/#file-marks","title":"File marks","text":"<p>Navigate within the current file or globally using file marks.</p> <p>m followed by a lower case character creates a mark within the current file.</p> <p>m followed by an upper case character creates a global mark.</p> <p>` (backtick) followed by a character jumps to the mark created</p> <p>Space f ' displays marks in telescope popup</p> <p>File marks within file</p> <p>m f creates a mark lablled <code>f</code></p> <p>` f jumps to the mark labelled <code>f</code></p> Global mark to jump between source and test code <p>m S with the cursor in the source code file.</p> <p>m T with the cursor in the test code file.</p> <p>` S to jump to the source code</p> <p>` T to jump to the source code</p>"},{"location":"neovim-basics/navigation/#jumplist","title":"Jumplist","text":"<p><code>:jumps</code> shows the Neovim jumplist containing all points from any buffer recently jumped to using neovim commands</p> <ul> <li>Ctrl o jump back </li> <li>Ctrl i jump forward </li> <li>ctrl and navigation key (hjkl) to move to changelist window</li> <li>q closes the jumplist buffer</li> </ul>"},{"location":"neovim-basics/navigation/#changes","title":"Changes","text":"<p><code>:changes</code> shows the Neovim changelist containing all points in the current buffer which have changed</p> <ul> <li>g ; jump back (previous edit)</li> <li>g . jump forward</li> <li>ctrl and navigation key (hjkl) to move to changelist window</li> <li>q closes the changelist buffer</li> </ul>"},{"location":"neovim-basics/navigation/#navigation-menus","title":"Navigation menus","text":"<ul> <li>[ ( &amp;  ] ) previous &amp; next paren</li> <li>[ brace-left &amp;  ] brace-right previous and next square brackets</li> <li>[ g &amp;  ] g previous and next Git hunks</li> <li>[ s &amp;  ] s previous and next misspelled wor</li> <li>d</li> </ul>"},{"location":"neovim-basics/navigation/#search-in-buffer","title":"Search in buffer","text":"<p>/ searches buffer for the following pattern</p> <ul> <li>n jumps to next match</li> <li>N jumps to previous match</li> </ul> <p>AstroNvim user config enables <code>incsearch</code> incremental search and <code>hlsearch</code> to highlight every search match</p>"},{"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/registers/","title":"Neovim Registers","text":"<p>Neovim use registers to store and access text using Neovim commands.</p> <p>\" to access a register by name.</p> <p>The name of a register is a number, alphabetical or special character.</p> <p><code>SPC f r</code> lists the values of registers in a telescope popup</p> Yank and paste commit message <p>Select the text of the commit message</p> <p>\" m y yanks the selected text into register <code>m</code></p> <p>Complete the Git commit.  When creating a new commit, paste the message from the register</p> <p>\" m p pastes the register text into the commit message buffer</p> Paste last evaluation result from Conjure <p>When Conjure evaluates code the result is stored in the <code>C</code> register. </p> <p>\" C p pastes the register text into the commit message buffer</p>"},{"location":"neovim-basics/registers/#registers","title":"Registers","text":"<p>Neovim help - registers</p> <pre><code>:help registers\n</code></pre> <p>\" the unnamed register, used by Neovim normal commands, e.g. <code>c</code> <code>d</code> <code>p</code> <code>s</code> <code>x</code> <code>y</code>, etc.</p> <p>0 to 9 numbered registers containing yank and delete history</p> <p>- small delete register for text smaller than a line</p> <p>a to z named registers manually selected, A to Z to append to the text already in the register</p> <p>: . and % read-only registers use with put commands (last inserted, current file name, recent command)</p> <p># alternate buffer file name</p> <p>= expression register for the result of runing a Neovim command expression</p> <p>+ and * selection registers for GUI</p> <p>_ black hole register does not store text, use when normal commands shouldnt update other registers</p> <p>/ last search pattern register used</p>"},{"location":"neovim-basics/registers/#find-registers","title":"Find Registers","text":"<p><code>SPC f r</code> opens the list of registers in a telescope popup.</p> <p> </p> <p>Registers in insert mode</p> <p><code>C-r</code> in insert mode pastes the content of the given register, e.g. <code>C-r a</code> to paste the content of <code>\"a</code></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  multiple cursors in more detail for in-place editing (visual-multi plugin) </li> <li><code>:%substitue</code> <code>:substitue</code> neovim command for search and replace</li> </ul> <p>Search and replace across a project:</p> <ul> <li>Space s 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> Normal mode 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":"AstroNvimNeovim commands <p>Telescope and :cdo</p> <p>Space f w to search for a word</p> <p>Ctrl q opens the quickfix list</p> <p>Use <code>:cdo</code> command to search and replace in the quickfix list</p> <pre><code>:cdo %s/current-pattern/new-pattern/g\n</code></pre> <p>Including the <code>c</code> option to confirm each replacement (using a noice popup when using Practicalli AstroNvim-config)</p> <p>Spectre</p> <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>Evaluating :cdo command as a project wide search replace</p> <p>:cdo command could be used to search and replace within the results of a tool that finds matching patterns across a project</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/spectre/","title":"Spectre","text":"<p>Space s s to toggle Spectre (open/close) to search and replace tool.</p> <p><code>?</code> for the Spectre key mappings</p> <p></p>"},{"location":"neovim-basics/search-replace/spectre/#search-replace","title":"Search &amp; Replace","text":"<p>i underneath Search and enter a search pattern, Esc to see resuts in a popup below.</p> <p>i underneath Replace and enter a replace pattern, Esc to see in-line diff results</p> <p>v toggles Spectre results view between diff to search to replace view</p> <p> </p> <p>d d to toggle an occurance </p> <p>R replaces all occurances (after selecting the occurances to change)</p> <p>A DONE checkbox is show at then end of each selection which has been reaplaced</p> <p>To replace single occurance, toggle all occurances that should not be changes and press R</p> <p> </p> <p>Spectre does not undo changes</p> <p>Use Git or Neovim undo to rollback changes made by Spectre.</p> <p> Spectre is available via the AstroNvim Community project pack and included in the Practicalli astronvim-config    </p> <p> ripgrep and  sed are required.</p> <p> Spectre project </p>"},{"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/modal-editing/","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/modal-editing/#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/modal-editing/#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/modal-editing/#text-wrangling","title":"Text wrangling","text":"<ul> <li>iedit</li> <li>text case</li> </ul>"},{"location":"reference/modal-editing/#clojure-editing","title":"Clojure Editing","text":"<p>traversing expressions  structural editing </p>"},{"location":"reference/modal-editing/case/","title":"Modifying text case","text":"<p>Convert Characters and regioins to upper or lower case text.</p>"},{"location":"reference/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/key-binding-reference/","title":"Evil Keybinding Reference","text":"<p>An alphabetically ordered reference of Vim-style key bindings.</p>"},{"location":"reference/modal-editing/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/modal-editing/motions/","title":"Motions","text":"<p>Todo</p> <p>Moving the cursor around by context rather than individual characters</p>"},{"location":"reference/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/narrowing/#documentation","title":"Documentation","text":"<p><code>:help NarrowRegion</code> to view the documetation on the NrrwRgn plug use</p>"},{"location":"reference/modal-editing/narrowing/#attention","title":"Attention","text":"<p><code>:NRM</code> is described as experimental by the project readme.</p>"},{"location":"reference/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/visual-select/#line-and-block","title":"Line and block","text":"<p>V enters visual line select mode</p> <p>j and k alter the selection by line</p> <p>Ctrl+v enters visual region select mode</p> <p>Switch between visual modes</p> <p>Once in visual mode: </p> <p>V switches to visual line mode Ctrl+v switches to visual line mode</p>"},{"location":"reference/modal-editing/z-menu/","title":"Evil Z menu","text":"<p><code>z</code> in normal mode opens a menu of convenient utilities</p>"},{"location":"reference/modal-editing/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/modal-editing/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/modal-editing/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":"reference/neovim/","title":"Neovim Reference","text":"<ul> <li>Language Providers</li> <li>Key mappings</li> </ul>"},{"location":"reference/neovim/changelist/","title":"Changelist","text":"<p>Initial draft - feedback welcome</p> <pre><code>:help :changelist\n</code></pre> <p>View changelist</p> <pre><code>:changes\n</code></pre> <ul> <li>ctrl and navigation key (hjkl) to move to changelist window</li> <li>q closes the changelist buffer</li> </ul>"},{"location":"reference/neovim/jumplist/","title":"Jumplist","text":"<p>Initial draft - feedback welcome</p> <pre><code>:help :jumplist\n</code></pre> <p>View jumplist</p> <pre><code>:jumps\n</code></pre> <ul> <li>ctrl and navigation key (hjkl) to move to jumplist window</li> <li>q closes the jumplist buffer</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/quickfix/","title":"Quickfix","text":"<p>Initial draft - feedback welcome</p>"},{"location":"reference/neovim/quickfix/#quickfix-mode","title":"quickfix mode","text":"Open quickfix in window<pre><code>:ccopen\n</code></pre> <p>Use j k to navigate the list or <code>:cc</code> and a number to jump to a result</p> jump to the 7th result<pre><code>:cc 7\n</code></pre> <ul> <li>ctrl and navigation key (hjkl) to move to quickfix window</li> <li>q closes the quickfix buffer</li> </ul>"},{"location":"reference/neovim/quickfix/#tools","title":"Tools","text":"<ul> <li>qf.nvim - Quickfix and location list management for Neovim</li> <li>nvim-bqf enhanced quickfix window</li> </ul> <p>Quickfix is a mode to show results of another command</p> <ul> <li>a make compile task</li> <li>the results of a search</li> <li>lsp analysis errors</li> </ul> <p>Quickfix buffer can be used to jump through the errors one by one.  Each error can be viewe and fix it in turn. </p> <p>quickfix is used to find a list of positions in files.  </p> <ul> <li>:vimgrep| finds pattern matches.  </li> </ul> <p>The 'errorformat' option should be set to match the error messages from your compiler (see |errorformat| below).</p> <pre><code>                        *quickfix-ID*\n</code></pre> <p>Each quickfix list has a unique identifier called the quickfix ID and this number will not change within a Vim session. The |getqflist()| function can be used to get the identifier assigned to a list. There is also a quickfix list number which may change whenever more than ten lists are added to a quickfix stack.</p> <pre><code>                    *location-list* *E776*\n</code></pre> <p>A location list is a window-local quickfix list. You get one after commands like <code>:lvimgrep</code>, <code>:lgrep</code>, <code>:lhelpgrep</code>, <code>:lmake</code>, etc., which create a location list instead of a quickfix list as the corresponding <code>:vimgrep</code>, <code>:grep</code>, <code>:helpgrep</code>, <code>:make</code> do.                         location-list-file-window A location list is associated with a window and each window can have a separate location list.  A location list can be associated with only one window.  The location list is independent of the quickfix list.</p> <p>When a window with a location list is split, the new window gets a copy of the location list.  When there are no longer any references to a location list, the location list is destroyed.</p> <pre><code>                    *quickfix-changedtick*\n</code></pre> <p>Every quickfix and location list has a read-only changedtick variable that tracks the total number of changes made to the list.  Every time the quickfix list is modified, this count is incremented. This can be used to perform an action only when the list has changed.  The |getqflist()| and |getloclist()| functions can be used to query the current value of changedtick.  You cannot change the changedtick variable.</p> <p>The following quickfix commands can be used.  The location list commands are similar to the quickfix commands, replacing the 'c' prefix in the quickfix command with 'l'.</p> <pre><code>                        *E924*\n</code></pre> <p>If the current window was closed by an |autocommand| while processing a location list command, it will be aborted.</p> <pre><code>                        *E925* *E926*\n</code></pre> <p>If the current quickfix or location list was changed by an |autocommand| while processing a quickfix or location list command, it will be aborted.</p> <pre><code>                        *:cc*\n</code></pre> <p>:cc[!] [nr]     Display error [nr].  If [nr] is omitted, the same :[nr]cc[!]      error is displayed again.  Without [!] this doesn't             work when jumping to another buffer, the current buffer             has been changed, there is the only window for the             buffer and both 'hidden' and 'autowrite' are off.             When jumping to another buffer with [!] any changes to             the current buffer are lost, unless 'hidden' is set or             there is another window for this buffer.             The 'switchbuf' settings are respected when jumping             to a buffer.             When used in the quickfix window the line number can             be used, including \".\" for the current line and \"$\"             for the last line.</p> <pre><code>                        *:ll*\n</code></pre> <p>:ll[!] [nr]     Same as \":cc\", except the location list for the :[nr]ll[!]      current window is used instead of the quickfix list.</p> <pre><code>                    *:cn* *:cne* *:cnext* *E553*\n</code></pre> <p>:[count]cn[ext][!]  Display the [count] next error in the list that             includes a file name.  If there are no file names at             all, go to the [count] next error.  See |:cc| for             [!] and 'switchbuf'.</p> <pre><code>                        *:lne* *:lnext*\n</code></pre> <p>:[count]lne[xt][!]  Same as \":cnext\", except the location list for the             current window is used instead of the quickfix list.</p> <p>:[count]cN[ext][!]      :cp :cprevious :cprev :cN :cNext :[count]cp[revious][!]  Display the [count] previous error in the list that             includes a file name.  If there are no file names at             all, go to the [count] previous error.  See |:cc| for             [!] and 'switchbuf'.</p> <p>:[count]lN[ext][!]      :lp :lprevious :lprev :lN :lNext :[count]lp[revious][!]  Same as \":cNext\" and \":cprevious\", except the location             list for the current window is used instead of the             quickfix list.</p> <pre><code>                        *:cabo* *:cabove*\n</code></pre> <p>:[count]cabo[ve]    Go to the [count] error above the current line in the             current buffer.  If [count] is omitted, then 1 is             used.  If there are no errors, then an error message             is displayed.  Assumes that the entries in a quickfix             list are sorted by their buffer number and line             number. If there are multiple errors on the same line,             then only the first entry is used.  If [count] exceeds             the number of entries above the current line, then the             first error in the file is selected.</p> <pre><code>                        *:lab* *:labove*\n</code></pre> <p>:[count]lab[ove]    Same as \":cabove\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cbel* *:cbelow*\n</code></pre> <p>:[count]cbel[ow]    Go to the [count] error below the current line in the             current buffer.  If [count] is omitted, then 1 is             used.  If there are no errors, then an error message             is displayed.  Assumes that the entries in a quickfix             list are sorted by their buffer number and line             number.  If there are multiple errors on the same             line, then only the first entry is used.  If [count]             exceeds the number of entries below the current line,             then the last error in the file is selected.</p> <pre><code>                        *:lbel* *:lbelow*\n</code></pre> <p>:[count]lbel[ow]    Same as \":cbelow\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cbe* *:cbefore*\n</code></pre> <p>:[count]cbe[fore]   Go to the [count] error before the current cursor             position in the current buffer.  If [count] is             omitted, then 1 is used.  If there are no errors, then             an error message is displayed.  Assumes that the             entries in a quickfix list are sorted by their buffer,             line and column numbers.  If [count] exceeds the             number of entries before the current position, then             the first error in the file is selected.</p> <pre><code>                        *:lbe* *:lbefore*\n</code></pre> <p>:[count]lbe[fore]   Same as \":cbefore\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:caf* *:cafter*\n</code></pre> <p>:[count]caf[ter]    Go to the [count] error after the current cursor             position in the current buffer.  If [count] is             omitted, then 1 is used.  If there are no errors, then             an error message is displayed.  Assumes that the             entries in a quickfix list are sorted by their buffer,             line and column numbers.  If [count] exceeds the             number of entries after the current position, then             the last error in the file is selected.</p> <pre><code>                        *:laf* *:lafter*\n</code></pre> <p>:[count]laf[ter]    Same as \":cafter\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cnf* *:cnfile*\n</code></pre> <p>:[count]cnf[ile][!] Display the first error in the [count] next file in             the list that includes a file name.  If there are no             file names at all or if there is no next file, go to             the [count] next error.  See |:cc| for [!] and             'switchbuf'.</p> <pre><code>                        *:lnf* *:lnfile*\n</code></pre> <p>:[count]lnf[ile][!] Same as \":cnfile\", except the location list for the             current window is used instead of the quickfix list.</p> <p>:[count]cNf[ile][!]         :cpf :cpfile :cNf :cNfile :[count]cpf[ile][!] Display the last error in the [count] previous file in             the list that includes a file name.  If there are no             file names at all or if there is no next file, go to             the [count] previous error.  See |:cc| for [!] and             'switchbuf'.</p> <p>:[count]lNf[ile][!]         :lpf :lpfile :lNf :lNfile :[count]lpf[ile][!] Same as \":cNfile\" and \":cpfile\", except the location             list for the current window is used instead of the             quickfix list.</p> <pre><code>                        *:crewind* *:cr*\n</code></pre> <p>:cr[ewind][!] [nr]  Display error [nr].  If [nr] is omitted, the FIRST             error is displayed.  See |:cc|.</p> <pre><code>                        *:lrewind* *:lr*\n</code></pre> <p>:lr[ewind][!] [nr]  Same as \":crewind\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cfirst* *:cfir*\n</code></pre> <p>:cfir[st][!] [nr]   Same as \":crewind\".</p> <pre><code>                        *:lfirst* *:lfir*\n</code></pre> <p>:lfir[st][!] [nr]   Same as \":lrewind\".</p> <pre><code>                        *:clast* *:cla*\n</code></pre> <p>:cla[st][!] [nr]    Display error [nr].  If [nr] is omitted, the LAST             error is displayed.  See |:cc|.</p> <pre><code>                        *:llast* *:lla*\n</code></pre> <p>:lla[st][!] [nr]    Same as \":clast\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cq* *:cquit*\n</code></pre> <p>:cq[uit][!] :{N}cq[uit][!] :cq[uit][!] {N}     Quit Vim with error code {N}.  {N} defaults to one.             Useful when Vim is called from another program:             e.g., a compiler will not compile the same file again,             <code>git commit</code> will abort the committing process, <code>fc</code>             (built-in for shells like bash and zsh) will not             execute the command, etc.             {N} can also be zero, in which case Vim exits             normally.             WARNING: All changes in files are lost.  It works like             \":qall!\" |:qall|, except that Nvim exits non-zero or             [count].</p> <pre><code>                        *:cf* *:cfi* *:cfile*\n</code></pre> <p>:cf[ile][!] [errorfile] Read the error file and jump to the first error.             This is done automatically when Vim is started with             the -q option.  You can use this command when you             keep Vim running while compiling.  If you give the             name of the errorfile, the 'errorfile' option will             be set to [errorfile].  See |:cc| for [!].             If the encoding of the error file differs from the             'encoding' option, you can use the 'makeencoding'             option to specify the encoding.</p> <pre><code>                        *:lf* *:lfi* *:lfile*\n</code></pre> <p>:lf[ile][!] [errorfile] Same as \":cfile\", except the location list for the             current window is used instead of the quickfix list.             You can not use the -q command-line option to set             the location list.</p> <p>:cg[etfile] [errorfile]                 :cg :cgetfile             Read the error file.  Just like \":cfile\" but don't             jump to the first error.             If the encoding of the error file differs from the             'encoding' option, you can use the 'makeencoding'             option to specify the encoding.</p> <p>:lg[etfile] [errorfile]                 :lg :lge :lgetfile             Same as \":cgetfile\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:caddf* *:caddfile*\n</code></pre> <p>:caddf[ile] [errorfile] Read the error file and add the errors from the             errorfile to the current quickfix list. If a quickfix             list is not present, then a new list is created.             If the encoding of the error file differs from the             'encoding' option, you can use the 'makeencoding'             option to specify the encoding.</p> <pre><code>                        *:laddf* *:laddfile*\n</code></pre> <p>:laddf[ile] [errorfile] Same as \":caddfile\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                    *:cb* *:cbuffer* *E681*\n</code></pre> <p>:cb[uffer][!] [bufnr]   Read the error list from the current buffer.             When [bufnr] is given it must be the number of a             loaded buffer.  That buffer will then be used instead             of the current buffer.             A range can be specified for the lines to be used.             Otherwise all lines in the buffer are used.             See |:cc| for [!].</p> <pre><code>                    *:lb* *:lbuffer*\n</code></pre> <p>:lb[uffer][!] [bufnr]   Same as \":cbuffer\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                    *:cgetb* *:cgetbuffer*\n</code></pre> <p>:cgetb[uffer] [bufnr]   Read the error list from the current buffer.  Just             like \":cbuffer\" but don't jump to the first error.</p> <pre><code>                    *:lgetb* *:lgetbuffer*\n</code></pre> <p>:lgetb[uffer] [bufnr]   Same as \":cgetbuffer\", except the location list for             the current window is used instead of the quickfix             list.</p> <pre><code>                    *:cad* *:cadd* *:caddbuffer*\n</code></pre> <p>:cad[dbuffer] [bufnr]   Read the error list from the current buffer and add             the errors to the current quickfix list.  If a             quickfix list is not present, then a new list is             created. Otherwise, same as \":cbuffer\".</p> <pre><code>                        *:laddb* *:laddbuffer*\n</code></pre> <p>:laddb[uffer] [bufnr]   Same as \":caddbuffer\", except the location list for             the current window is used instead of the quickfix             list.</p> <pre><code>                        *:cex* *:cexpr* *E777*\n</code></pre> <p>:cex[pr][!] {expr}  Create a quickfix list using the result of {expr} and             jump to the first error.             If {expr} is a String, then each newline terminated             line in the String is processed using the global value             of 'errorformat' and the result is added to the             quickfix list.             If {expr} is a List, then each String item in the list             is processed and added to the quickfix list.  Non             String items in the List are ignored.             See |:cc| for [!].             Examples:                 :cexpr system('grep -n xyz *')                 :cexpr getline(1, '$')</p> <pre><code>                        *:lex* *:lexpr*\n</code></pre> <p>:lex[pr][!] {expr}  Same as |:cexpr|, except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cgete* *:cgetexpr*\n</code></pre> <p>:cgete[xpr] {expr}  Create a quickfix list using the result of {expr}.             Just like |:cexpr|, but don't jump to the first error.</p> <pre><code>                        *:lgete* *:lgetexpr*\n</code></pre> <p>:lgete[xpr] {expr}  Same as |:cgetexpr|, except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cadde* *:caddexpr*\n</code></pre> <p>:cadde[xpr] {expr}  Evaluate {expr} and add the resulting lines to the             current quickfix list. If a quickfix list is not             present, then a new list is created. The current             cursor position will not be changed. See |:cexpr| for             more information.             Example:     :g/mypattern/caddexpr expand(\"%\") .. \":\" .. line(\".\") ..  \":\" .. getline(\".\")</p> <pre><code>                    *:lad* *:addd* *:laddexpr*\n</code></pre> <p>:lad[dexpr] {expr}  Same as \":caddexpr\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cl* *:clist*\n</code></pre> <p>:cl[ist] [from] [, [to]]             List all errors that are valid |quickfix-valid|.             If numbers [from] and/or [to] are given, the respective             range of errors is listed.  A negative number counts             from the last error backwards, -1 being the last error.             The |:filter| command can be used to display only the             quickfix entries matching a supplied pattern. The             pattern is matched against the filename, module name,             pattern and text of the entry.</p> <p>:cl[ist] +{count}   List the current and next {count} valid errors.  This             is similar to \":clist from from+count\", where \"from\"             is the current error position.</p> <p>:cl[ist]! [from] [, [to]]             List all errors.</p> <p>:cl[ist]! +{count}  List the current and next {count} error lines.  This             is useful to see unrecognized lines after the current             one.  For example, if \":clist\" shows:         8384 testje.java:252: error: cannot find symbol             Then using \":cl! +3\" shows the reason:         8384 testje.java:252: error: cannot find symbol         8385:   ZexitCode = Fmainx();         8386:               ^         8387:   symbol:   method Fmainx()  </p> <p>:lli[st] [from] [, [to]]                :lli :llist             Same as \":clist\", except the location list for the             current window is used instead of the quickfix list.</p> <p>:lli[st]! [from] [, [to]]             List all the entries in the location list for the             current window.</p> <p>If you insert or delete lines, mostly the correct error location is still found because hidden marks are used.  Sometimes, when the mark has been deleted for some reason, the message \"line changed\" is shown to warn you that the error location may not be correct.  If you quit Vim and start again the marks are lost and the error locations may not be correct anymore.</p> <p>Two autocommands are available for running commands before and after a quickfix command (':make', ':grep' and so on) is executed. See |QuickFixCmdPre| and |QuickFixCmdPost| for details.</p> <pre><code>                    *QuickFixCmdPost-example*\n</code></pre> <p>When 'encoding' differs from the locale, the error messages may have a different encoding from what Vim is using.  To convert the messages you can use this code:     function QfMakeConv()        let qflist = getqflist()        for i in qflist           let i.text = iconv(i.text, \"cp936\", \"utf-8\")        endfor        call setqflist(qflist)     endfunction</p> <pre><code>au QuickfixCmdPost make call QfMakeConv()\n</code></pre> <p>Another option is using 'makeencoding'.</p> <pre><code>                        *quickfix-title*\n</code></pre> <p>Every quickfix and location list has a title. By default the title is set to the command that created the list. The |getqflist()| and |getloclist()| functions can be used to get the title of a quickfix and a location list respectively. The |setqflist()| and |setloclist()| functions can be used to modify the title of a quickfix and location list respectively. Examples:     call setqflist([], 'a', {'title' : 'Cmd output'})     echo getqflist({'title' : 1})     call setloclist(3, [], 'a', {'title' : 'Cmd output'})     echo getloclist(3, {'title' : 1})</p> <pre><code>                        *quickfix-index*\n</code></pre> <p>When you jump to a quickfix/location list entry using any of the quickfix commands (e.g. |:cc|, |:cnext|, |:cprev|, etc.), that entry becomes the currently selected entry. The index of the currently selected entry in a quickfix/location list can be obtained using the getqflist()/getloclist() functions. Examples:     echo getqflist({'idx' : 0}).idx     echo getqflist({'id' : qfid, 'idx' : 0}).idx     echo getloclist(2, {'idx' : 0}).idx</p> <p>For a new quickfix list, the first entry is selected and the index is 1.  Any entry in any quickfix/location list can be set as the currently selected entry using the setqflist() function. Examples:     call setqflist([], 'a', {'idx' : 12})     call setqflist([], 'a', {'id' : qfid, 'idx' : 7})     call setloclist(1, [], 'a', {'idx' : 7})</p> <pre><code>                        *quickfix-size*\n</code></pre> <p>You can get the number of entries (size) in a quickfix and a location list using the |getqflist()| and |getloclist()| functions respectively. Examples:     echo getqflist({'size' : 1})     echo getloclist(5, {'size' : 1})</p> <pre><code>                        *quickfix-context*\n</code></pre> <p>Any Vim type can be associated as a context with a quickfix or location list. The |setqflist()| and the |setloclist()| functions can be used to associate a context with a quickfix and a location list respectively. The |getqflist()| and the |getloclist()| functions can be used to retrieve the context of a quickfix and a location list respectively. This is useful for a Vim plugin dealing with multiple quickfix/location lists. Examples:  </p> <pre><code>let somectx = {'name' : 'Vim', 'type' : 'Editor'}\ncall setqflist([], 'a', {'context' : somectx})\necho getqflist({'context' : 1})\n\nlet newctx = ['red', 'green', 'blue']\ncall setloclist(2, [], 'a', {'id' : qfid, 'context' : newctx})\necho getloclist(2, {'id' : qfid, 'context' : 1})\n\n                        *quickfix-parse*\n</code></pre> <p>You can parse a list of lines using 'errorformat' without creating or modifying a quickfix list using the |getqflist()| function. Examples:     echo getqflist({'lines' : [\"F1:10:Line10\", \"F2:20:Line20\"]})     echo getqflist({'lines' : systemlist('grep -Hn quickfix *')}) This returns a dictionary where the \"items\" key contains the list of quickfix entries parsed from lines. The following shows how to use a custom 'errorformat' to parse the lines without modifying the 'errorformat' option:     echo getqflist({'efm' : '%f#%l#%m', 'lines' : ['F1#10#Line']})</p> <p>EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST:                             :cdo :cdo[!] {cmd}       Execute {cmd} in each valid entry in the quickfix list.             It works like doing this:                 :cfirst                 :{cmd}                 :cnext                 :{cmd}                 etc.             When the current file can't be |abandon|ed and the [!]             is not present, the command fails.             When going to the next entry fails execution stops.             The last buffer (or where an error occurred) becomes             the current buffer.             {cmd} can contain '|' to concatenate several commands.</p> <pre><code>        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</code></pre> <p>:cfdo[!] {cmd}      Execute {cmd} in each file in the quickfix list.             It works like doing this:                 :cfirst                 :{cmd}                 :cnfile                 :{cmd}                 etc.             Otherwise it works the same as <code>:cdo</code>.</p> <pre><code>                        *:ldo*\n</code></pre> <p>:ld[o][!] {cmd}     Execute {cmd} in each valid entry in the location list             for the current window.             It works like doing this:                 :lfirst                 :{cmd}                 :lnext                 :{cmd}                 etc.             Only valid entries in the location list are used.             Otherwise it works the same as <code>:cdo</code>.</p> <pre><code>                        *:lfdo*\n</code></pre> <p>:lfdo[!] {cmd}      Execute {cmd} in each file in the location list for             the current window.             It works like doing this:                 :lfirst                 :{cmd}                 :lnfile                 :{cmd}                 etc.             Otherwise it works the same as <code>:ldo</code>.</p> <p>FILTERING A QUICKFIX OR LOCATION LIST:                     cfilter-plugin :Cfilter :Lfilter If you have too many entries in a quickfix list, you can use the cfilter plugin to reduce the number of entries.  Load the plugin with:  </p> <pre><code>packadd cfilter\n</code></pre> <p>Then you can use the following commands to filter a quickfix/location list:  </p> <pre><code>:Cfilter[!] /{pat}/\n:Lfilter[!] /{pat}/\n</code></pre> <p>The |:Cfilter| command creates a new quickfix list from the entries matching {pat} in the current quickfix list. {pat} is a Vim |regular-expression| pattern. Both the file name and the text of the entries are matched against {pat}. If the optional ! is supplied, then the entries not matching {pat} are used. The pattern can be optionally enclosed using one of the following characters: ', \", /. If the pattern is empty, then the last used search pattern is used.</p> <p>The |:Lfilter| command does the same as |:Cfilter| but operates on the current location list.</p> <p>The current quickfix/location list is not modified by these commands, so you can go back to the unfiltered list using the |:colder|/|:lolder| command.</p> <p>============================================================================= 2. The error window                 quickfix-window</p> <pre><code>                    *:cope* *:copen* *w:quickfix_title*\n</code></pre> <p>:cope[n] [height]   Open a window to show the current list of errors.</p> <pre><code>        When [height] is given, the window becomes that high\n        (if there is room).  When [height] is omitted the\n        window is made ten lines high.\n\n        If there already is a quickfix window, it will be made\n        the current window.  It is not possible to open a\n        second quickfix window.  If [height] is given the\n        existing window will be resized to it.\n\n                        *quickfix-buffer*\n        The window will contain a special buffer, with\n        'buftype' equal to \"quickfix\".  Don't change this!\n        The window will have the w:quickfix_title variable set\n        which will indicate the command that produced the\n        quickfix list. This can be used to compose a custom\n        status line if the value of 'statusline' is adjusted\n        properly. Whenever this buffer is modified by a\n        quickfix command or function, the |b:changedtick|\n        variable is incremented.  You can get the number of\n        this buffer using the getqflist() and getloclist()\n        functions by passing the \"qfbufnr\" item. For a\n        location list, this buffer is wiped out when the\n        location list is removed.\n\n                        *:lop* *:lopen*\n</code></pre> <p>:lop[en] [height]   Open a window to show the location list for the             current window. Works only when the location list for             the current window is present.  You can have more than             one location window opened at a time.  Otherwise, it             acts the same as \":copen\".</p> <pre><code>                        *:ccl* *:cclose*\n</code></pre> <p>:ccl[ose]       Close the quickfix window.</p> <pre><code>                        *:lcl* *:lclose*\n</code></pre> <p>:lcl[ose]       Close the window showing the location list for the             current window.</p> <pre><code>                        *:cw* *:cwindow*\n</code></pre> <p>:cw[indow] [height] Open the quickfix window when there are recognized             errors.  If the window is already open and there are             no recognized errors, close the window.</p> <pre><code>                        *:lw* *:lwindow*\n</code></pre> <p>:lw[indow] [height] Same as \":cwindow\", except use the window showing the             location list for the current window.</p> <pre><code>                        *:cbo* *:cbottom*\n</code></pre> <p>:cbo[ttom]      Put the cursor in the last line of the quickfix window             and scroll to make it visible.  This is useful for             when errors are added by an asynchronous callback.             Only call it once in a while if there are many             updates to avoid a lot of redrawing.</p> <pre><code>                        *:lbo* *:lbottom*\n</code></pre> <p>:lbo[ttom]      Same as \":cbottom\", except use the window showing the             location list for the current window.</p> <p>Normally the quickfix window is at the bottom of the screen.  If there are vertical splits, it's at the bottom of the rightmost column of windows.  To make it always occupy the full width:     :botright cwindow You can move the window around with |window-moving| commands. For example, to move it to the top: CTRL-W K The 'winfixheight' option will be set, which means that the window will mostly keep its height, ignoring 'winheight' and 'equalalways'.  You can change the height manually (e.g., by dragging the status line above it with the mouse).</p> <p>In the quickfix window, each line is one error.  The line number is equal to the error number.  The current entry is highlighted with the QuickFixLine highlighting.  You can change it to your liking, e.g.:     :hi QuickFixLine ctermbg=Yellow guibg=Yellow</p> <p>You can use \":.cc\" to jump to the error under the cursor. Hitting the  key or double-clicking the mouse on a line has the same effect.  The file containing the error is opened in the window above the quickfix window.  If there already is a window for that file, it is used instead.  If the buffer in the used window has changed, and the error is in another file, jumping to the error will fail.  You will first have to make sure the window contains a buffer which can be abandoned. <p>When you select a file from the quickfix window, the following steps are used to find a window to edit the file:</p> <ol> <li>If a window displaying the selected file is present in the current tabpage    (starting with the window before the quickfix window), then that window is    used.</li> <li>If the above step fails and if 'switchbuf' contains \"usetab\" and a window    displaying the selected file is present in any one of the tabpages    (starting with the first tabpage) then that window is used.</li> <li>If the above step fails then a window in the current tabpage displaying a    buffer with 'buftype' not set (starting with the window before the quickfix    window) is used.</li> <li>If the above step fails and if 'switchbuf' contains \"uselast\", then the    previously accessed window is used.</li> <li>If the above step fails then the window before the quickfix window is used.    If there is no previous window, then the window after the quickfix window    is used.</li> <li>If the above step fails, then a new horizontally split window above the    quickfix window is used.<pre><code>            *CTRL-W_&lt;Enter&gt;* *CTRL-W_&lt;CR&gt;*\n</code></pre> <p>You can use CTRL-W  to open a new window and jump to the error there. <p>When the quickfix window has been filled, two autocommand events are triggered.  First the 'filetype' option is set to \"qf\", which triggers the FileType event (also see |qf.vim|).  Then the BufReadPost event is triggered, using \"quickfix\" for the buffer name.  This can be used to perform some action on the listed errors.  Example:     au BufReadPost quickfix  setlocal modifiable         \\ | silent exe 'g/^/s//\\=line(\".\") .. \" \"/'         \\ | setlocal nomodifiable This prepends the line number to each line.  Note the use of \"\\=\" in the substitute string of the \":s\" command, which is used to evaluate an expression. The BufWinEnter event is also triggered, again using \"quickfix\" for the buffer name.</p> <p>Note: When adding to an existing quickfix list the autocommand are not triggered.</p> <p>Note: Making changes in the quickfix window has no effect on the list of errors.  'modifiable' is off to avoid making changes.  If you delete or insert lines anyway, the relation between the text and the error number is messed up. If you really want to do this, you could write the contents of the quickfix window to a file and use \":cfile\" to have it parsed and used as the new error list.</p> <pre><code>                    *location-list-window*\n</code></pre> <p>The location list window displays the entries in a location list.  When you open a location list window, it is created below the current window and displays the location list for the current window.  The location list window is similar to the quickfix window, except that you can have more than one location list window open at a time. When you use a location list command in this window, the displayed location list is used.</p> <p>When you select a file from the location list window, the following steps are used to find a window to edit the file:</p> <ol> <li>If a non-quickfix window associated with the location list is present in    the current tabpage, then that window is used.</li> <li>If the above step fails and if the file is already opened in another window    in the current tabpage, then that window is used.</li> <li>If the above step fails and 'switchbuf' contains \"usetab\" and if the file    is opened in a window in any one of the tabpages, then that window is used.</li> <li>If the above step fails then a window in the current tabpage showing a    buffer with 'buftype' not set is used.</li> <li>If the above step fails, then the file is edited in a new window.</li> </ol> <p>In all of the above cases, if the location list for the selected window is not yet set, then it is set to the location list displayed in the location list window.</p> <pre><code>                        *quickfix-window-ID*\n</code></pre> <p>You can use the |getqflist()| and |getloclist()| functions to obtain the window ID of the quickfix window and location list window respectively (if present).  Examples:     echo getqflist({'winid' : 1}).winid     echo getloclist(2, {'winid' : 1}).winid</p> <pre><code>                        *getqflist-examples*\n</code></pre> <p>The |getqflist()| and |getloclist()| functions can be used to get the various attributes of a quickfix and location list respectively. Some examples for using these functions are below:</p> <pre><code>\" get the title of the current quickfix list\n:echo getqflist({'title' : 0}).title\n\n\" get the identifier of the current quickfix list\n:let qfid = getqflist({'id' : 0}).id\n\n\" get the identifier of the fourth quickfix list in the stack\n:let qfid = getqflist({'nr' : 4, 'id' : 0}).id\n\n\" check whether a quickfix list with a specific identifier exists\n:if getqflist({'id' : qfid}).id == qfid\n\n\" get the index of the current quickfix list in the stack\n:let qfnum = getqflist({'nr' : 0}).nr\n\n\" get the items of a quickfix list specified by an identifier\n:echo getqflist({'id' : qfid, 'items' : 0}).items\n\n\" get the number of entries in a quickfix list specified by an id\n:echo getqflist({'id' : qfid, 'size' : 0}).size\n\n\" get the context of the third quickfix list in the stack\n:echo getqflist({'nr' : 3, 'context' : 0}).context\n\n\" get the number of quickfix lists in the stack\n:echo getqflist({'nr' : '$'}).nr\n\n\" get the number of times the current quickfix list is changed\n:echo getqflist({'changedtick' : 0}).changedtick\n\n\" get the current entry in a quickfix list specified by an identifier\n:echo getqflist({'id' : qfid, 'idx' : 0}).idx\n\n\" get all the quickfix list attributes using an identifier\n:echo getqflist({'id' : qfid, 'all' : 0})\n\n\" parse text from a List of lines and return a quickfix list\n:let myList = [\"a.java:10:L10\", \"b.java:20:L20\"]\n:echo getqflist({'lines' : myList}).items\n\n\" parse text using a custom 'efm' and return a quickfix list\n:echo getqflist({'lines' : ['a.c#10#Line 10'], 'efm':'%f#%l#%m'}).items\n\n\" get the quickfix list window id\n:echo getqflist({'winid' : 0}).winid\n\n\" get the quickfix list window buffer number\n:echo getqflist({'qfbufnr' : 0}).qfbufnr\n\n\" get the context of the current location list\n:echo getloclist(0, {'context' : 0}).context\n\n\" get the location list window id of the third window\n:echo getloclist(3, {'winid' : 0}).winid\n\n\" get the location list window buffer number of the third window\n:echo getloclist(3, {'qfbufnr' : 0}).qfbufnr\n\n\" get the file window id of a location list window (winnr: 4)\n:echo getloclist(4, {'filewinid' : 0}).filewinid\n\n                        *setqflist-examples*\n</code></pre> <p>The |setqflist()| and |setloclist()| functions can be used to set the various attributes of a quickfix and location list respectively. Some examples for using these functions are below:</p> <pre><code>\" create an empty quickfix list with a title and a context\n:let t = 'Search results'\n:let c = {'cmd' : 'grep'}\n:call setqflist([], ' ', {'title' : t, 'context' : c})\n\n\" set the title of the current quickfix list\n:call setqflist([], 'a', {'title' : 'Mytitle'})\n\n\" change the current entry in the list specified by an identifier\n:call setqflist([], 'a', {'id' : qfid, 'idx' : 10})\n\n\" set the context of a quickfix list specified by an identifier\n:call setqflist([], 'a', {'id' : qfid, 'context' : {'val' : 100}})\n\n\" create a new quickfix list from a command output\n:call setqflist([], ' ', {'lines' : systemlist('grep -Hn main *.c')})\n\n\" parse text using a custom efm and add to a particular quickfix list\n:call setqflist([], 'a', {'id' : qfid,\n    \\ 'lines' : [\"a.c#10#L10\", \"b.c#20#L20\"], 'efm':'%f#%l#%m'})\n\n\" add items to the quickfix list specified by an identifier\n:let newItems = [{'filename' : 'a.txt', 'lnum' : 10, 'text' : \"Apple\"},\n        \\ {'filename' : 'b.txt', 'lnum' : 20, 'text' : \"Orange\"}]\n:call setqflist([], 'a', {'id' : qfid, 'items' : newItems})\n\n\" empty a quickfix list specified by an identifier\n:call setqflist([], 'r', {'id' : qfid, 'items' : []})\n\n\" free all the quickfix lists in the stack\n:call setqflist([], 'f')\n\n\" set the title of the fourth quickfix list\n:call setqflist([], 'a', {'nr' : 4, 'title' : 'SomeTitle'})\n\n\" create a new quickfix list at the end of the stack\n:call setqflist([], ' ', {'nr' : '$',\n        \\ 'lines' : systemlist('grep -Hn class *.java')})\n\n\" create a new location list from a command output\n:call setloclist(0, [], ' ', {'lines' : systemlist('grep -Hn main *.c')})\n\n\" replace the location list entries for the third window\n:call setloclist(3, [], 'r', {'items' : newItems})\n</code></pre> <p>============================================================================= 3. Using more than one list of errors           quickfix-error-lists</p> <p>So far has been assumed that there is only one list of errors.  Actually the ten last used lists are remembered.  When starting a new list, the previous ones are automatically kept.  Two commands can be used to access older error lists.  They set one of the existing error lists as the current one.</p> <pre><code>                    *:colder* *:col* *E380*\n</code></pre> <p>:col[der] [count]   Go to older error list.  When [count] is given, do             this [count] times.  When already at the oldest error             list, an error message is given.</p> <pre><code>                    *:lolder* *:lol*\n</code></pre> <p>:lol[der] [count]   Same as <code>:colder</code>, except use the location list for             the current window instead of the quickfix list.</p> <pre><code>                    *:cnewer* *:cnew* *E381*\n</code></pre> <p>:cnew[er] [count]   Go to newer error list.  When [count] is given, do             this [count] times.  When already at the newest error             list, an error message is given.</p> <pre><code>                    *:lnewer* *:lnew*\n</code></pre> <p>:lnew[er] [count]   Same as <code>:cnewer</code>, except use the location list for             the current window instead of the quickfix list.</p> <pre><code>                    *:chistory* *:chi*\n</code></pre> <p>:[count]chi[story]  Show the list of error lists.  The current list is             marked with \"&gt;\".  The output looks like:               error list 1 of 3; 43 errors   :make              &gt; error list 2 of 3; 0 errors    :helpgrep tag                error list 3 of 3; 15 errors   :grep ex_help *.c  </p> <pre><code>        When [count] is given, then the count'th quickfix\n        list is made the current list. Example:  \n            \" Make the 4th quickfix list current\n            :4chistory\n\n                    *:lhistory* *:lhi*\n</code></pre> <p>:[count]lhi[story]  Show the list of location lists, otherwise like             <code>:chistory</code>.</p> <p>When adding a new error list, it becomes the current list.</p> <p>When \":colder\" has been used and \":make\" or \":grep\" is used to add a new error list, one newer list is overwritten.  This is especially useful if you are browsing with \":grep\" |grep|.  If you want to keep the more recent error lists, use \":cnewer 99\" first.</p> <p>To get the number of lists in the quickfix and location list stack, you can use the |getqflist()| and |getloclist()| functions respectively with the list number set to the special value '$'. Examples:     echo getqflist({'nr' : '$'}).nr     echo getloclist(3, {'nr' : '$'}).nr To get the number of the current list in the stack:     echo getqflist({'nr' : 0}).nr</p> <p>============================================================================= 4. Using :make                      :make_makeprg</p> <pre><code>                        *:mak* *:make*\n</code></pre> <p>:mak[e][!] [arguments]  1. All relevant |QuickFixCmdPre| autocommands are                executed.             2. If the 'autowrite' option is on, write any changed                buffers             3. An errorfile name is made from 'makeef'.  If                'makeef' doesn't contain \"##\", and a file with this                name already exists, it is deleted.             4. The program given with the 'makeprg' option is                started (default \"make\") with the optional                [arguments] and the output is saved in the                errorfile (for Unix it is also echoed on the                screen).             5. The errorfile is read using 'errorformat'.             6. All relevant |QuickFixCmdPost| autocommands are                executed.  See example below.             7. If [!] is not given the first error is jumped to.             8. The errorfile is deleted.             9. You can now move through the errors with commands                like |:cnext| and |:cprevious|, see above.             This command does not accept a comment, any \"             characters are considered part of the arguments.             If the encoding of the program output differs from the             'encoding' option, you can use the 'makeencoding'             option to specify the encoding.</p> <pre><code>                        *:lmak* *:lmake*\n</code></pre> <p>:lmak[e][!] [arguments]             Same as \":make\", except the location list for the             current window is used instead of the quickfix list.</p> <p>The \":make\" command executes the command given with the 'makeprg' option. This is done by passing the command to the shell given with the 'shell' option.  This works almost like typing</p> <pre><code>\":!{makeprg} [arguments] {shellpipe} {errorfile}\".\n</code></pre> <p>{makeprg} is the string given with the 'makeprg' option.  Any command can be used, not just \"make\".  Characters '%' and '#' are expanded as usual on a command-line.  You can use \"%&lt;\" to insert the current file name without extension, or \"#&lt;\" to insert the alternate file name without extension, for example:    :set makeprg=make\\ #&lt;.o</p> <p>[arguments] is anything that is typed after \":make\". {shellpipe} is the 'shellpipe' option. {errorfile} is the 'makeef' option, with ## replaced to make it unique.</p> <p>The placeholder \"$\" can be used for the argument list in {makeprg} if the command needs some additional characters after its arguments.  The $ is replaced then by all arguments.  Example:    :set makeprg=latex\\ \\\\nonstopmode\\ \\\\input\\{$} or simpler    :let &amp;mp = 'latex \\nonstopmode \\input{$}' \"$\" can be given multiple times, for example:    :set makeprg=gcc\\ -o\\ $\\ $*</p> <p>The 'shellpipe' option defaults to \"2&gt;&amp;1| tee\" for Win32. This means that the output of the compiler is saved in a file and not shown on the screen directly.  For Unix \"| tee\" is used.  The compiler output is shown on the screen and saved in a file the same time.  Depending on the shell used \"|&amp; tee\" or \"2&gt;&amp;1| tee\" is the default, so stderr output will be included.</p> <p>If 'shellpipe' is empty, the {errorfile} part will be omitted.  This is useful for compilers that write to an errorfile themselves.</p> <p>Using QuickFixCmdPost to fix the encoding  </p> <p>It may be that 'encoding' is set to an encoding that differs from the messages your build program produces.  This example shows how to fix this after Vim has read the error messages:  </p> <pre><code>function QfMakeConv()\n   let qflist = getqflist()\n   for i in qflist\n      let i.text = iconv(i.text, \"cp936\", \"utf-8\")\n   endfor\n   call setqflist(qflist)\nendfunction\n\nau QuickfixCmdPost make call QfMakeConv()\n</code></pre> <p>(Example by Faque Cheng) Another option is using 'makeencoding'.</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":"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> 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>Pre-requisite: multi-modal editing</p> <p> Multi-modal Editing is a recommended pre-requisite</p> <p>Aliases to run Clojure REPL - Practicalli Clojure CLI Config</p> <p> Practicalli Clojure CLI config contains aliases used to start a Clojure REPL and other development tools.  Aliases are used extensively through the Clojure sections of this book.</p> Practicalli Neovim config replaces some key bindings <p>Practicalli Neovim Config 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 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>Paste Evaluation result</p> <p>\" C p  to paste the contents of the <code>C</code> register into the current buffer. </p> <p>The result of every Conjure evaluation is stored in the <code>C</code> register when using Practicalli AstroNvim Config.</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/documentation/","title":"Documentation","text":"<p>K or Space l h shows the documentation for the function under the cursor in a popup window.</p> <p>K a second time to jump the cursor to the popup window to scroll the text if required (or use a mouse wheel)</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>"},{"location":"repl-driven-development/refactor-tools/#function-documentation","title":"Function documentation","text":"<p>K or Space l h show the doc-string for function or any other var 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> <p>, l l code lens refresh</p> <p>, l L code lens run</p>"},{"location":"repl-driven-development/refactor-tools/#navigation","title":"Navigation","text":"<p>g d go to definition of current symbol, e.g. function definition</p> <p>, l G telescope search of all symbols in the project</p> <p>, l R telescope search of all references in the project</p> <p>, l s telescope search of symbols</p> <p>, l s split view of symbols</p>"},{"location":"repl-driven-development/refactor-tools/#diagnostics","title":"Diagnostics","text":"<p>Space l d show popup for current diagnostic indicator</p> <p>Space l D search through all diagnostics reports</p>"},{"location":"repl-driven-development/refactor-tools/#code-actions","title":"Code Actions","text":"<p>Space l r rename current symbol (namespace rename not supported by LSP client)</p> <p>Space l a code actions (popup with available actions)</p> <p>Space l f format buffer</p>"},{"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> <p>Space l I shows format and lint tools supported by null-ls for the current filetype, e.g. clojure</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":"source-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":"source-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":"source-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":"source-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":"source-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":"source-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":"source-control/diff/#nvimdiff","title":"nvimdiff","text":"<p>The Git <code>difftool</code> can specify Neovim as a diff viewer to show Git diff views of all the files that have changes</p> <p>nvimdiff as a command line option</p> <pre><code>git difftool --tool=nvimdiff &lt;optional-filename&gt;\n</code></pre> <p><code>git difftool</code> can be configured to use Neovim </p> <p>Git client config to set <code>nvimdiff</code> as <code>difftool</code></p> ~/.config/git/config<pre><code>[diff]\n  # Neovim diff tool\n  tool = nvimdiff\n</code></pre> <p>Run <code>git difftool</code> in the root of the project to show the diff of each changed file.</p> <pre><code>git difftool &lt;optional-filename&gt;\n</code></pre> <p>: q a to close the current diff view.  The command line prompts to open the next file as a diff view (assuming there are more files to view).</p>"},{"location":"source-control/diff/#diffview","title":"DiffView","text":"<p>DiffView compares working space and staged changes side by side, or a diff for git merge conflicts.</p> AstroNvimPracticalli Neovim Config <p>Space g d or <code>d</code> in neogit status buffer (<code>SPC g s</code>) will open diffview in a new tab</p> <p>[ c to move to previous hunk</p> <p>] c to move to next hunk</p> <p>Space g to return to neovim buffer or q to return to neogit status buffer</p> <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> <ul> <li>Green - added lines</li> <li>Yellow - changed line</li> <li>Red - deleted lines</li> </ul>"},{"location":"source-control/lazygit/","title":"Lazygit version control","text":"Command Line or AstroNvim configuration <p>Lazygit interface not provided by Practicalli Neovim Config Redux</p>"},{"location":"source-control/lazygit/#requirements","title":"Requirements","text":"<p>Install lazygit command line tool</p>"},{"location":"source-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":"source-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":"source-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":"source-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":"source-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":"source-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":"source-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":"source-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":"source-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":"source-control/neogit/#modify-git-commit-history","title":"Modify Git commit history","text":"<p><code>r</code> opens the rebase menu</p>"},{"location":"source-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":"source-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":"source-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":"source-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>"},{"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 -L -O https://github.com/clojure/brew-install/releases/latest/download/linux-install.sh &amp;&amp; \\\nchmod +x linux-install.sh &amp;&amp; \\\n./linux-install.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 calling <code>clojure</code> with the --help option, which shows the options available to the command</p> <pre><code>clojure --help\n</code></pre> <p>Also consider running a repl to ensure the dependency download is working correctly</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>optionally install rlwrap package if using the basic repl terminal UI with the <code>clj</code> wrapper</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>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Neovim for Clojure development","text":"<p>Practicalli Neovim provides install &amp; user guide focused on a simple, powerful and joyful REPL driven workflow for Clojure.</p> <p>Practicalli recommends using AstroNvim community configuration which provides Conjure REPL client and Clojure editing support (parinfer &amp; paredit).</p> <p></p>"},{"location":"#quick-start","title":"Quick Start","text":"<p>Install Clojure, Neovim 0.10.0 and Practicalli AstroNvim user config</p>"},{"location":"#neovim-overview","title":"Neovim overview","text":"<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>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> </p>"},{"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-practicalli","title":"Sponsor Practicalli","text":"<p>All sponsorship funds are used to support the continued development of Practicalli series of books and videos, although most work is done at personal cost and time.</p> <p>Thanks 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 is based on AstroNvim, a thoughtful configuration that supports the latest Neovim stable releases, provides a polished UI and many community extensions.</p> <p>Practicalli AstroNvim User Config provides a complete Clojure config on top of AstroNvim.</p> <p>Install Practicalli AstroNvim Config </p> <p>NOTE: Practicalli Neovim Config Redux was a learning experiment that provided mnemonic key bindings, packer, telescope selector, written in Fennel.  This project has now been archived in favour of AstroNvim</p>"},{"location":"configuration/#multiple-configurations","title":"Multiple Configurations","text":"<p>Many Neovim configurations can be installed in <code>$HOME/.config/</code> using unique directory names, e.g. AstroNvim, lazyvim, Nvchad, practicalli. </p> <p>Set <code>NVIM_APPNAME</code> to a configuration directory name (relative to $HOME/.config/`) to run Neovim with that specific config.</p> <p>Run AstroNvim config in <code>$HOME/.config/astronvim/</code></p> <pre><code>NVIM_APPNAME=astronvim nvim\n</code></pre> <p>The configuration directory name is used to save local <code>share</code>, <code>state</code> and <code>cache</code> files for that specific configuration.</p>"},{"location":"configuration/#configure-shell-alias","title":"Configure shell alias","text":"<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>Add alias to <code>.bashrc</code> for Bash shell or <code>.zshrc</code> for Zsh</p> <p>Define Shell Aliases to run each configuration</p> <pre><code>alias astro=\"NVIM_APPNAME=astronvim nvim\"\nalias lazy=\"NVIM_APPNAME=lazyvim nvim\"\nalias practicalli=\"NVIM_APPNAME=neovim-config nvim\"\n</code></pre>"},{"location":"configuration/#shell-aliases-for-bash-and-zsh","title":"shell-aliases for bash and zsh","text":"<p>Create a <code>.config/shell-aliases</code> file containing all shell aliases when often switching between different shells, avoiding the need to define aliases twice</p> <p>Source the <code>.config/shell-aliases</code> file from within <code>.bashrc</code> or <code>.zshrc</code></p> ZshBash .zshrc<pre><code># Shell Aliases\n[[ ! -f ~/.config/shell-aliases ]] || source ~/.config/shell-aliases\n</code></pre> .bashrc<pre><code># Shell Aliases\nif [ -f ~/.config/shell-aliases ]; then\n    . ~/.config/shell-aliases\nfi\n</code></pre>"},{"location":"configuration/#zsh-terminal-config-selector","title":"Zsh Terminal config selector","text":"<p>Optionalliy define a terminal UI selection to choose a configuration if using zsh.</p> <p>Z Shell nvim-selector script</p> .local/bin/nvim-selector<pre><code>function nvim-selector() {\n  items=(\"astronvim\" \"practicalli\" \"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 User Config is a user configuration that extends AstroNvim and imports packages from the  AstroNvim Community.</p>"},{"location":"configuration/astronvim/#astronvim-install","title":"AstroNvim Install","text":"<p> Practicalli AstroNvim User Config is Clojure development focused configuration, an extension of the AstroNvim template.</p> <p> AstroNvim template repository provide a general configuration for Neovim.  AstroNvim Community provides plugin configs to make it easier to extend the general feature of AstroNvim.</p> Practicalli AstroNvim User ConfigAstroNvim template <p>Clone the  Practicalli AstroNvim User Config which provides Clojure support on top of AstroNvim.</p> <pre><code>git clone http://github.com/practicalli/astronvim-user-config $HOME/.config/astronvim\n</code></pre> <p>Create your own user configuration using the  AstroNvim template repository to create a new GitHub repository.</p> <p>Clone the newly created repository</p> <pre><code>git clone git@github.com/AstroNvim/template $HOME/.config/astronvim\n</code></pre> <p>Use Shell Aliases if using multiple Neovim configurations</p> <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>Lazy package manager will run automatically and download all plugins.  Treesitter languages are automatically installed.  </p> <p>q to close the lazy package manager popup.</p> <p><code>NVIM_APPNAME=astronvim4 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_APPNAME=astronvim4 nvim --headless\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/astrocommunity/","title":"Override Astrocommunity Configuration","text":"<p>Configuration in the AstroNvim Community clojure language pack can be overridden and plugins disabled to meet your needs</p>"},{"location":"configuration/astronvim/astrocommunity/#parinfer","title":"Parinfer","text":"<p>By aligning clojure code correctly, parinfer will automatically correct the position of parenthesis and other delimiters, i.e. <code>()</code>, <code>[]</code>, <code>{}</code></p> <p>Parinfer can be disabled if preferred and the more traditional slurp/barf structural editing be done via nvim-treesitter-sexp</p> <p>Include the Clojure language pack and disable the parinfer plugin by setting the plugin name to equal false</p> <pre><code>  { import = \"astrocommunity.pack.clojure\" },\n  { \"gpanders/nvim-parinfer\", enabled = false },\n</code></pre>"},{"location":"configuration/astronvim/astrocommunity/#conjure","title":"Conjure","text":"<p>Configure the Clojure REPL client via the conjure plugin.</p> <p>NOTE: <code>:help conjure-client-clojure-nrepl</code> for full list of Conjure options for Clojure.</p> <p>Set HUD location to full width along the bottom of the screen. The HUD appears in the top right corner of the screen by default.</p> <pre><code>            [\"conjure#log#hud#enabled\"] = true,  -- enable HUD\n            [\"conjure#log#hud#width\"] = 1,\n            [\"conjure#log#hud#anchor\"] = \"SE\",\n            [\"conjure#log#botright\"] = true,\n</code></pre> <p>Disable the auto repl (babashka) if an nREPL process is not listening, i.e. <code>.nrepl-port</code> file does not exist or does not contain a port number.</p> <pre><code>            -- Disable auto repl (babashka)\n            [\"conjure#client#clojure#nrepl#connection#auto_repl#enabled\"] = false,\n            [\"conjure#client#clojure#nrepl#connection#auto_repl#hidden\"] = true,\n            [\"conjure#client#clojure#nrepl#connection#auto_repl#cmd\"] = nil,\n            [\"conjure#client#clojure#nrepl#eval#auto_require\"] = false,\n</code></pre> <p>Change the test runner used by Conjure. <code>clojure.test</code> runner is used by default</p> <ul> <li><code>\"clojure\"</code> clojure.test (default)</li> <li>`\"clojuresCRipt\" cljs.test</li> <li><code>\"kaocha\"</code> lambdaisland/kaocha</li> </ul> <pre><code>            -- Set Test runner: \"clojure\", \"clojuresCRipt\", \"kaocha\"\n            [\"conjure#client#clojure#nrepl#test#runner\"] = \"kaocha\",\n</code></pre> <p>Working example with additional configuration options to show HUD along bottom, enable auto repl if no nREPL process found and set test runner to use lambdaisland/kaocha.</p> <pre><code>  { import = \"astrocommunity.pack.clojure\" },\n  {\n    \"AstroNvim/astrocore\",\n    opts = {\n      options = {\n        g = {\n          -- Enable HUD and show full lenght along bottom\n          [\"conjure#log#hud#enabled\"] = true, -- show log by default?\n          [\"conjure#log#hud#width\"] = 1,\n          [\"conjure#log#hud#anchor\"] = \"SE\",\n          [\"conjure#log#botright\"] = true,\n\n          -- Disable auto repl (babashka)\n          [\"conjure#client#clojure#nrepl#connection#auto_repl#enabled\"] = false,\n          [\"conjure#client#clojure#nrepl#connection#auto_repl#hidden\"] = true,\n          [\"conjure#client#clojure#nrepl#connection#auto_repl#cmd\"] = nil,\n          [\"conjure#client#clojure#nrepl#eval#auto_require\"] = false,\n\n          -- Set Test runner: \"clojure\", \"clojuresCRipt\", \"kaocha\"\n          [\"conjure#client#clojure#nrepl#test#runner\"] = \"kaocha\",\n        },\n      },\n    },\n  },\n</code></pre>"},{"location":"configuration/astronvim/astrocommunity/#nvim-treesitter-sexp","title":"nvim-treesitter-sexp","text":"<p>Treesitter based structural editing with normal mode key mappings, which can be set to false to disable. Two commands are disabled in the example.</p> <p>Additional which-key keymaps can be included for greater discoverability. Example includes keymaps inspired by Spacemacs Lisp mode, <code>SPC k</code>.</p> <pre><code>  { import = \"astrocommunity.pack.clojure\" },\n  {\n    \"PaterJason/nvim-treesitter-sexp\",\n    dependencies = {\n      \"AstroNvim/astrocore\",\n      opts = {\n        -- configuration &amp; keymaps overrides:\n        -- https://github.com/PaterJason/nvim-treesitter-sexp#configuration\n        -- enabled = false,  -- Set to false to disable individual keymaps\n        -- set_cursor = true,\n        -- keymaps = {\n        -- Default key bindings - set to false to disable\n        --   commands = {\n        --     promote_elem = false,\n        --     promote_form = false,\n        --   },\n        --   motions = {\n        --   },\n        --   textobjects = {\n        --   },\n        -- },\n        options = {\n          g = {},\n        },\n        mappings = {\n          n = {\n            -- Additional Which-key key bindings for nvim-treesitter-sexp\n            [\"&lt;Leader&gt;k\"] = { name = \"Structural Editing\" },\n            [\"&lt;Leader&gt;kE\"] = { \"&lt;Cmd&gt;TSSexp swap_prev_elem&lt;CR&gt;\", desc = \"Swap Previous Element\" },\n            [\"&lt;Leader&gt;ke\"] = { \"&lt;Cmd&gt;TSSexp swap_next_elem&lt;CR&gt;\", desc = \"Swap Previous Element\" },\n            [\"&lt;Leader&gt;kF\"] = { \"&lt;Cmd&gt;TSSexp swap_prev_form&lt;CR&gt;\", desc = \"Swap Previous Form\" },\n            [\"&lt;Leader&gt;kf\"] = { \"&lt;Cmd&gt;TSSexp swap_next_form&lt;CR&gt;\", desc = \"Swap Previous Form\" },\n            [\"&lt;Leader&gt;kk\"] = { \"&lt;Cmd&gt;TSSexp promote_elem&lt;CR&gt;\", desc = \"Promote Element\" },\n            [\"&lt;Leader&gt;kr\"] = { \"&lt;Cmd&gt;TSSexp promote_form&lt;CR&gt;\", desc = \"Promote Form\" },\n            [\"&lt;Leader&gt;k@\"] = { \"&lt;Cmd&gt;TSSexp splice&lt;CR&gt;\", desc = \"Splice\" },\n            [\"&lt;Leader&gt;kS\"] = { \"&lt;Cmd&gt;TSSexp slurp_left&lt;CR&gt;\", desc = \"Slurp Left\" },\n            [\"&lt;Leader&gt;ks\"] = { \"&lt;Cmd&gt;TSSexp slurp_right&lt;CR&gt;\", desc = \"Slurp Right\" },\n            [\"&lt;Leader&gt;kB\"] = { \"&lt;Cmd&gt;TSSexp barf_left&lt;CR&gt;\", desc = \"Barf Left\" },\n            [\"&lt;Leader&gt;kb\"] = { \"&lt;Cmd&gt;TSSexp barf_right&lt;CR&gt;\", desc = \"Barf Right\" },\n            [\"&lt;Leader&gt;kI\"] = { \"&lt;Cmd&gt;TSSexp barf_right&lt;CR&gt;\", desc = \"Insert Head\" },\n            [\"&lt;Leader&gt;ki\"] = { \"&lt;Cmd&gt;TSSexp barf_right&lt;CR&gt;\", desc = \"Insert Tail\" },\n          },\n          t = {\n            -- terminal? mode key bindings\n          },\n          v = {\n            -- visual mode key bindings\n          },\n        },\n      },\n    },\n  },\n</code></pre>"},{"location":"configuration/astronvim/config-design/","title":"\ud83d\udce6 Practicalli AstroNvim Config Design","text":"<p>A guide to the design of AstroNvim Config created by Practicalli to support a comprehensive development workflow.</p> AstroCommunity Plugin Configurations used where available <p>Plugin configurations from AstroCommunity are used to minimise the code size and maintenance of the Practicalli configuration</p>"},{"location":"configuration/astronvim/config-design/#files-overview","title":"Files overview","text":"<p>The file structure as taken from the AstroNvim template and new files were created to minimise changes, making it simpler to add updates from the original template repository.</p> <p>Key: AstroNvim template file changes</p> <ul> <li> unchanged </li> <li> changed </li> <li> added</li> <li> config not activated (comment <code>if</code> statement to activate)</li> </ul> <p> <code>init.lua</code> ensures the Lazy package manager is available when Neovim starts up. This file is unchanged from the AstroNvim template.</p> <p> <code>lua/lazy_setup.lua</code> configures the Lazy package manager.  <code>zipPlugin</code> enabled to support Clojure docs and source navigation inside libraries. </p> <p> <code>lua/community.lua</code> imports plugin configurations from AstroCommunity, including the Clojure pack.</p> <p> <code>lua/polish.lua</code> general lua configuration loaded after AstroNvim configs.</p> <p><code>lua/plugins/</code> for additional plugins organised logically. All <code>.lua</code> files are automatically loaded from this directory when starting Neovim.</p> <ul> <li> <code>astrocore.lua</code>, <code>astrolsp.lua</code>, <code>astroui.lua</code> examples of overriding AstroNvim defaults</li> <li> <code>clojure.lua</code> alternative approach to configure clojure, extending the AstroNvim Clojure pack</li> <li> <code>github.lua</code> issue &amp; PR management with octo.nvim (requires GitHub CLI)</li> <li> <code>mason.lua</code> ensure tools are installed by default (LSP servers, format &amp; lint tools, DAP debug tools)</li> <li> <code>neo-tree.lua</code> visual file navigator - example config</li> <li> <code>none-ls.lua</code> example config for format &amp; lint tools</li> <li> <code>platuml.lua</code> UML diagrams defined with code - requires plantuml.com install</li> <li> <code>practicalli.lua</code> theme, dashboard &amp; key binding preferences enjoyed by Practicalli</li> <li> <code>snippets.lua</code> load JSON style snippet definitions</li> <li><code>telescope.lua</code> ensure Treesitter languages are installed (AstroCommunity language packs also ensure parsers installed)</li> <li> <code>treesittter.lua</code> ensure Treesitter languages are installed (AstroCommunity language packs also ensure parsers installed)</li> <li> <code>user.lua</code> example user configuration, added via <code>lua/plugins/practicalli.lua</code></li> </ul>"},{"location":"configuration/astronvim/config-design/#clojure-support","title":"Clojure support","text":"<p>The  AstroCommunity provides a Clojure language pack that ensures <code>clojure</code> Treesitter parser and <code>clojure-lsp</code> support and installed automatically.</p> <p>The pack contains 4 Neovim plugins:</p> <ul> <li>conjure REPL client to evaluate code</li> <li>nvim-parinfer code indenting structural editing</li> <li>nvim-treesitter-sexp paredit (slurp/barf etc) structural editing </li> <li>ts-comment.nvim Clojure comment patterns</li> </ul> <p>!!! INFO: \"Practicalli AstroNvim Config includes Clojure pack\"</p> AstroCommunity Clojure 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> Exclude a plugin from the pack <p>The Clojure pack includes parinfer and paredit tools for structural editing, which both work together without issue.  Should one or both of these plugins not be reqiured, set enabled to false <pre><code>return {\n  \"AstroNvim/astrocommunity\",\n  { import = \"astrocommunity.pack.clojure\" },\n  { \"gpanders/nvim-parinfer\", enabled = false },\n</code></pre></p> <p>Override Conjure configration</p> <p>Add the AstroCommunity Clojure pack and additional configuration to create a tailored experience </p> <p><code>:help conjure</code> for general Conjure options.</p> <p><code>:help conjure-client-clojure-nrepl</code> for Clojure specific options.</p> <pre><code>return {\n  \"AstroNvim/astrocommunity\",\n  { import = \"astrocommunity.pack.clojure\" },\n  {\n    \"AstroNvim/astrocore\",\n    opts = {\n      options = {\n        g = {\n          -- show HUD REPL log at startup\n          [\"conjure#log#hud#enabled\"] = false,\n\n          -- Hightlight evaluated forms\n          -- [\"conjure#highlight#enabled\"] = true,\n\n          -- Trim log after number of lines. Default: `10000`\n          -- [\"conjure#log#trim#at\"] = 200,\n          -- Trim log to number of lines. Default: `7000`\n          -- [\"conjure#log#trim#to\"] = 100,\n\n          -- auto repl (babashka)\n          [\"conjure#client#clojure#nrepl#connection#auto_repl#enabled\"] = false,\n          [\"conjure#client#clojure#nrepl#connection#auto_repl#hidden\"] = true,\n          [\"conjure#client#clojure#nrepl#connection#auto_repl#cmd\"] = nil,\n          [\"conjure#client#clojure#nrepl#eval#auto_require\"] = false,\n\n          -- Test runner: \"clojure\", \"clojuresCRipt\", \"kaocha\"\n          [\"conjure#client#clojure#nrepl#test#runner\"] = \"kaocha\",\n        },\n      },\n    },\n  },\n}\n</code></pre> Config comment for parinfer <p>The parinfer comment configuration may not be required when using ts-comment.nvim to set the Clojure comment pattern. <pre><code>{\n  \"gpanders/nvim-parinfer\",\n  filetype = { \"clojure\" },\n  config = function()\n    vim.g.parinfer_force_balance = true\n    vim.g.parinfer_comment_chars = \";;\"\n  end,\n},\n</code></pre></p> <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</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>Manual install of Treesitter Clojure Parser</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> <p>LuaSnip with json format snippets in <code>snippets/</code> directory</p> .config/astronvim-config/plugins/core.lua<pre><code>return {\n  --LuaSnip with json format snippets in `snippets/` directory\n  {\n    \"L3MON4D3/LuaSnip\",\n    config = function(plugin, opts)\n      require \"astronvim.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 = { \"./snippets\" } } -- include JSON style snippets\n      local luasnip = require \"luasnip\"\n      luasnip.filetype_extend(\"javascript\", { \"javascriptreact\" })\n    end,\n  },\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>  {\n    -- AstroUI provides the basis for configuring the AstroNvim User Interface\n    -- Configuration documentation can be found with `:h astroui`\n    \"AstroNvim/astroui\",\n    ---@type AstroUIOpts\n    opts = {\n      colorscheme = \"everforest\",\n    },\n  },\n</code></pre> <p> AstroCommunity themes</p>"},{"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 Config Redux has been archived</p> <p>Practicalli Neovim uses the AstroNvim config.</p> <p></p> <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> Kitty Terminal</li> <li>Clojure tooling and a Java SDK (Java Virtual Machine)</li> <li>Neovim 0.10.x</li> <li>Practicalli AstroNvim User Config rich community configuration which is highly configurable</li> <li>NerdFonts icon support in themes and status line</li> <li>Optional: Neovide GUI for Neovim</li> </ul> <p>Neovim 0.10.0 latest stable release</p> <p>Content and configuration in this book has been tested against Neovim 0.10.0 but not against Neovim nightly builds.</p> <p>Already installed?</p> <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/neovide/","title":"Neovide GUI","text":"<p>Neovide provides a GUI for Neovim and supports the use of AstroNvim community configuration.</p> <p> Neovide features</p>"},{"location":"install/neovide/#install-neovide","title":"Install Neovide","text":"<p> Download from Neovide.dev website</p> DebianMacOSX <p>Download neovide.AppImage</p> <p>Move the <code>neovide.AppImage</code> to the execution path, e.g. <code>$HOME/.local/bin</code></p> <p>Create the <code>$HOME/.local/bin/neovide</code> symbolic link pointing to the neovide.AppImage</p> <pre><code>ln -s $HOME/.local/bin/neovide.AppImage $HOME/.local/bin/neovide\n</code></pre> <p>Download the MacOSX dmg.zip file</p> <p>Extract the .zip file </p> <p>Run the extracted dmg file and use the install wizard to copy Neovide to the Applications directory.</p> <p>Create symbolic link from Neovide install to <code>~/.local/bin</code> </p> <pre><code>ln -s /Applications/neovide.app/Contents/MacOS/neovide ~/.local/bin/neovide\n</code></pre> <p>Add alias to use neovide with astronvim configuration to <code>.bashrc</code> , <code>.zshrc</code> or shared <code>shell-aliases</code> file</p> <pre><code>alias neovide=\"NVIM_APPNAME=astronvim neovide\"\n</code></pre>"},{"location":"install/neovide/#neovide-with-nvim_appname","title":"Neovide with NVIM_APPNAME","text":"<p><code>NVIM_APPNAME</code> sets the configuration used when starting Neovim.</p> <p>Use a shell alias to run Neovide with a specific configuration</p> <pre><code># Neovide alias with AstroNvim configuration\nalias neovide=\"NVIM_APPNAME=astronvim neovide\"\n</code></pre>"},{"location":"install/neovide/#set-neovide-font","title":"Set Neovide Font","text":"<p>The <code>guifont</code> Neovim option is used to set a font family and size specifically for a GUI appliction, i.e. Neovide.  It is not used by Neovim itself.</p> <p>Neovide font family and size</p> <pre><code>guifont = \"Fira Code:h16\"\n</code></pre> <p>AstroNvim Neovide font family and size</p> <p> Practicalli AstroNvim Config includes the <code>guifont</code> option in the <code>options.lua</code> file.</p> options.lua<pre><code>return {\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 = true,           -- sets vim.opt.wrap\n    -- showtabline = 0,    -- sets vim.opt.showtabline - zero hides tabs\n    timeoutlen = 420,\n    -- neovide font family &amp; size\n    guifont = \"Fira Code:h16\",\n  },\n}\n</code></pre> <p></p>"},{"location":"install/neovim/","title":"Install Neovim","text":"<p>The  Neovim release page includes install steps for specific operating system.</p> <p>Neovim 0.9 is the minimum version for this configuration and Neovim 0.9.4 is currently being used by Practicalli.</p> <p>Follow the install Neovim guide for the specific operating system.</p> <p> Neovim releases</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>Install the following tools to support Neovim and AstroNvim</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> x11 clipboard as a provider for Neovim copy/paste (Linux only)</li> <li><code>luarocks</code> for LSP servers (AstroNvim)</li> </ul> <p>Treesitter requires a C compiler</p> <p>nvim-treesitter requires a C compiler , e.g. <code>gcc</code> for Linux or <code>clang</code> for android/termix</p> <p>The C compiler is used to compile langauge support for treesiter.</p> <p>AstroNvim requires node.js</p> <p>AstroNvim uses Mason to install LSP servers, format and lint tools. Many of the LSP servers require node.</p> <p>Node.js install - Practicalli Engineering Playbook </p> Debian PackagesMacOSX Homebrew <pre><code>sudo apt install fd-find 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</p> <pre><code>sudo apt install wl-clipboard\n</code></pre> <p>MacOSX requires the libintl and gettext tools as well as the other supporting tools.</p> <pre><code>brew install libintl gettext ripgrep fd luarocks\n</code></pre>"},{"location":"install/neovim/#install-neovim_1","title":"Install Neovim","text":"<p>Use the GitHub releases for the latest version of Neovim, or use a Package manager for the operating system if the version of Neovim is 0.9.x</p> Linux AppImageMacOSX HomebrewMacOSX GitHub ReleaseDebian PackageBuild from Source <p>Download the Linux 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 $HOME/.local/bin/nvim.appimage\n</code></pre> <p>Create a symbolic link called <code>nvim</code> to the nvim.appimage file.</p> <pre><code>ln -s $HOME/.local/bin/nvim.appimage $HOME/.local/bin/nvim\n</code></pre> <p><code>nvim</code> command can now be run in a terminal from any directory.</p> <p>Install from Homebrew or via the Neovim Release page</p> <p>Homebrew <pre><code>brew install neovim\n</code></pre></p> <p>Neovim Release</p> <p>Download <code>nvim-macos.tar.gz</code> From the Neovim GitHub release page</p> <p>Avoid \"unknown developer\" warning from MacOSX</p> <pre><code>xattr -c ./nvim-macos.tar.gz\n</code></pre> <p>Make a local apps directory for neovim (and other things like node.js, etc.)</p> <pre><code>mkdir -P ~/.local/apps\n</code></pre> <p>Extract the neovim archive</p> <pre><code>tar zvxf nvim-macos.tar.gz -C ~/.local/apps/\n</code></pre> <p>Create the <code>~/.local/bin/nvim</code> symbolic link to include Neovim on the OS execution path </p> <p><code>echo $PATH</code> to check <code>.local/bin</code> is included in the execution the path by the Operating System command line shell</p> <pre><code>ln -s ~/.local/apps/nvim-macos/bin/nvim ~/.local/bin/nvim\n</code></pre> <p>Run\u00a0<code>nvim</code>  (or setup a Neovim configuration first, e.g. AstroNvim)</p> <p>From the Neovim GitHub release page:</p> <ol> <li>Install\u00a0<code>libintl</code>and\u00a0<code>gettext</code>\u00a0(e.g. via\u00a0<code>brew install libintl gettext</code>)</li> <li>Download\u00a0nvim-macos.tar.gz</li> <li>Run\u00a0<code>xattr -c ./nvim-macos.tar.gz</code>\u00a0(to avoid \"unknown developer\" warning)</li> <li>Make local apps directory for neovim (and other things like node.js, etc.)</li> </ol> <pre><code>mkdir -P ~/.local/apps\n</code></pre> <ol> <li>Extract the neovim download</li> </ol> <pre><code>tar zvxf nvim-macos.tar.gz -C ~/.local/apps/\n</code></pre> <ol> <li>Create nvim symbolic link in <code>~/.local/bin</code> to include Neovim on the OS execution path (check <code>.local/bin</code> is added to the execution the path by the Operating System command line shell)</li> </ol> <pre><code>ln -s ~/.local/apps/nvim-macos/bin/nvim ~/.local/bin/nvim\n</code></pre> <p>Linux version only packaged as AppImage from Neovim 0.9 onward</p> <p>A <code>.deb</code> file can be created after building Neovim from source.</p> <p> Neovim build guide</p> <p> Neovim Build Prerequisites for each operating system</p> 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> <pre><code>git clone --origin neovim https://github.com/neovim/neovim.git\n</code></pre> <p>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\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":"install/tools-fonts/","title":"Recommended Tools and Fonts","text":"<p>Neovim is a terminal based application so use of a quality terminal is recommended, e.g. Kitty Terminal (or iTerm2 if only on MacOSX)</p> <p>External Command line tools support search and other system information based features presented in AstroNvim.</p> <p>Nodejs supports Language Server protocol servers, format and lint tools installed by Mason.</p>"},{"location":"install/tools-fonts/#kitty-terminal-with-nerd-fonts","title":"\"Kitty Terminal with Nerd Fonts\"","text":"<p>Neovim runs in a terminal, so using Kitty (or iTerm2 - MacOSX only) are good options.  Nerd fonts provides additional symbols on top of the terminal font, providing a richer experience.</p> <p> Kitty Terminal - Practicalli Engineering Playbook provides examples of using Nerd Fonts or Nerd Font symbols with the Kitty terminal.</p> <p>Nerd Fonts </p>"},{"location":"install/tools-fonts/#command-line-tools","title":"Command line tools","text":"<ul> <li>ripgrep text search tool</li> <li>fzf fuzzy finder </li> <li>gdu </li> <li>btm from  GitHub repository releases</li> </ul> Debian packagesHomebrew <p>Install fzf, gdu and node.js via debian package manager <pre><code>apt install fzf gdu\n</code></pre></p> <p>Install fzf, gdu and node.js via Homebrew package manager <pre><code>brew install fzf gdu\n</code></pre></p> <p>Install btm from its  GitHub repository release page</p>"},{"location":"install/tools-fonts/#nodejs-for-lsp-format-lint-tools","title":"nodejs for LSP, format &amp; lint tools","text":"<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>"},{"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>Pull Request Commits must be cryptographically signed</p> <p>All commits contributed to Practicalli must be signed via a legitimate SSH or GPG key to avoid the risk of commit spoofing.</p> <p>Configure commit signing with SSH key - Practicalli Engineering</p> <p>All pull requests must include an entry in CHANGELOG.md or will not be merged.  A changelog entry allows the community to follow the changes to the book.</p> <p>Each pull request will have a number of CI workflows run against the contribution, checking the format of the content and if a changelog entry has been provided.</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 be closed without merging as these take considerable time to review.</p> <p>Issues such as grammar improvements are typically a sign of a rushed section that requires a rewrite, so a pull request to fix a typeographic error will probably not be merged.  Raise an issue, or post a thread in the  Clojurians Slack #practicall channel</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>Neovim News for new developments</p> <p>Keep up to date with new features within Neovim</p> <p><pre><code>:help news.txt\n</code></pre> Use the version name to view specific features of a release <pre><code>:help news-0.9.5.txt\n</code></pre></p>"},{"location":"introduction/features/#neovim-features-for-development","title":"Neovim features for development","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> Configure hidden files <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 / 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>Space W was added to Practicalli Astro Config as a key binding for <code>:write path/to/filename</code> which writes the current buffer to a new file, prompting for the file name.</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/#directories","title":"Directories","text":"<p>a in Neotree to create a file or by adding a ++forward-slash++ at the end of the name a directory is created.</p> <p>Use the <code>mkdir</code> shell command to create a new directory, which is created relative to the current path, which can be checked with <code>:lcd</code></p> <p><code>:!mkdir full/path/to/new/directory</code></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> <pre><code>:!mkdir -p %:h\n</code></pre> <p><code>mkdir -p</code> - the UNIX command to create a folder, the <code>-p</code> option creating any parts of the path required to make the full path</p> <p><code>%</code> - name of the current file </p> <p><code>:h</code> - for the current directory (the \u201chead\u201d of the path). </p> <p><code>!</code> - the NeoVim terminal shell command</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>Multi-modal editing has several states optomised for interacting with text</p> <ul> <li>normal - manipulating and navigating existing text (default state)</li> <li>insert - writing new text</li> <li>visual - selecting blocks of text</li> </ul> <p>Normal mode to insert mode:</p> <ul> <li>i insert before the cursor</li> <li>a append after the curor</li> <li>o insert on new line after current line</li> <li>i insert a new line previous to current line</li> </ul> <p>v to enter visual select, using navigation and/or motions to select a range.</p> <p>Esc to leave insert or visual mode and return to normal mode.</p>"},{"location":"neovim-basics/multi-modal-editing/#command-language","title":"Command language","text":"<p>Learn to speak modal editing commands as sentences to effectively learn Multi-modal editing</p> <p>Verbs start the sentence and are the action to perform</p> <ul> <li>c change</li> <li>d delete</li> <li>f find character</li> <li>g go</li> <li>s substitute</li> <li>v visual select</li> <li>y yank (copy)</li> </ul> <p>Modifiers (motions) follow verbs and define where the cursor moves to.</p> <ul> <li>' a mark location</li> <li>{ } beginning/end of paragraph</li> <li>a around</li> <li>f find (includes character)</li> <li>i inside</li> <li>S surround (nvim-surround) t till (up until)</li> </ul> <p>Text objects provide scope for verbs and modifiers</p> <ul> <li>b block/parentheses</li> <li>p paragraph</li> <li>s sentence  </li> <li>t tag, e.g. html/xml tag</li> <li>w word</li> <li>W word delimited by only space</li> </ul> Examples of speaking Evil <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 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>SPC v s \"</code> visually select current work and surround with <code>\"\"</code> <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>) <p>Evil Reference and Tips</p> <p>Evil quick reference guide Evil tips for developers Speaking Vim</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> <p>Practicalli Spacemacs - Evil reference</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/navigation/","title":"Navigation","text":"<p>Move the cursor one space at a time </p> <ul> <li>h move left</li> <li>j move down</li> <li>k move up</li> <li>l move right</li> </ul>"},{"location":"neovim-basics/navigation/#jump-along-line","title":"Jump along line","text":"<p>Move to specific points within a line</p> <ul> <li>w jump to start of next word</li> <li>b jump to start of word</li> <li>e jump to end of next word</li> <li>$ jumps to end of line</li> <li>0 jumps to start of line</li> <li>^ jumps to first character of line</li> </ul> <p>Uppercase w b e consider word delimited by blank characters</p> <p>Jump joined-word using W B E </p> <p>Use w b e movement with a number to move the cursor larger distances</p> jump 3 words forward<pre><code>3w\n</code></pre> <p>f jumps forward in the current line to the given character</p> jump to next q character<pre><code>fq\n</code></pre> <p>F jumps backward in the current line to the given character</p> jump to previous [ character<pre><code>F[\n</code></pre> <p>t jumps forward in the current line to before the given character</p> jump before q character<pre><code>tq\n</code></pre> <p>T jumps backward in the current line to after the given character</p> jump after [ character<pre><code>T[\n</code></pre>"},{"location":"neovim-basics/navigation/#jump-around-buffer","title":"Jump around buffer","text":"<ul> <li>H jump to top of window</li> <li>M jump to middle of window</li> <li>L jump to bottom of window</li> <li>{ jump to previous paragraph</li> <li>} jump to next paragraph</li> <li>gg jump to first character of line</li> <li>G jump to first character of line</li> </ul> <p>Use cursor movement with a number to move the cursor larger distances</p> jump down 12 lines<pre><code>12j\n</code></pre> Relative line numbers for line navigation <p>Enable relative line numbers to show how far away from the current line each other line is.</p> <pre><code>set relativenumber\nset number\n</code></pre> <p>Practicalli AstroNvim-Config enables relative line numbers</p> <p>Jump to a specific line using the number as a command</p> jump to line number<pre><code>:127\n</code></pre>"},{"location":"neovim-basics/navigation/#navigate-position-history","title":"Navigate position history","text":"<p>++ctrl+\"o\" jumps to a previous postion in the cursor history</p> <p>++ctrl+\"i\" jumps to a previous postion in the cursor history</p>"},{"location":"neovim-basics/navigation/#file-marks","title":"File marks","text":"<p>Navigate within the current file or globally using file marks.</p> <p>m followed by a lower case character creates a mark within the current file.</p> <p>m followed by an upper case character creates a global mark.</p> <p>` (backtick) followed by a character jumps to the mark created</p> <p>Space f ' displays marks in telescope popup</p> <p>File marks within file</p> <p>m f creates a mark lablled <code>f</code></p> <p>` f jumps to the mark labelled <code>f</code></p> Global mark to jump between source and test code <p>m S with the cursor in the source code file.</p> <p>m T with the cursor in the test code file.</p> <p>` S to jump to the source code</p> <p>` T to jump to the source code</p>"},{"location":"neovim-basics/navigation/#jumplist","title":"Jumplist","text":"<p><code>:jumps</code> shows the Neovim jumplist containing all points from any buffer recently jumped to using neovim commands</p> <ul> <li>Ctrl o jump back </li> <li>Ctrl i jump forward </li> <li>ctrl and navigation key (hjkl) to move to changelist window</li> <li>q closes the jumplist buffer</li> </ul>"},{"location":"neovim-basics/navigation/#changes","title":"Changes","text":"<p><code>:changes</code> shows the Neovim changelist containing all points in the current buffer which have changed</p> <ul> <li>g ; jump back (previous edit)</li> <li>g . jump forward</li> <li>ctrl and navigation key (hjkl) to move to changelist window</li> <li>q closes the changelist buffer</li> </ul>"},{"location":"neovim-basics/navigation/#navigation-menus","title":"Navigation menus","text":"<ul> <li>[ ( &amp;  ] ) previous &amp; next paren</li> <li>[ brace-left &amp;  ] brace-right previous and next square brackets</li> <li>[ g &amp;  ] g previous and next Git hunks</li> <li>[ s &amp;  ] s previous and next misspelled wor</li> <li>d</li> </ul>"},{"location":"neovim-basics/navigation/#search-in-buffer","title":"Search in buffer","text":"<p>/ searches buffer for the following pattern</p> <ul> <li>n jumps to next match</li> <li>N jumps to previous match</li> </ul> <p>AstroNvim user config enables <code>incsearch</code> incremental search and <code>hlsearch</code> to highlight every search match</p>"},{"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/registers/","title":"Neovim Registers","text":"<p>Neovim use registers to store and access text using Neovim commands.</p> <p>\" to access a register by name.</p> <p>The name of a register is a number, alphabetical or special character.</p> <p><code>SPC f r</code> lists the values of registers in a telescope popup</p> Yank and paste commit message <p>Select the text of the commit message</p> <p>\" m y yanks the selected text into register <code>m</code></p> <p>Complete the Git commit.  When creating a new commit, paste the message from the register</p> <p>\" m p pastes the register text into the commit message buffer</p> Paste last evaluation result from Conjure <p>When Conjure evaluates code the result is stored in the <code>C</code> register. </p> <p>\" C p pastes the register text into the commit message buffer</p>"},{"location":"neovim-basics/registers/#registers","title":"Registers","text":"<p>Neovim help - registers</p> <pre><code>:help registers\n</code></pre> <p>\" the unnamed register, used by Neovim normal commands, e.g. <code>c</code> <code>d</code> <code>p</code> <code>s</code> <code>x</code> <code>y</code>, etc.</p> <p>0 to 9 numbered registers containing yank and delete history</p> <p>- small delete register for text smaller than a line</p> <p>a to z named registers manually selected, A to Z to append to the text already in the register</p> <p>: . and % read-only registers use with put commands (last inserted, current file name, recent command)</p> <p># alternate buffer file name</p> <p>= expression register for the result of runing a Neovim command expression</p> <p>+ and * selection registers for GUI</p> <p>_ black hole register does not store text, use when normal commands shouldnt update other registers</p> <p>/ last search pattern register used</p>"},{"location":"neovim-basics/registers/#find-registers","title":"Find Registers","text":"<p><code>SPC f r</code> opens the list of registers in a telescope popup.</p> <p> </p> <p>Registers in insert mode</p> <p><code>C-r</code> in insert mode pastes the content of the given register, e.g. <code>C-r a</code> to paste the content of <code>\"a</code></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  multiple cursors in more detail for in-place editing (visual-multi plugin) </li> <li><code>:%substitue</code> <code>:substitue</code> neovim command for search and replace</li> </ul> <p>Search and replace across a project:</p> <ul> <li>Space s 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> Normal mode 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":"AstroNvimNeovim commands <p>Telescope and :cdo</p> <p>Space f w to search for a word</p> <p>Ctrl q opens the quickfix list</p> <p>Use <code>:cdo</code> command to search and replace in the quickfix list</p> <pre><code>:cdo %s/current-pattern/new-pattern/g\n</code></pre> <p>Including the <code>c</code> option to confirm each replacement (using a noice popup when using Practicalli AstroNvim-config)</p> <p>Spectre</p> <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>Evaluating :cdo command as a project wide search replace</p> <p>:cdo command could be used to search and replace within the results of a tool that finds matching patterns across a project</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/spectre/","title":"Spectre","text":"<p>Space s s to toggle Spectre (open/close) to search and replace tool.</p> <p><code>?</code> for the Spectre key mappings</p> <p></p>"},{"location":"neovim-basics/search-replace/spectre/#search-replace","title":"Search &amp; Replace","text":"<p>i underneath Search and enter a search pattern, Esc to see resuts in a popup below.</p> <p>i underneath Replace and enter a replace pattern, Esc to see in-line diff results</p> <p>v toggles Spectre results view between diff to search to replace view</p> <p> </p> <p>d d to toggle an occurance </p> <p>R replaces all occurances (after selecting the occurances to change)</p> <p>A DONE checkbox is show at then end of each selection which has been reaplaced</p> <p>To replace single occurance, toggle all occurances that should not be changes and press R</p> <p> </p> <p>Spectre does not undo changes</p> <p>Use Git or Neovim undo to rollback changes made by Spectre.</p> <p> Spectre is available via the AstroNvim Community project pack and included in the Practicalli astronvim-config    </p> <p> ripgrep and  sed are required.</p> <p> Spectre project </p>"},{"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/modal-editing/","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/modal-editing/#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/modal-editing/#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/modal-editing/#text-wrangling","title":"Text wrangling","text":"<ul> <li>iedit</li> <li>text case</li> </ul>"},{"location":"reference/modal-editing/#clojure-editing","title":"Clojure Editing","text":"<p>traversing expressions  structural editing </p>"},{"location":"reference/modal-editing/case/","title":"Modifying text case","text":"<p>Convert Characters and regioins to upper or lower case text.</p>"},{"location":"reference/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/key-binding-reference/","title":"Evil Keybinding Reference","text":"<p>An alphabetically ordered reference of Vim-style key bindings.</p>"},{"location":"reference/modal-editing/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/modal-editing/motions/","title":"Motions","text":"<p>Todo</p> <p>Moving the cursor around by context rather than individual characters</p>"},{"location":"reference/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/narrowing/#documentation","title":"Documentation","text":"<p><code>:help NarrowRegion</code> to view the documetation on the NrrwRgn plug use</p>"},{"location":"reference/modal-editing/narrowing/#attention","title":"Attention","text":"<p><code>:NRM</code> is described as experimental by the project readme.</p>"},{"location":"reference/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/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/modal-editing/visual-select/#line-and-block","title":"Line and block","text":"<p>V enters visual line select mode</p> <p>j and k alter the selection by line</p> <p>Ctrl+v enters visual region select mode</p> <p>Switch between visual modes</p> <p>Once in visual mode: </p> <p>V switches to visual line mode Ctrl+v switches to visual line mode</p>"},{"location":"reference/modal-editing/z-menu/","title":"Evil Z menu","text":"<p><code>z</code> in normal mode opens a menu of convenient utilities</p>"},{"location":"reference/modal-editing/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/modal-editing/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/modal-editing/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":"reference/neovim/","title":"Neovim Reference","text":"<ul> <li>Language Providers</li> <li>Key mappings</li> </ul>"},{"location":"reference/neovim/changelist/","title":"Changelist","text":"<p>Initial draft - feedback welcome</p> <pre><code>:help :changelist\n</code></pre> <p>View changelist</p> <pre><code>:changes\n</code></pre> <ul> <li>ctrl and navigation key (hjkl) to move to changelist window</li> <li>q closes the changelist buffer</li> </ul>"},{"location":"reference/neovim/jumplist/","title":"Jumplist","text":"<p>Initial draft - feedback welcome</p> <pre><code>:help :jumplist\n</code></pre> <p>View jumplist</p> <pre><code>:jumps\n</code></pre> <ul> <li>ctrl and navigation key (hjkl) to move to jumplist window</li> <li>q closes the jumplist buffer</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/quickfix/","title":"Quickfix","text":"<p>Initial draft - feedback welcome</p>"},{"location":"reference/neovim/quickfix/#quickfix-mode","title":"quickfix mode","text":"Open quickfix in window<pre><code>:ccopen\n</code></pre> <p>Use j k to navigate the list or <code>:cc</code> and a number to jump to a result</p> jump to the 7th result<pre><code>:cc 7\n</code></pre> <ul> <li>ctrl and navigation key (hjkl) to move to quickfix window</li> <li>q closes the quickfix buffer</li> </ul>"},{"location":"reference/neovim/quickfix/#tools","title":"Tools","text":"<ul> <li>qf.nvim - Quickfix and location list management for Neovim</li> <li>nvim-bqf enhanced quickfix window</li> </ul> <p>Quickfix is a mode to show results of another command</p> <ul> <li>a make compile task</li> <li>the results of a search</li> <li>lsp analysis errors</li> </ul> <p>Quickfix buffer can be used to jump through the errors one by one.  Each error can be viewe and fix it in turn. </p> <p>quickfix is used to find a list of positions in files.  </p> <ul> <li>:vimgrep| finds pattern matches.  </li> </ul> <p>The 'errorformat' option should be set to match the error messages from your compiler (see |errorformat| below).</p> <pre><code>                        *quickfix-ID*\n</code></pre> <p>Each quickfix list has a unique identifier called the quickfix ID and this number will not change within a Vim session. The |getqflist()| function can be used to get the identifier assigned to a list. There is also a quickfix list number which may change whenever more than ten lists are added to a quickfix stack.</p> <pre><code>                    *location-list* *E776*\n</code></pre> <p>A location list is a window-local quickfix list. You get one after commands like <code>:lvimgrep</code>, <code>:lgrep</code>, <code>:lhelpgrep</code>, <code>:lmake</code>, etc., which create a location list instead of a quickfix list as the corresponding <code>:vimgrep</code>, <code>:grep</code>, <code>:helpgrep</code>, <code>:make</code> do.                         location-list-file-window A location list is associated with a window and each window can have a separate location list.  A location list can be associated with only one window.  The location list is independent of the quickfix list.</p> <p>When a window with a location list is split, the new window gets a copy of the location list.  When there are no longer any references to a location list, the location list is destroyed.</p> <pre><code>                    *quickfix-changedtick*\n</code></pre> <p>Every quickfix and location list has a read-only changedtick variable that tracks the total number of changes made to the list.  Every time the quickfix list is modified, this count is incremented. This can be used to perform an action only when the list has changed.  The |getqflist()| and |getloclist()| functions can be used to query the current value of changedtick.  You cannot change the changedtick variable.</p> <p>The following quickfix commands can be used.  The location list commands are similar to the quickfix commands, replacing the 'c' prefix in the quickfix command with 'l'.</p> <pre><code>                        *E924*\n</code></pre> <p>If the current window was closed by an |autocommand| while processing a location list command, it will be aborted.</p> <pre><code>                        *E925* *E926*\n</code></pre> <p>If the current quickfix or location list was changed by an |autocommand| while processing a quickfix or location list command, it will be aborted.</p> <pre><code>                        *:cc*\n</code></pre> <p>:cc[!] [nr]     Display error [nr].  If [nr] is omitted, the same :[nr]cc[!]      error is displayed again.  Without [!] this doesn't             work when jumping to another buffer, the current buffer             has been changed, there is the only window for the             buffer and both 'hidden' and 'autowrite' are off.             When jumping to another buffer with [!] any changes to             the current buffer are lost, unless 'hidden' is set or             there is another window for this buffer.             The 'switchbuf' settings are respected when jumping             to a buffer.             When used in the quickfix window the line number can             be used, including \".\" for the current line and \"$\"             for the last line.</p> <pre><code>                        *:ll*\n</code></pre> <p>:ll[!] [nr]     Same as \":cc\", except the location list for the :[nr]ll[!]      current window is used instead of the quickfix list.</p> <pre><code>                    *:cn* *:cne* *:cnext* *E553*\n</code></pre> <p>:[count]cn[ext][!]  Display the [count] next error in the list that             includes a file name.  If there are no file names at             all, go to the [count] next error.  See |:cc| for             [!] and 'switchbuf'.</p> <pre><code>                        *:lne* *:lnext*\n</code></pre> <p>:[count]lne[xt][!]  Same as \":cnext\", except the location list for the             current window is used instead of the quickfix list.</p> <p>:[count]cN[ext][!]      :cp :cprevious :cprev :cN :cNext :[count]cp[revious][!]  Display the [count] previous error in the list that             includes a file name.  If there are no file names at             all, go to the [count] previous error.  See |:cc| for             [!] and 'switchbuf'.</p> <p>:[count]lN[ext][!]      :lp :lprevious :lprev :lN :lNext :[count]lp[revious][!]  Same as \":cNext\" and \":cprevious\", except the location             list for the current window is used instead of the             quickfix list.</p> <pre><code>                        *:cabo* *:cabove*\n</code></pre> <p>:[count]cabo[ve]    Go to the [count] error above the current line in the             current buffer.  If [count] is omitted, then 1 is             used.  If there are no errors, then an error message             is displayed.  Assumes that the entries in a quickfix             list are sorted by their buffer number and line             number. If there are multiple errors on the same line,             then only the first entry is used.  If [count] exceeds             the number of entries above the current line, then the             first error in the file is selected.</p> <pre><code>                        *:lab* *:labove*\n</code></pre> <p>:[count]lab[ove]    Same as \":cabove\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cbel* *:cbelow*\n</code></pre> <p>:[count]cbel[ow]    Go to the [count] error below the current line in the             current buffer.  If [count] is omitted, then 1 is             used.  If there are no errors, then an error message             is displayed.  Assumes that the entries in a quickfix             list are sorted by their buffer number and line             number.  If there are multiple errors on the same             line, then only the first entry is used.  If [count]             exceeds the number of entries below the current line,             then the last error in the file is selected.</p> <pre><code>                        *:lbel* *:lbelow*\n</code></pre> <p>:[count]lbel[ow]    Same as \":cbelow\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cbe* *:cbefore*\n</code></pre> <p>:[count]cbe[fore]   Go to the [count] error before the current cursor             position in the current buffer.  If [count] is             omitted, then 1 is used.  If there are no errors, then             an error message is displayed.  Assumes that the             entries in a quickfix list are sorted by their buffer,             line and column numbers.  If [count] exceeds the             number of entries before the current position, then             the first error in the file is selected.</p> <pre><code>                        *:lbe* *:lbefore*\n</code></pre> <p>:[count]lbe[fore]   Same as \":cbefore\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:caf* *:cafter*\n</code></pre> <p>:[count]caf[ter]    Go to the [count] error after the current cursor             position in the current buffer.  If [count] is             omitted, then 1 is used.  If there are no errors, then             an error message is displayed.  Assumes that the             entries in a quickfix list are sorted by their buffer,             line and column numbers.  If [count] exceeds the             number of entries after the current position, then             the last error in the file is selected.</p> <pre><code>                        *:laf* *:lafter*\n</code></pre> <p>:[count]laf[ter]    Same as \":cafter\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cnf* *:cnfile*\n</code></pre> <p>:[count]cnf[ile][!] Display the first error in the [count] next file in             the list that includes a file name.  If there are no             file names at all or if there is no next file, go to             the [count] next error.  See |:cc| for [!] and             'switchbuf'.</p> <pre><code>                        *:lnf* *:lnfile*\n</code></pre> <p>:[count]lnf[ile][!] Same as \":cnfile\", except the location list for the             current window is used instead of the quickfix list.</p> <p>:[count]cNf[ile][!]         :cpf :cpfile :cNf :cNfile :[count]cpf[ile][!] Display the last error in the [count] previous file in             the list that includes a file name.  If there are no             file names at all or if there is no next file, go to             the [count] previous error.  See |:cc| for [!] and             'switchbuf'.</p> <p>:[count]lNf[ile][!]         :lpf :lpfile :lNf :lNfile :[count]lpf[ile][!] Same as \":cNfile\" and \":cpfile\", except the location             list for the current window is used instead of the             quickfix list.</p> <pre><code>                        *:crewind* *:cr*\n</code></pre> <p>:cr[ewind][!] [nr]  Display error [nr].  If [nr] is omitted, the FIRST             error is displayed.  See |:cc|.</p> <pre><code>                        *:lrewind* *:lr*\n</code></pre> <p>:lr[ewind][!] [nr]  Same as \":crewind\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cfirst* *:cfir*\n</code></pre> <p>:cfir[st][!] [nr]   Same as \":crewind\".</p> <pre><code>                        *:lfirst* *:lfir*\n</code></pre> <p>:lfir[st][!] [nr]   Same as \":lrewind\".</p> <pre><code>                        *:clast* *:cla*\n</code></pre> <p>:cla[st][!] [nr]    Display error [nr].  If [nr] is omitted, the LAST             error is displayed.  See |:cc|.</p> <pre><code>                        *:llast* *:lla*\n</code></pre> <p>:lla[st][!] [nr]    Same as \":clast\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cq* *:cquit*\n</code></pre> <p>:cq[uit][!] :{N}cq[uit][!] :cq[uit][!] {N}     Quit Vim with error code {N}.  {N} defaults to one.             Useful when Vim is called from another program:             e.g., a compiler will not compile the same file again,             <code>git commit</code> will abort the committing process, <code>fc</code>             (built-in for shells like bash and zsh) will not             execute the command, etc.             {N} can also be zero, in which case Vim exits             normally.             WARNING: All changes in files are lost.  It works like             \":qall!\" |:qall|, except that Nvim exits non-zero or             [count].</p> <pre><code>                        *:cf* *:cfi* *:cfile*\n</code></pre> <p>:cf[ile][!] [errorfile] Read the error file and jump to the first error.             This is done automatically when Vim is started with             the -q option.  You can use this command when you             keep Vim running while compiling.  If you give the             name of the errorfile, the 'errorfile' option will             be set to [errorfile].  See |:cc| for [!].             If the encoding of the error file differs from the             'encoding' option, you can use the 'makeencoding'             option to specify the encoding.</p> <pre><code>                        *:lf* *:lfi* *:lfile*\n</code></pre> <p>:lf[ile][!] [errorfile] Same as \":cfile\", except the location list for the             current window is used instead of the quickfix list.             You can not use the -q command-line option to set             the location list.</p> <p>:cg[etfile] [errorfile]                 :cg :cgetfile             Read the error file.  Just like \":cfile\" but don't             jump to the first error.             If the encoding of the error file differs from the             'encoding' option, you can use the 'makeencoding'             option to specify the encoding.</p> <p>:lg[etfile] [errorfile]                 :lg :lge :lgetfile             Same as \":cgetfile\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:caddf* *:caddfile*\n</code></pre> <p>:caddf[ile] [errorfile] Read the error file and add the errors from the             errorfile to the current quickfix list. If a quickfix             list is not present, then a new list is created.             If the encoding of the error file differs from the             'encoding' option, you can use the 'makeencoding'             option to specify the encoding.</p> <pre><code>                        *:laddf* *:laddfile*\n</code></pre> <p>:laddf[ile] [errorfile] Same as \":caddfile\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                    *:cb* *:cbuffer* *E681*\n</code></pre> <p>:cb[uffer][!] [bufnr]   Read the error list from the current buffer.             When [bufnr] is given it must be the number of a             loaded buffer.  That buffer will then be used instead             of the current buffer.             A range can be specified for the lines to be used.             Otherwise all lines in the buffer are used.             See |:cc| for [!].</p> <pre><code>                    *:lb* *:lbuffer*\n</code></pre> <p>:lb[uffer][!] [bufnr]   Same as \":cbuffer\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                    *:cgetb* *:cgetbuffer*\n</code></pre> <p>:cgetb[uffer] [bufnr]   Read the error list from the current buffer.  Just             like \":cbuffer\" but don't jump to the first error.</p> <pre><code>                    *:lgetb* *:lgetbuffer*\n</code></pre> <p>:lgetb[uffer] [bufnr]   Same as \":cgetbuffer\", except the location list for             the current window is used instead of the quickfix             list.</p> <pre><code>                    *:cad* *:cadd* *:caddbuffer*\n</code></pre> <p>:cad[dbuffer] [bufnr]   Read the error list from the current buffer and add             the errors to the current quickfix list.  If a             quickfix list is not present, then a new list is             created. Otherwise, same as \":cbuffer\".</p> <pre><code>                        *:laddb* *:laddbuffer*\n</code></pre> <p>:laddb[uffer] [bufnr]   Same as \":caddbuffer\", except the location list for             the current window is used instead of the quickfix             list.</p> <pre><code>                        *:cex* *:cexpr* *E777*\n</code></pre> <p>:cex[pr][!] {expr}  Create a quickfix list using the result of {expr} and             jump to the first error.             If {expr} is a String, then each newline terminated             line in the String is processed using the global value             of 'errorformat' and the result is added to the             quickfix list.             If {expr} is a List, then each String item in the list             is processed and added to the quickfix list.  Non             String items in the List are ignored.             See |:cc| for [!].             Examples:                 :cexpr system('grep -n xyz *')                 :cexpr getline(1, '$')</p> <pre><code>                        *:lex* *:lexpr*\n</code></pre> <p>:lex[pr][!] {expr}  Same as |:cexpr|, except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cgete* *:cgetexpr*\n</code></pre> <p>:cgete[xpr] {expr}  Create a quickfix list using the result of {expr}.             Just like |:cexpr|, but don't jump to the first error.</p> <pre><code>                        *:lgete* *:lgetexpr*\n</code></pre> <p>:lgete[xpr] {expr}  Same as |:cgetexpr|, except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cadde* *:caddexpr*\n</code></pre> <p>:cadde[xpr] {expr}  Evaluate {expr} and add the resulting lines to the             current quickfix list. If a quickfix list is not             present, then a new list is created. The current             cursor position will not be changed. See |:cexpr| for             more information.             Example:     :g/mypattern/caddexpr expand(\"%\") .. \":\" .. line(\".\") ..  \":\" .. getline(\".\")</p> <pre><code>                    *:lad* *:addd* *:laddexpr*\n</code></pre> <p>:lad[dexpr] {expr}  Same as \":caddexpr\", except the location list for the             current window is used instead of the quickfix list.</p> <pre><code>                        *:cl* *:clist*\n</code></pre> <p>:cl[ist] [from] [, [to]]             List all errors that are valid |quickfix-valid|.             If numbers [from] and/or [to] are given, the respective             range of errors is listed.  A negative number counts             from the last error backwards, -1 being the last error.             The |:filter| command can be used to display only the             quickfix entries matching a supplied pattern. The             pattern is matched against the filename, module name,             pattern and text of the entry.</p> <p>:cl[ist] +{count}   List the current and next {count} valid errors.  This             is similar to \":clist from from+count\", where \"from\"             is the current error position.</p> <p>:cl[ist]! [from] [, [to]]             List all errors.</p> <p>:cl[ist]! +{count}  List the current and next {count} error lines.  This             is useful to see unrecognized lines after the current             one.  For example, if \":clist\" shows:         8384 testje.java:252: error: cannot find symbol             Then using \":cl! +3\" shows the reason:         8384 testje.java:252: error: cannot find symbol         8385:   ZexitCode = Fmainx();         8386:               ^         8387:   symbol:   method Fmainx()  </p> <p>:lli[st] [from] [, [to]]                :lli :llist             Same as \":clist\", except the location list for the             current window is used instead of the quickfix list.</p> <p>:lli[st]! [from] [, [to]]             List all the entries in the location list for the             current window.</p> <p>If you insert or delete lines, mostly the correct error location is still found because hidden marks are used.  Sometimes, when the mark has been deleted for some reason, the message \"line changed\" is shown to warn you that the error location may not be correct.  If you quit Vim and start again the marks are lost and the error locations may not be correct anymore.</p> <p>Two autocommands are available for running commands before and after a quickfix command (':make', ':grep' and so on) is executed. See |QuickFixCmdPre| and |QuickFixCmdPost| for details.</p> <pre><code>                    *QuickFixCmdPost-example*\n</code></pre> <p>When 'encoding' differs from the locale, the error messages may have a different encoding from what Vim is using.  To convert the messages you can use this code:     function QfMakeConv()        let qflist = getqflist()        for i in qflist           let i.text = iconv(i.text, \"cp936\", \"utf-8\")        endfor        call setqflist(qflist)     endfunction</p> <pre><code>au QuickfixCmdPost make call QfMakeConv()\n</code></pre> <p>Another option is using 'makeencoding'.</p> <pre><code>                        *quickfix-title*\n</code></pre> <p>Every quickfix and location list has a title. By default the title is set to the command that created the list. The |getqflist()| and |getloclist()| functions can be used to get the title of a quickfix and a location list respectively. The |setqflist()| and |setloclist()| functions can be used to modify the title of a quickfix and location list respectively. Examples:     call setqflist([], 'a', {'title' : 'Cmd output'})     echo getqflist({'title' : 1})     call setloclist(3, [], 'a', {'title' : 'Cmd output'})     echo getloclist(3, {'title' : 1})</p> <pre><code>                        *quickfix-index*\n</code></pre> <p>When you jump to a quickfix/location list entry using any of the quickfix commands (e.g. |:cc|, |:cnext|, |:cprev|, etc.), that entry becomes the currently selected entry. The index of the currently selected entry in a quickfix/location list can be obtained using the getqflist()/getloclist() functions. Examples:     echo getqflist({'idx' : 0}).idx     echo getqflist({'id' : qfid, 'idx' : 0}).idx     echo getloclist(2, {'idx' : 0}).idx</p> <p>For a new quickfix list, the first entry is selected and the index is 1.  Any entry in any quickfix/location list can be set as the currently selected entry using the setqflist() function. Examples:     call setqflist([], 'a', {'idx' : 12})     call setqflist([], 'a', {'id' : qfid, 'idx' : 7})     call setloclist(1, [], 'a', {'idx' : 7})</p> <pre><code>                        *quickfix-size*\n</code></pre> <p>You can get the number of entries (size) in a quickfix and a location list using the |getqflist()| and |getloclist()| functions respectively. Examples:     echo getqflist({'size' : 1})     echo getloclist(5, {'size' : 1})</p> <pre><code>                        *quickfix-context*\n</code></pre> <p>Any Vim type can be associated as a context with a quickfix or location list. The |setqflist()| and the |setloclist()| functions can be used to associate a context with a quickfix and a location list respectively. The |getqflist()| and the |getloclist()| functions can be used to retrieve the context of a quickfix and a location list respectively. This is useful for a Vim plugin dealing with multiple quickfix/location lists. Examples:  </p> <pre><code>let somectx = {'name' : 'Vim', 'type' : 'Editor'}\ncall setqflist([], 'a', {'context' : somectx})\necho getqflist({'context' : 1})\n\nlet newctx = ['red', 'green', 'blue']\ncall setloclist(2, [], 'a', {'id' : qfid, 'context' : newctx})\necho getloclist(2, {'id' : qfid, 'context' : 1})\n\n                        *quickfix-parse*\n</code></pre> <p>You can parse a list of lines using 'errorformat' without creating or modifying a quickfix list using the |getqflist()| function. Examples:     echo getqflist({'lines' : [\"F1:10:Line10\", \"F2:20:Line20\"]})     echo getqflist({'lines' : systemlist('grep -Hn quickfix *')}) This returns a dictionary where the \"items\" key contains the list of quickfix entries parsed from lines. The following shows how to use a custom 'errorformat' to parse the lines without modifying the 'errorformat' option:     echo getqflist({'efm' : '%f#%l#%m', 'lines' : ['F1#10#Line']})</p> <p>EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST:                             :cdo :cdo[!] {cmd}       Execute {cmd} in each valid entry in the quickfix list.             It works like doing this:                 :cfirst                 :{cmd}                 :cnext                 :{cmd}                 etc.             When the current file can't be |abandon|ed and the [!]             is not present, the command fails.             When going to the next entry fails execution stops.             The last buffer (or where an error occurred) becomes             the current buffer.             {cmd} can contain '|' to concatenate several commands.</p> <pre><code>        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</code></pre> <p>:cfdo[!] {cmd}      Execute {cmd} in each file in the quickfix list.             It works like doing this:                 :cfirst                 :{cmd}                 :cnfile                 :{cmd}                 etc.             Otherwise it works the same as <code>:cdo</code>.</p> <pre><code>                        *:ldo*\n</code></pre> <p>:ld[o][!] {cmd}     Execute {cmd} in each valid entry in the location list             for the current window.             It works like doing this:                 :lfirst                 :{cmd}                 :lnext                 :{cmd}                 etc.             Only valid entries in the location list are used.             Otherwise it works the same as <code>:cdo</code>.</p> <pre><code>                        *:lfdo*\n</code></pre> <p>:lfdo[!] {cmd}      Execute {cmd} in each file in the location list for             the current window.             It works like doing this:                 :lfirst                 :{cmd}                 :lnfile                 :{cmd}                 etc.             Otherwise it works the same as <code>:ldo</code>.</p> <p>FILTERING A QUICKFIX OR LOCATION LIST:                     cfilter-plugin :Cfilter :Lfilter If you have too many entries in a quickfix list, you can use the cfilter plugin to reduce the number of entries.  Load the plugin with:  </p> <pre><code>packadd cfilter\n</code></pre> <p>Then you can use the following commands to filter a quickfix/location list:  </p> <pre><code>:Cfilter[!] /{pat}/\n:Lfilter[!] /{pat}/\n</code></pre> <p>The |:Cfilter| command creates a new quickfix list from the entries matching {pat} in the current quickfix list. {pat} is a Vim |regular-expression| pattern. Both the file name and the text of the entries are matched against {pat}. If the optional ! is supplied, then the entries not matching {pat} are used. The pattern can be optionally enclosed using one of the following characters: ', \", /. If the pattern is empty, then the last used search pattern is used.</p> <p>The |:Lfilter| command does the same as |:Cfilter| but operates on the current location list.</p> <p>The current quickfix/location list is not modified by these commands, so you can go back to the unfiltered list using the |:colder|/|:lolder| command.</p> <p>============================================================================= 2. The error window                 quickfix-window</p> <pre><code>                    *:cope* *:copen* *w:quickfix_title*\n</code></pre> <p>:cope[n] [height]   Open a window to show the current list of errors.</p> <pre><code>        When [height] is given, the window becomes that high\n        (if there is room).  When [height] is omitted the\n        window is made ten lines high.\n\n        If there already is a quickfix window, it will be made\n        the current window.  It is not possible to open a\n        second quickfix window.  If [height] is given the\n        existing window will be resized to it.\n\n                        *quickfix-buffer*\n        The window will contain a special buffer, with\n        'buftype' equal to \"quickfix\".  Don't change this!\n        The window will have the w:quickfix_title variable set\n        which will indicate the command that produced the\n        quickfix list. This can be used to compose a custom\n        status line if the value of 'statusline' is adjusted\n        properly. Whenever this buffer is modified by a\n        quickfix command or function, the |b:changedtick|\n        variable is incremented.  You can get the number of\n        this buffer using the getqflist() and getloclist()\n        functions by passing the \"qfbufnr\" item. For a\n        location list, this buffer is wiped out when the\n        location list is removed.\n\n                        *:lop* *:lopen*\n</code></pre> <p>:lop[en] [height]   Open a window to show the location list for the             current window. Works only when the location list for             the current window is present.  You can have more than             one location window opened at a time.  Otherwise, it             acts the same as \":copen\".</p> <pre><code>                        *:ccl* *:cclose*\n</code></pre> <p>:ccl[ose]       Close the quickfix window.</p> <pre><code>                        *:lcl* *:lclose*\n</code></pre> <p>:lcl[ose]       Close the window showing the location list for the             current window.</p> <pre><code>                        *:cw* *:cwindow*\n</code></pre> <p>:cw[indow] [height] Open the quickfix window when there are recognized             errors.  If the window is already open and there are             no recognized errors, close the window.</p> <pre><code>                        *:lw* *:lwindow*\n</code></pre> <p>:lw[indow] [height] Same as \":cwindow\", except use the window showing the             location list for the current window.</p> <pre><code>                        *:cbo* *:cbottom*\n</code></pre> <p>:cbo[ttom]      Put the cursor in the last line of the quickfix window             and scroll to make it visible.  This is useful for             when errors are added by an asynchronous callback.             Only call it once in a while if there are many             updates to avoid a lot of redrawing.</p> <pre><code>                        *:lbo* *:lbottom*\n</code></pre> <p>:lbo[ttom]      Same as \":cbottom\", except use the window showing the             location list for the current window.</p> <p>Normally the quickfix window is at the bottom of the screen.  If there are vertical splits, it's at the bottom of the rightmost column of windows.  To make it always occupy the full width:     :botright cwindow You can move the window around with |window-moving| commands. For example, to move it to the top: CTRL-W K The 'winfixheight' option will be set, which means that the window will mostly keep its height, ignoring 'winheight' and 'equalalways'.  You can change the height manually (e.g., by dragging the status line above it with the mouse).</p> <p>In the quickfix window, each line is one error.  The line number is equal to the error number.  The current entry is highlighted with the QuickFixLine highlighting.  You can change it to your liking, e.g.:     :hi QuickFixLine ctermbg=Yellow guibg=Yellow</p> <p>You can use \":.cc\" to jump to the error under the cursor. Hitting the  key or double-clicking the mouse on a line has the same effect.  The file containing the error is opened in the window above the quickfix window.  If there already is a window for that file, it is used instead.  If the buffer in the used window has changed, and the error is in another file, jumping to the error will fail.  You will first have to make sure the window contains a buffer which can be abandoned. <p>When you select a file from the quickfix window, the following steps are used to find a window to edit the file:</p> <ol> <li>If a window displaying the selected file is present in the current tabpage    (starting with the window before the quickfix window), then that window is    used.</li> <li>If the above step fails and if 'switchbuf' contains \"usetab\" and a window    displaying the selected file is present in any one of the tabpages    (starting with the first tabpage) then that window is used.</li> <li>If the above step fails then a window in the current tabpage displaying a    buffer with 'buftype' not set (starting with the window before the quickfix    window) is used.</li> <li>If the above step fails and if 'switchbuf' contains \"uselast\", then the    previously accessed window is used.</li> <li>If the above step fails then the window before the quickfix window is used.    If there is no previous window, then the window after the quickfix window    is used.</li> <li>If the above step fails, then a new horizontally split window above the    quickfix window is used.<pre><code>            *CTRL-W_&lt;Enter&gt;* *CTRL-W_&lt;CR&gt;*\n</code></pre> <p>You can use CTRL-W  to open a new window and jump to the error there. <p>When the quickfix window has been filled, two autocommand events are triggered.  First the 'filetype' option is set to \"qf\", which triggers the FileType event (also see |qf.vim|).  Then the BufReadPost event is triggered, using \"quickfix\" for the buffer name.  This can be used to perform some action on the listed errors.  Example:     au BufReadPost quickfix  setlocal modifiable         \\ | silent exe 'g/^/s//\\=line(\".\") .. \" \"/'         \\ | setlocal nomodifiable This prepends the line number to each line.  Note the use of \"\\=\" in the substitute string of the \":s\" command, which is used to evaluate an expression. The BufWinEnter event is also triggered, again using \"quickfix\" for the buffer name.</p> <p>Note: When adding to an existing quickfix list the autocommand are not triggered.</p> <p>Note: Making changes in the quickfix window has no effect on the list of errors.  'modifiable' is off to avoid making changes.  If you delete or insert lines anyway, the relation between the text and the error number is messed up. If you really want to do this, you could write the contents of the quickfix window to a file and use \":cfile\" to have it parsed and used as the new error list.</p> <pre><code>                    *location-list-window*\n</code></pre> <p>The location list window displays the entries in a location list.  When you open a location list window, it is created below the current window and displays the location list for the current window.  The location list window is similar to the quickfix window, except that you can have more than one location list window open at a time. When you use a location list command in this window, the displayed location list is used.</p> <p>When you select a file from the location list window, the following steps are used to find a window to edit the file:</p> <ol> <li>If a non-quickfix window associated with the location list is present in    the current tabpage, then that window is used.</li> <li>If the above step fails and if the file is already opened in another window    in the current tabpage, then that window is used.</li> <li>If the above step fails and 'switchbuf' contains \"usetab\" and if the file    is opened in a window in any one of the tabpages, then that window is used.</li> <li>If the above step fails then a window in the current tabpage showing a    buffer with 'buftype' not set is used.</li> <li>If the above step fails, then the file is edited in a new window.</li> </ol> <p>In all of the above cases, if the location list for the selected window is not yet set, then it is set to the location list displayed in the location list window.</p> <pre><code>                        *quickfix-window-ID*\n</code></pre> <p>You can use the |getqflist()| and |getloclist()| functions to obtain the window ID of the quickfix window and location list window respectively (if present).  Examples:     echo getqflist({'winid' : 1}).winid     echo getloclist(2, {'winid' : 1}).winid</p> <pre><code>                        *getqflist-examples*\n</code></pre> <p>The |getqflist()| and |getloclist()| functions can be used to get the various attributes of a quickfix and location list respectively. Some examples for using these functions are below:</p> <pre><code>\" get the title of the current quickfix list\n:echo getqflist({'title' : 0}).title\n\n\" get the identifier of the current quickfix list\n:let qfid = getqflist({'id' : 0}).id\n\n\" get the identifier of the fourth quickfix list in the stack\n:let qfid = getqflist({'nr' : 4, 'id' : 0}).id\n\n\" check whether a quickfix list with a specific identifier exists\n:if getqflist({'id' : qfid}).id == qfid\n\n\" get the index of the current quickfix list in the stack\n:let qfnum = getqflist({'nr' : 0}).nr\n\n\" get the items of a quickfix list specified by an identifier\n:echo getqflist({'id' : qfid, 'items' : 0}).items\n\n\" get the number of entries in a quickfix list specified by an id\n:echo getqflist({'id' : qfid, 'size' : 0}).size\n\n\" get the context of the third quickfix list in the stack\n:echo getqflist({'nr' : 3, 'context' : 0}).context\n\n\" get the number of quickfix lists in the stack\n:echo getqflist({'nr' : '$'}).nr\n\n\" get the number of times the current quickfix list is changed\n:echo getqflist({'changedtick' : 0}).changedtick\n\n\" get the current entry in a quickfix list specified by an identifier\n:echo getqflist({'id' : qfid, 'idx' : 0}).idx\n\n\" get all the quickfix list attributes using an identifier\n:echo getqflist({'id' : qfid, 'all' : 0})\n\n\" parse text from a List of lines and return a quickfix list\n:let myList = [\"a.java:10:L10\", \"b.java:20:L20\"]\n:echo getqflist({'lines' : myList}).items\n\n\" parse text using a custom 'efm' and return a quickfix list\n:echo getqflist({'lines' : ['a.c#10#Line 10'], 'efm':'%f#%l#%m'}).items\n\n\" get the quickfix list window id\n:echo getqflist({'winid' : 0}).winid\n\n\" get the quickfix list window buffer number\n:echo getqflist({'qfbufnr' : 0}).qfbufnr\n\n\" get the context of the current location list\n:echo getloclist(0, {'context' : 0}).context\n\n\" get the location list window id of the third window\n:echo getloclist(3, {'winid' : 0}).winid\n\n\" get the location list window buffer number of the third window\n:echo getloclist(3, {'qfbufnr' : 0}).qfbufnr\n\n\" get the file window id of a location list window (winnr: 4)\n:echo getloclist(4, {'filewinid' : 0}).filewinid\n\n                        *setqflist-examples*\n</code></pre> <p>The |setqflist()| and |setloclist()| functions can be used to set the various attributes of a quickfix and location list respectively. Some examples for using these functions are below:</p> <pre><code>\" create an empty quickfix list with a title and a context\n:let t = 'Search results'\n:let c = {'cmd' : 'grep'}\n:call setqflist([], ' ', {'title' : t, 'context' : c})\n\n\" set the title of the current quickfix list\n:call setqflist([], 'a', {'title' : 'Mytitle'})\n\n\" change the current entry in the list specified by an identifier\n:call setqflist([], 'a', {'id' : qfid, 'idx' : 10})\n\n\" set the context of a quickfix list specified by an identifier\n:call setqflist([], 'a', {'id' : qfid, 'context' : {'val' : 100}})\n\n\" create a new quickfix list from a command output\n:call setqflist([], ' ', {'lines' : systemlist('grep -Hn main *.c')})\n\n\" parse text using a custom efm and add to a particular quickfix list\n:call setqflist([], 'a', {'id' : qfid,\n    \\ 'lines' : [\"a.c#10#L10\", \"b.c#20#L20\"], 'efm':'%f#%l#%m'})\n\n\" add items to the quickfix list specified by an identifier\n:let newItems = [{'filename' : 'a.txt', 'lnum' : 10, 'text' : \"Apple\"},\n        \\ {'filename' : 'b.txt', 'lnum' : 20, 'text' : \"Orange\"}]\n:call setqflist([], 'a', {'id' : qfid, 'items' : newItems})\n\n\" empty a quickfix list specified by an identifier\n:call setqflist([], 'r', {'id' : qfid, 'items' : []})\n\n\" free all the quickfix lists in the stack\n:call setqflist([], 'f')\n\n\" set the title of the fourth quickfix list\n:call setqflist([], 'a', {'nr' : 4, 'title' : 'SomeTitle'})\n\n\" create a new quickfix list at the end of the stack\n:call setqflist([], ' ', {'nr' : '$',\n        \\ 'lines' : systemlist('grep -Hn class *.java')})\n\n\" create a new location list from a command output\n:call setloclist(0, [], ' ', {'lines' : systemlist('grep -Hn main *.c')})\n\n\" replace the location list entries for the third window\n:call setloclist(3, [], 'r', {'items' : newItems})\n</code></pre> <p>============================================================================= 3. Using more than one list of errors           quickfix-error-lists</p> <p>So far has been assumed that there is only one list of errors.  Actually the ten last used lists are remembered.  When starting a new list, the previous ones are automatically kept.  Two commands can be used to access older error lists.  They set one of the existing error lists as the current one.</p> <pre><code>                    *:colder* *:col* *E380*\n</code></pre> <p>:col[der] [count]   Go to older error list.  When [count] is given, do             this [count] times.  When already at the oldest error             list, an error message is given.</p> <pre><code>                    *:lolder* *:lol*\n</code></pre> <p>:lol[der] [count]   Same as <code>:colder</code>, except use the location list for             the current window instead of the quickfix list.</p> <pre><code>                    *:cnewer* *:cnew* *E381*\n</code></pre> <p>:cnew[er] [count]   Go to newer error list.  When [count] is given, do             this [count] times.  When already at the newest error             list, an error message is given.</p> <pre><code>                    *:lnewer* *:lnew*\n</code></pre> <p>:lnew[er] [count]   Same as <code>:cnewer</code>, except use the location list for             the current window instead of the quickfix list.</p> <pre><code>                    *:chistory* *:chi*\n</code></pre> <p>:[count]chi[story]  Show the list of error lists.  The current list is             marked with \"&gt;\".  The output looks like:               error list 1 of 3; 43 errors   :make              &gt; error list 2 of 3; 0 errors    :helpgrep tag                error list 3 of 3; 15 errors   :grep ex_help *.c  </p> <pre><code>        When [count] is given, then the count'th quickfix\n        list is made the current list. Example:  \n            \" Make the 4th quickfix list current\n            :4chistory\n\n                    *:lhistory* *:lhi*\n</code></pre> <p>:[count]lhi[story]  Show the list of location lists, otherwise like             <code>:chistory</code>.</p> <p>When adding a new error list, it becomes the current list.</p> <p>When \":colder\" has been used and \":make\" or \":grep\" is used to add a new error list, one newer list is overwritten.  This is especially useful if you are browsing with \":grep\" |grep|.  If you want to keep the more recent error lists, use \":cnewer 99\" first.</p> <p>To get the number of lists in the quickfix and location list stack, you can use the |getqflist()| and |getloclist()| functions respectively with the list number set to the special value '$'. Examples:     echo getqflist({'nr' : '$'}).nr     echo getloclist(3, {'nr' : '$'}).nr To get the number of the current list in the stack:     echo getqflist({'nr' : 0}).nr</p> <p>============================================================================= 4. Using :make                      :make_makeprg</p> <pre><code>                        *:mak* *:make*\n</code></pre> <p>:mak[e][!] [arguments]  1. All relevant |QuickFixCmdPre| autocommands are                executed.             2. If the 'autowrite' option is on, write any changed                buffers             3. An errorfile name is made from 'makeef'.  If                'makeef' doesn't contain \"##\", and a file with this                name already exists, it is deleted.             4. The program given with the 'makeprg' option is                started (default \"make\") with the optional                [arguments] and the output is saved in the                errorfile (for Unix it is also echoed on the                screen).             5. The errorfile is read using 'errorformat'.             6. All relevant |QuickFixCmdPost| autocommands are                executed.  See example below.             7. If [!] is not given the first error is jumped to.             8. The errorfile is deleted.             9. You can now move through the errors with commands                like |:cnext| and |:cprevious|, see above.             This command does not accept a comment, any \"             characters are considered part of the arguments.             If the encoding of the program output differs from the             'encoding' option, you can use the 'makeencoding'             option to specify the encoding.</p> <pre><code>                        *:lmak* *:lmake*\n</code></pre> <p>:lmak[e][!] [arguments]             Same as \":make\", except the location list for the             current window is used instead of the quickfix list.</p> <p>The \":make\" command executes the command given with the 'makeprg' option. This is done by passing the command to the shell given with the 'shell' option.  This works almost like typing</p> <pre><code>\":!{makeprg} [arguments] {shellpipe} {errorfile}\".\n</code></pre> <p>{makeprg} is the string given with the 'makeprg' option.  Any command can be used, not just \"make\".  Characters '%' and '#' are expanded as usual on a command-line.  You can use \"%&lt;\" to insert the current file name without extension, or \"#&lt;\" to insert the alternate file name without extension, for example:    :set makeprg=make\\ #&lt;.o</p> <p>[arguments] is anything that is typed after \":make\". {shellpipe} is the 'shellpipe' option. {errorfile} is the 'makeef' option, with ## replaced to make it unique.</p> <p>The placeholder \"$\" can be used for the argument list in {makeprg} if the command needs some additional characters after its arguments.  The $ is replaced then by all arguments.  Example:    :set makeprg=latex\\ \\\\nonstopmode\\ \\\\input\\{$} or simpler    :let &amp;mp = 'latex \\nonstopmode \\input{$}' \"$\" can be given multiple times, for example:    :set makeprg=gcc\\ -o\\ $\\ $*</p> <p>The 'shellpipe' option defaults to \"2&gt;&amp;1| tee\" for Win32. This means that the output of the compiler is saved in a file and not shown on the screen directly.  For Unix \"| tee\" is used.  The compiler output is shown on the screen and saved in a file the same time.  Depending on the shell used \"|&amp; tee\" or \"2&gt;&amp;1| tee\" is the default, so stderr output will be included.</p> <p>If 'shellpipe' is empty, the {errorfile} part will be omitted.  This is useful for compilers that write to an errorfile themselves.</p> <p>Using QuickFixCmdPost to fix the encoding  </p> <p>It may be that 'encoding' is set to an encoding that differs from the messages your build program produces.  This example shows how to fix this after Vim has read the error messages:  </p> <pre><code>function QfMakeConv()\n   let qflist = getqflist()\n   for i in qflist\n      let i.text = iconv(i.text, \"cp936\", \"utf-8\")\n   endfor\n   call setqflist(qflist)\nendfunction\n\nau QuickfixCmdPost make call QfMakeConv()\n</code></pre> <p>(Example by Faque Cheng) Another option is using 'makeencoding'.</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":"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> 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>Pre-requisite: multi-modal editing</p> <p> Multi-modal Editing is a recommended pre-requisite</p> <p>Aliases to run Clojure REPL - Practicalli Clojure CLI Config</p> <p> Practicalli Clojure CLI config contains aliases used to start a Clojure REPL and other development tools.  Aliases are used extensively through the Clojure sections of this book.</p> Practicalli Neovim config replaces some key bindings <p>Practicalli Neovim Config 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 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>Paste Evaluation result</p> <p>\" C p  to paste the contents of the <code>C</code> register into the current buffer. </p> <p>The result of every Conjure evaluation is stored in the <code>C</code> register when using Practicalli AstroNvim Config.</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/documentation/","title":"Documentation","text":"<p>K or Space l h shows the documentation for the function under the cursor in a popup window.</p> <p>K a second time to jump the cursor to the popup window to scroll the text if required (or use a mouse wheel)</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>"},{"location":"repl-driven-development/refactor-tools/#function-documentation","title":"Function documentation","text":"<p>K or Space l h show the doc-string for function or any other var 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> <p>, l l code lens refresh</p> <p>, l L code lens run</p>"},{"location":"repl-driven-development/refactor-tools/#navigation","title":"Navigation","text":"<p>g d go to definition of current symbol, e.g. function definition</p> <p>, l G telescope search of all symbols in the project</p> <p>, l R telescope search of all references in the project</p> <p>, l s telescope search of symbols</p> <p>, l s split view of symbols</p>"},{"location":"repl-driven-development/refactor-tools/#diagnostics","title":"Diagnostics","text":"<p>Space l d show popup for current diagnostic indicator</p> <p>Space l D search through all diagnostics reports</p>"},{"location":"repl-driven-development/refactor-tools/#code-actions","title":"Code Actions","text":"<p>Space l r rename current symbol (namespace rename not supported by LSP client)</p> <p>Space l a code actions (popup with available actions)</p> <p>Space l f format buffer</p>"},{"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> <p>Space l I shows format and lint tools supported by null-ls for the current filetype, e.g. clojure</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":"source-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":"source-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":"source-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":"source-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":"source-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":"source-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":"source-control/diff/#nvimdiff","title":"nvimdiff","text":"<p>The Git <code>difftool</code> can specify Neovim as a diff viewer to show Git diff views of all the files that have changes</p> <p>nvimdiff as a command line option</p> <pre><code>git difftool --tool=nvimdiff &lt;optional-filename&gt;\n</code></pre> <p><code>git difftool</code> can be configured to use Neovim </p> <p>Git client config to set <code>nvimdiff</code> as <code>difftool</code></p> ~/.config/git/config<pre><code>[diff]\n  # Neovim diff tool\n  tool = nvimdiff\n</code></pre> <p>Run <code>git difftool</code> in the root of the project to show the diff of each changed file.</p> <pre><code>git difftool &lt;optional-filename&gt;\n</code></pre> <p>: q a to close the current diff view.  The command line prompts to open the next file as a diff view (assuming there are more files to view).</p>"},{"location":"source-control/diff/#diffview","title":"DiffView","text":"<p>DiffView compares working space and staged changes side by side, or a diff for git merge conflicts.</p> AstroNvimPracticalli Neovim Config <p>Space g d or <code>d</code> in neogit status buffer (<code>SPC g s</code>) will open diffview in a new tab</p> <p>[ c to move to previous hunk</p> <p>] c to move to next hunk</p> <p>Space g to return to neovim buffer or q to return to neogit status buffer</p> <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> <ul> <li>Green - added lines</li> <li>Yellow - changed line</li> <li>Red - deleted lines</li> </ul>"},{"location":"source-control/lazygit/","title":"Lazygit version control","text":"Command Line or AstroNvim configuration <p>Lazygit interface not provided by Practicalli Neovim Config Redux</p>"},{"location":"source-control/lazygit/#requirements","title":"Requirements","text":"<p>Install lazygit command line tool</p>"},{"location":"source-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":"source-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":"source-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":"source-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":"source-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":"source-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":"source-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":"source-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":"source-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":"source-control/neogit/#modify-git-commit-history","title":"Modify Git commit history","text":"<p><code>r</code> opens the rebase menu</p>"},{"location":"source-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":"source-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":"source-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":"source-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>"},{"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 -L -O https://github.com/clojure/brew-install/releases/latest/download/linux-install.sh &amp;&amp; \\\nchmod +x linux-install.sh &amp;&amp; \\\n./linux-install.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 calling <code>clojure</code> with the --help option, which shows the options available to the command</p> <pre><code>clojure --help\n</code></pre> <p>Also consider running a repl to ensure the dependency download is working correctly</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>optionally install rlwrap package if using the basic repl terminal UI with the <code>clj</code> wrapper</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>"}]}
\ No newline at end of file