treewide: documentation cleanup and fixes

.github/CONTRIBUTING.md

@@ -8,23 +8,42 @@
 
 ## Welcome
 
-I'm glad you are thinking about contributing to neovim-flake! If you're unsure about anything, just ask - or submit the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. Friendly contributions are always welcome.
+I'm glad you are thinking about contributing to nvf! If you're unsure about
+anything, just ask - or submit the issue or pull request anyway. The worst that
+can happen is you'll be politely asked to change something. Friendly
+contributions are always welcome.
 
-Before you contribute, I encourage you to read this project's CONTRIBUTING policy (you are here), its [LICENSE](LICENSE.md), and its [README](README.md).
+Before you contribute, I encourage you to read this project's CONTRIBUTING
+policy (you are here) and its [LICENSE](../LICENSE) to understand how your
+contributions are licensed.
 
-If you have any questions regarding those files, feel free to open an issue or [shoot me an email](mailto:[email protected]). Discussions tab is also available for more informal discussions.
+If you have any questions regarding those files, feel free to open an issue or
+[shoot me an email](mailto:[email protected]). Discussions tab is also available
+for more informal discussions.
 
 ## Contributing
 
-The contribution process is mostly documented in the [pull request template](pull_request_template.md). You will find a checklist of items to complete before submitting a pull request. Please make sure you complete it before submitting a pull request. If you are unsure about any of the items, please ask.
+The contribution process is mostly documented in the
+[pull request template](PULL_REQUEST_TEMPLATE/pull_request_template.md). You
+will find a checklist of items to complete before submitting a pull request.
+Please make sure you complete it before submitting a pull request. If you are
+unsure about any of the items, please ask.
 
 ### Guidelines
 
-We provide instructions on a healthy contribution to neovim-flake - including styling, commit formats, how-to guides for adding new modules and options.
-You are very well recommended to read the contributing guideliner over at [the documentation](https://notashelf.github.io/neovim-flake#hacking)
+We provide instructions on a healthy contribution to neovim-flake - including
+styling, commit formats, how-to guides for adding new modules and options. You
+are very well recommended to read the contributing guidelines over at
+[the documentation](https://notashelf.github.io/nvf#hacking)
 
 ### Code of Conduct
 
-This project does not quite have a code of conduct yet. And to be honest, I'm not sure if I want one or if it will ever have one. I'm not expecting this project to be a hotbed of activity, but I do want to make sure that everyone who does contribute feels welcome and safe. As such, I will do my best to make sure that those who distrupt the project are dealt with swiftly and appropriately.
+This project does not quite have a code of conduct yet. And to be perfectly
+honest, I'm not sure if I want one or if it will ever have one. I'm not
+expecting this project to be a hotbed of activity, but I do want to make sure
+that everyone who does contribute feels welcome and safe. As such, I will do my
+best to make sure that those who distrupt the project are dealt with swiftly and
+appropriately.
 
-If you feel that you are not being treated with respect, please contact me directly.
+If you feel that you are not being treated with respect, please contact me
+directly.

.github/pull_request_template.md → .github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -6,7 +6,7 @@ or dependency in this section.
 
 If your pull request aims to fix an open issue or a please bug, please also link the relevant issue
 below this line. You may attach an issue to your pull request with `Fixes #<issue number>` outside
-this comment.
+this comment, and it will be closed when your pull request is merged.
 -->
 
 ## Sanity Checking
@@ -23,20 +23,20 @@ it above in your description.
 [editorconfig]: https://editorconfig.org
 [changelog]: https://github.com/NotAShelf/nvf/tree/main/docs/release-notes
 
-- [ ] I have updated the [changelog] as per my changes.
-- [ ] I have tested, and self-reviewed my code.
+- [ ] I have updated the [changelog] as per my changes
+- [ ] I have tested, and self-reviewed my code
 - Style and consistency
-  - [ ] I ran **Alejandra** to format my code (`nix fmt`).
-  - [ ] My code conforms to the [editorconfig] configuration of the project.
-  - [ ] My changes are consistent with the rest of the codebase.
+  - [ ] I ran **Alejandra** to format my code (`nix fmt`)
+  - [ ] My code conforms to the [editorconfig] configuration of the project
+  - [ ] My changes are consistent with the rest of the codebase
 - If new changes are particularly complex:
   - [ ] My code includes comments in particularly complex areas
-  - [ ] I have added a section in the manual.
-  - [ ] _(For breaking changes)_ I have included a migration guide.
+  - [ ] I have added a section in the manual
+  - [ ] _(For breaking changes)_ I have included a migration guide
 - Package(s) built:
   - [ ] `.#nix` (default package)
   - [ ] `.#maximal`
-  - [ ] `.#docs-html`
+  - [ ] `.#docs-html` (manual, must build)
 - Tested on platform(s)
   - [ ] `x86_64-linux`
   - [ ] `aarch64-linux`

.github/README.md

@@ -48,28 +48,37 @@
 [Documentation]: #documentation
 [Help]: #help
 [Contribute]: #contributing
-[FAQ]: #faq
+[FAQ]: #frequently-asked-questions
 [Credits]: #credits
 
 **[<kbd><br> Features <br></kbd>][Features]**
 **[<kbd><br> Get Started <br></kbd>][Get Started]**
 **[<kbd><br> Documentation <br></kbd>][Documentation]**
 **[<kbd><br> Help <br></kbd>][Help]**
 **[<kbd><br> Contribute <br></kbd>][Contribute]**
-**[<kbd><br> FAQ <br></kbd>][Faq]** **[<kbd><br> Credits <br></kbd>][Credits]**
+**[<kbd><br> FAQ <br></kbd>][FAQ]** **[<kbd><br> Credits <br></kbd>][Credits]**
 
 </p></div>
 
 ---
 
 ## Features
 
+[standalone]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-installation
+[NixOS module]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-nixos
+[Home-Manager module]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-hm
+
+- **Simple**: One language to rule them all! Use Nix to configure everything,
+  with additional Lua Support
 - **Reproducible**: Your configuration will behave the same _anywhere_. No
   surprises, promise!
 - **Portable**: nvf depends _solely_ on your Nix store, and nothing else. No
   more global binaries! Works on all platforms, without hassle.
+  - Options to install [standalone], [NixOS module] or [Home-Manager module].
 - **Customizable**: There are _almost no defaults_ to annoy you. nvf is fully
   customizable through the Nix module system.
+- Not comfortable with a full-nix config or want to bring your Lua config? You
+  can do just that, no unnecessary restrictions.
 - **Well-documented**: Documentation is priority. You will _never_ face
   undocumented, obscure behaviour.
 - **Idiomatic**: nvf does things ✨ _the right way_ ✨ - the codebase is, and
@@ -120,7 +129,9 @@ instructions.
 
 ## Documentation
 
-The _recommended_ way of installing **nvf** is using either the NixOS or the
+### Installation
+
+The _recommended_ way of installing nvf is using either the NixOS or the
 Home-Manager module, though it is completely possible and no less supported to
 install **nvf** as a standalone package, or a flake output.
 
@@ -138,11 +149,13 @@ Please create an issue on the [issue tracker] if you find the documentation
 lacking or confusing. Any improvements to the documentation through pull
 requests are also welcome, and appreciated.
 
-## Help
+## Getting Help
 
-You can create an issue on the [issue tracker] to ask questions or report bugs.
-I am not yet on spaces like matrix or IRC, so please use the issue tracker for
-now.
+If you are confused, stuck or would like to ask a simple question; you may
+create an issue on the [issue tracker] to ask questions or report bugs.
+
+We are not not yet on spaces like matrix or IRC, so please use the issue tracker
+for now.
 
 ## Contributing
 
@@ -152,21 +165,23 @@ submitting a pull request. You can also create an issue on the [issue tracker]
 before submitting a pull request if you would like to discuss a feature or bug
 fix.
 
-## FAQ
+## Frequently Asked Questions
 
 [appropriate issue template]: https://github.com/NotAShelf/nvf/issues/new/choose
 [list of branches]: https://github.com/NotAShelf/nvf/branches
 [list of open pull requests]: https://github.com/NotAShelf/nvf/pulls
 
 **Q**: What platforms are supported?
 <br/> **A**: nvf actively supports Linux and Darwin platforms using standalone
-Nix, NixOS or Home-Manager. Please take a look at the
+Nix, NixOS or Home-Manager. Please take a look at the [nvf manual] for available
+installation instructions.
 
 **Q**: Can you add _X_?
 <br/> **A**: Maybe! It is not one of our goals to support each and every Neovim
 plugin, however, I am always open to new modules and plugin setup additions to
 **nvf**. Use the [appropriate issue template] and I will consider a module
-addition. As mentioned before, PRs adding new features are also welcome.
+addition. As mentioned before, pull requests to add new features are also
+welcome.
 
 **Q**: A plugin I need is not available in **nvf**. What to do?
 <br/> **A**: **nvf** exposes several APIs for you to be able to add your own
@@ -185,22 +200,26 @@ better prepare to breaking changes.
 
 ### Contributors
 
-Special, heart-felt thanks to
+[mnw]: https://github.com/gerg-l/mnw
+
+nvf would not be what it is today without the awesome people below. Special,
+heart-felt thanks to
 
-- [@fufexan](https://github.com/fufexan) - For the transition to flake-parts
-- [@FlafyDev](https://github.com/FlafyDev) - For getting the home-manager to
-  work
+- [@fufexan](https://github.com/fufexan) - For the transition to flake-parts and
+  invaluable Nix assistance.
+- [@FlafyDev](https://github.com/FlafyDev) - For getting home-manager module to
+  work and Nix assistance.
 - [@n3oney](https://github.com/n3oney) - For making custom keybinds finally
-  possible
+  possible, and other module additions.
 - [@horriblename](https://github.com/horriblename) - For actively implementing
-  planned features and quality of life updates
+  planned features and quality of life updates.
 - [@Yavko](https://github.com/Yavko) - For the amazing **nvf** logo
 - [@FrothyMarrow](https://github.com/FrothyMarrow) - For seeing mistakes that I
-  could not
-- [@Diniamo](https://github.com/Diniamo) - For actively submitting PRs, pull
-  requests and overall assistence
-- [@Gerg-l](https://github.com/gerg-l) - For the modern Neovim wrapper, mnw and
-  occasional code improvements
+  could not.
+- [@Diniamo](https://github.com/Diniamo) - For actively submitting pull
+  requests, issues and assistance with maintenance of nvf.
+- [@Gerg-l](https://github.com/gerg-l) - For the modern Neovim wrapper, [mnw],
+  and occasional code improvements.
 
 and everyone who has submitted issues or pull requests!
 
@@ -214,7 +233,7 @@ including:
   is originally based on.
 - [@sioodmy's](https://github.com/sioodmy)
   [dotfiles](https://github.com/sioodmy/dotfiles) that inspired the design
-  choices.
+  choices for UI and plugin defaults.
 - [@wiltaylor's](https://github.com/wiltaylor)
   [neovim-flake](https://github.com/wiltaylor/neovim-flake) for plugin and
   design ideas.
@@ -229,10 +248,11 @@ recommend checking their work out.
 ## License
 
 Following the license of the
-[original neovim-flake](https://github.com/jordanisaacs/neovim-flake), **nvf**
-has been made available under the [**MIT License**](LICENSE). However, all
-assets and documentation are published under the
-[**CC BY License**](https://github.com/NotAShelf/nvf/blob/main/.github/assets/LICENSE).
+[original neovim-flake](https://github.com/jordanisaacs/neovim-flake), nvf has
+been made available under the [**MIT License**](LICENSE). However, all assets
+and documentation are published under the
+[**CC BY License**](https://github.com/NotAShelf/nvf/blob/main/.github/assets/LICENSE)
+under explicit permission by the artist.
 
 <h6 align="center">Yes, this includes the logo work too. Stop taking artwork that is not yours!</h6>
 

.github/typos.toml

@@ -0,0 +1,2 @@
+
+default.extend-ignore-words-re = ["(?i)(noice)", "befores", "annote", "viw"]

.github/workflows/check-docs.yml

@@ -19,19 +19,12 @@ jobs:
           - docs-manpages
           - docs-json
     steps:
-      - uses: easimon/maximize-build-space@v10
-        with:
-          overprovision-lvm: true
-          remove-android: true
-          remove-dotnet: true
-          remove-haskell: true
-
       - name: Install Nix
         uses: DeterminateSystems/nix-installer-action@main
       - uses: DeterminateSystems/magic-nix-cache-action@main
 
-      - uses: actions/checkout@v4
-        name: Checkout
+      - name: Checkout
+        uses: actions/checkout@v4
 
       - name: Set default git branch (to reduce log spam)
         run: git config --global init.defaultBranch main
@@ -49,3 +42,16 @@ jobs:
         with:
           name: "${{ matrix.package }}"
           path: result/share/doc/nvf
+  flake-docs-linkcheck:
+    name: Validate hyperlinks in documentation sources
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build documentation packages
+        run: nix build .#docs-linkcheck -Lv

.github/workflows/editorconfig.yml

@@ -15,7 +15,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           gh api \
-            repos/notashelf/neovim-flake/pulls/${{github.event.number}}/files --paginate \
+            repos/notashelf/nvf/pulls/${{github.event.number}}/files --paginate \
             | jq '.[] | select(.status != "removed") | .filename' \
             > "$HOME/changed_files"
 

.github/workflows/manual.yml

@@ -47,7 +47,7 @@ jobs:
       - uses: DeterminateSystems/nix-installer-action@main
       - uses: DeterminateSystems/magic-nix-cache-action@main
       - run: |
-          nix build .#docs
+          nix build .#docs -Lv
           cp -r result/share/doc/nvf public
       - uses: peaceiris/actions-gh-pages@v4
         with:

.github/workflows/typos.yml

@@ -0,0 +1,30 @@
+name: "Check for typos in the source tree"
+
+permissions: read-all
+
+on:
+  pull_request:
+  workflow_dispatch:
+  push:
+
+jobs:
+  check-typos:
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.pull_request.title, '[skip ci]')"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Check for typos
+        uses: crate-ci/typos@master
+        with:
+          config: .github/typos.toml
+
+      - name: Fail Gracefully
+        if: ${{ failure() }}
+        shell: bash
+        run: |
+          echo "::error:: Current codebase contains typos that were caught by the CI!"
+          echo "If those typos were intentional, please add them to the ignored regexes in .github/typos.toml"
+          echo "[skip ci] label may be used if this is a one-time issue"
+          exit 1