diff --git a/.editorconfig b/.editorconfig index 43456223..2f767ae8 100644 --- a/.editorconfig +++ b/.editorconfig @@ -14,7 +14,7 @@ indent_style = space indent_size = 2 trim_trailing_whitespace = false -[*.{js,nix,yml,yaml}] +[*.{js,json,nix,yml,yaml}] indent_style = space indent_size = 2 tab_width = 2 @@ -26,3 +26,6 @@ trim_trailing_whitespace = unset [*.lock] indent_size = unset + +[npins/sources.json] +insert_final_newline = unset diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index 739d2d2c..97a82378 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1,4 +1 @@ github: NotAShelf -ko_fi: NotAShelf -liberapay: NotAShelf - diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md index b2a26919..66fe9c0f 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -7,14 +7,17 @@ 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 #` outside this comment, and it will be closed when your pull request is merged. + +A developer package template is provided in flake/develop.nix. If working on a module, you may use +it to test your changes with minimal dependency changes. --> ## Sanity Checking --- diff --git a/.github/README.md b/.github/README.md index 5d10c73f..01395211 100644 --- a/.github/README.md +++ b/.github/README.md @@ -50,6 +50,7 @@ [Contribute]: #contributing [FAQ]: #frequently-asked-questions [Credits]: #credits +[License]: #license **[
 Features
][Features]** **[
 Get Started 
][Get Started]** @@ -67,6 +68,10 @@ [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 +[release notes]: https://notashelf.github.io/nvf/release-notes.html +[discussions tab]: https://github.com/notashelf/nvf/discussions +[FAQ section]: #frequently-asked-questions +[DAG]: https://en.wikipedia.org/wiki/Directed_acyclic_graph - **Simple**: One language to rule them all! Use Nix to configure everything, with optional Lua support for robust configurability! @@ -79,11 +84,31 @@ 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. - - Lazyloading? We got it! Lazyload both internal and external plugins at will. + - Lazyloading 💤? We got it! Lazyload both internal and external plugins at + will. + - nvf allows _ordering configuration bits_ using [DAG] (_Directed acyclic + graph_)s. It has never been easier to construct an editor configuration + deterministically! + - nvf exposes everything you need to avoid a vendor lock-in. Which means you + can add new modules, plugins and so on without relying on us adding a module + for them! Though, of course, feel free to request them. + - Use plugins from anywhere. Inputs, npins, nixpkgs... You name it. + - Add your own modules, with ease. It's all built-in! - **Well-documented**: Documentation is priority. You will _never_ face undocumented, obscure behaviour. + - Changes, breaking or otherwise, will be communicated in the [release notes] + - Refer to the [FAQ section] for answers to common questions. + - Your question not there? Head to the to the [discussions tab]! - **Idiomatic**: nvf does things ✨ _the right way_ ✨ - the codebase is, and will, remain maintainable for myself and any contributors. +- **Community-Led**: we would like nvf to be fully capable of accomplishing what + you really want it to do. If you have a use case that is not made possible by + nvf, please open an issue (or a pull request!) + - Your feedback is more than welcome! Feedback is what _drives_ nvf forward. + If you have anything to say, or ask, please let us know. + - Pull requests are _always_ welcome. If you think the project can benefit + from something you did locally, but are not quite sure how to upstream, + please feel free to contact us! We'll help you get it done. ## Get Started @@ -173,39 +198,66 @@ fix. [list of open pull requests]: https://github.com/NotAShelf/nvf/pulls **Q**: What platforms are supported? -
**A**: nvf actively supports **Linux and Darwin** platforms using -standalone Nix, NixOS or Home-Manager. Please take a look at the [nvf manual] -for available installation instructions. + +**A**: nvf actively supports **Linux and Darwin** platforms using standalone +Nix, NixOS or Home-Manager. Please take a look at the [nvf manual] for available +installation instructions. **Q**: Can you add _X_? -
**A**: Maybe! It is not one of our goals to support each and every Neovim + +**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, pull requests to add new features are also welcome. **Q**: A plugin I need is not available in **nvf**. What to do? -
**A**: **nvf** exposes several APIs for you to be able to add your own -plugin configurations! Please see the documentation on how you may do this. + +**A**: **nvf** exposes several APIs for you to be able to add your own plugin +configurations! Please see the documentation on how you may do this. **Q**: Main branch is awfully silent, is the project dead? -
**A**: No! Sometimes we branch out (e.g. `v0.6`) to avoid breaking -userspace and work in a separate branch until we make sure the new additions are -implemented in the most comfortable way possible for the end user. If you have -not noticed any activity on the main branch, consider taking a look at the + +**A**: No! Sometimes we branch out (e.g. `v0.6`) to avoid breaking userspace and +work in a separate branch until we make sure the new additions are implemented +in the most comfortable way possible for the end user. If you have not noticed +any activity on the main branch, consider taking a look at the [list of branches] or the [list of open pull requests]. You may also consider _testing_ those release branches to get access to new features ahead of time and better prepare to breaking changes. **Q**: Will you support non-flake installations? -
**A**: Quite possibly. **nvf** started as "neovim-flake", which does mean -it is and will remain flakes-first but we might consider non-flakes -compatibility. Though keep in mind that **nvf** under non-flake environments -would lose customizability of plugin inputs, which is one of our primary -features. + +**A**: Quite possibly. **nvf** started as "neovim-flake", which does mean it is +and will remain flakes-first but we might consider non-flakes compatibility. +Though keep in mind that **nvf** under non-flake environments would lose +customizability of plugin inputs, which is one of our primary features. + +**Q**: I prefer working with Lua, can I use nvf as a plugin manager while I use +an imperative path (e.g., `~/.config/nvim`) for my Neovim configuration instead +of a configuration generated from Nix? + +**A**: Yes! Add `"~/.config.nvim"` to `vim.additionalRuntimePaths = [ ... ]` and +any plugins you want to load to `vim.startPlugins`. This will load your +configuration from `~/.config/nvim`. You may still use `vim.*` to modify +Neovim's behaviour with Nix. ## Credits +### Co-Maintainers + +Alongside myself, nvf is developed by those talented folk: + +- [**@horriblename**](https://github.com/horriblename) + ([Liberapay](https://liberapay.com/horriblename/))- For actively implementing + planned features and quality of life updates. +- [**@Diniamo**](https://github.com/Diniamo) + ([Liberapay](https://en.liberapay.com/diniamo/)) - For actively submitting + pull requests, issues and assistance with maintenance of nvf. + +Please do remember to extend your thanks (financially or otherwise) if this +project has been helpful to you. + ### Contributors [mnw]: https://github.com/gerg-l/mnw @@ -213,41 +265,39 @@ features. 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 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 +- [**@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, and other module additions. -- [@horriblename](https://github.com/horriblename) - For actively implementing - 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 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. +- [**@Yavko**](https://github.com/Yavko) - For the amazing **nvf** logo +- [**@FrothyMarrow**](https://github.com/FrothyMarrow) - For seeing mistakes + that I could not. +- [**@Gerg-l**](https://github.com/gerg-l) 🐸 - For the modern Neovim wrapper, + [mnw], and occasional code improvements. +- [**@Soliprem**](https://github.com/soliprem) - Rigorously implementing missing + features and excellent work on new language modules. and everyone who has submitted issues or pull requests! ### Inspiration -This configuration borrows from and is based on a few other configurations, +This configuration borrows from, and is based on a few other configurations, including: - [@jordanisaacs's](https://github.com/jordanisaacs) - [neovim-flake](https://github.com/jordanisaacs/neovim-flake) that this flake - is originally based on. -- [@sioodmy's](https://github.com/sioodmy) - [dotfiles](https://github.com/sioodmy/dotfiles) that inspired the design - choices for UI and plugin defaults. + [**neovim-flake**](https://github.com/jordanisaacs/neovim-flake) that this + flake is originally based on. - [@wiltaylor's](https://github.com/wiltaylor) [neovim-flake](https://github.com/wiltaylor/neovim-flake) for plugin and design ideas. - [@gvolpe's](https://github.com/gvolpe) [neovim-flake](https://github.com/gvolpe/neovim-flake) for plugin, design and nix concepts. +- [@sioodmy's](https://github.com/sioodmy) + [dotfiles](https://github.com/sioodmy/dotfiles) that inspired the design + choices for UI and plugin defaults. I am grateful for their previous work and inspiration, and I wholeheartedly recommend checking their work out. @@ -255,12 +305,12 @@ 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 +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) -under explicit permission by the artist. +under explicit permission by the author or authors.
Yes, this includes the logo work too. Stop taking artwork that is not yours!
diff --git a/.github/typos.toml b/.github/typos.toml index df76201c..2ea46a8c 100644 --- a/.github/typos.toml +++ b/.github/typos.toml @@ -1,2 +1,5 @@ default.extend-ignore-words-re = ["(?i)(noice)", "befores", "annote", "viw"] +files.extend-exclude = [ +"npins/sources.json" +] diff --git a/.github/workflows/cachix.yml b/.github/workflows/cachix.yml index 4aa0b215..cac8ee51 100644 --- a/.github/workflows/cachix.yml +++ b/.github/workflows/cachix.yml @@ -35,7 +35,6 @@ jobs: - name: Install Nix uses: DeterminateSystems/nix-installer-action@main - - uses: DeterminateSystems/magic-nix-cache-action@main - uses: cachix/cachix-action@v15 with: diff --git a/.github/workflows/check-docs.yml b/.github/workflows/check-docs.yml index b543c813..4d133ecd 100644 --- a/.github/workflows/check-docs.yml +++ b/.github/workflows/check-docs.yml @@ -21,7 +21,6 @@ jobs: steps: - name: Install Nix uses: DeterminateSystems/nix-installer-action@main - - uses: DeterminateSystems/magic-nix-cache-action@main - name: Checkout uses: actions/checkout@v4 @@ -42,13 +41,13 @@ 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 diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 8101b8b1..7a7677eb 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -19,7 +19,6 @@ jobs: - name: Install Nix uses: DeterminateSystems/nix-installer-action@main - - uses: DeterminateSystems/magic-nix-cache-action@main - name: Check Flake run: nix flake check @@ -33,6 +32,5 @@ jobs: - name: Install Nix uses: DeterminateSystems/nix-installer-action@main - - uses: DeterminateSystems/magic-nix-cache-action@main - run: nix run nixpkgs#alejandra -- -c . diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml new file mode 100644 index 00000000..f8f45d05 --- /dev/null +++ b/.github/workflows/docs-preview.yml @@ -0,0 +1,184 @@ +name: Build and Preview Manual + +on: + workflow_dispatch: + pull_request_target: + types: [opened, synchronize, reopened, closed] + paths: + - ".github/workflows/docs-preview.yml" + - "modules/**" + - "docs/**" + +# Defining permissions here passes it to all workflows. +# https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token +permissions: + contents: write + pull-requests: write + issues: write + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + build-preview: + runs-on: ubuntu-latest + steps: + - name: Install Nix + uses: DeterminateSystems/nix-installer-action@main + + - name: Checkout + uses: actions/checkout@v4 + + - name: Set default git branch (to reduce log spam) + run: git config --global init.defaultBranch main + + - name: Build documentation packages + run: nix build .#docs-html --print-build-logs + + - name: Deploy to GitHub Pages preview + run: | + PR_NUMBER=${{ github.event.pull_request.number }} + BRANCH_NAME="gh-pages" + PREVIEW_DIR="docs-preview-${PR_NUMBER}" + + # Clone the gh-pages branch and move to the preview subdirectory + git clone --single-branch --branch $BRANCH_NAME https://github.com/${{ github.repository }} gh-pages + cd gh-pages + + mkdir -p $PREVIEW_DIR + + # Copy the build files to the preview subdirectory + cp -rvf ../result/share/doc/nvf/* ./$PREVIEW_DIR + + # Configure git to use the GitHub Actions token for authentication + git config --global user.name "GitHub Actions" + git config --global user.email "actions@github.com" + + # Set the GitHub token for authentication + git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }} + + # Add and commit the changes + git add --all + git commit -m "Deploy PR #${PR_NUMBER} preview" || echo "No changes to commit" + git push --force origin $BRANCH_NAME + + comment-url: + needs: build-preview + runs-on: ubuntu-latest + steps: + - name: Prepare Environment + id: prelude + run: | + PR_NUMBER=${{ github.event.pull_request.number }} + URL="https://${{ github.repository_owner }}.github.io/nvf/docs-preview-${PR_NUMBER}/" + + # Propagate non-interpolatable environment vars + echo "URL=$URL" >> "$GITHUB_OUTPUT" + echo "REV=$GITHUB_SHA" >> "$GITHUB_OUTPUT" + echo "ACTOR=$GITHUB_ACTOR" >> "$GITHUB_OUTPUT" + echo "REF=$GITHUB_HEAD_REF" >> "$GITHUB_OUTPUT" + echo "RUNS=$GITHUB_RUN_NUMBER" >> "$GITHUB_OUTPUT" + + echo "Live Preview URL: $URL" + echo "Rev: $GITHUB_SHA" + echo "Actor: $GITHUB_ACTOR" + echo "Ref: "$GITHUB_HEAD_REF" + echo "Reruns: "$GITHUB_RUN_NUMBER" + + echo "### :rocket: Live Preview Deployed " >> "$GITHUB_STEP_SUMMARY" + echo "Preview can be found at ${URL}" >> "$GITHUB_STEP_SUMMARY" + + - name: Find Comment + uses: peter-evans/find-comment@v3 + id: fc + with: + comment-author: "github-actions[bot]" + issue-number: ${{ github.event.pull_request.number }} + body-includes: "Live preview deployed" + + - name: Post live preview comment + uses: peter-evans/create-or-update-comment@v4 + env: + COMMENT_ID: ${{ steps.fc.outputs.comment-id }} + URL: ${{ steps.prelude.outputs.URL }} + GITHUB_SHA: ${{ steps.prelude.outputs.REV }} + ACTOR: ${{ steps.prelude.outputs.ACTOR }} + REF: ${{ steps.prelude.outputs.REF }} + RUNS: ${{ steps.prelude.outputs.RUNS }} + with: + comment-id: ${{ env.COMMENT_ID }} + issue-number: ${{ github.event.pull_request.number }} # issue number also applies to pull requests + edit-mode: replace # replace previous body + body: | + ### :rocket: Live preview deployed from ${{ env.GITHUB_SHA }} + + View it [here](${{ env.URL }}): + +
+ Debug Information +

Triggered by: ${{ env.ACTOR }}

+

HEAD at: ${{ env.REF }}

+

Reruns: ${{ env.RUNS }}

+
+ + cleanup: + if: ${{ github.event.pull_request.merged == true || github.event.pull_request.state == 'closed' }} + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Delete preview for closed/merged PR + run: | + PR_NUMBER=${{ github.event.pull_request.number }} + BRANCH_NAME="gh-pages" + PREVIEW_DIR="docs-preview-${PR_NUMBER}" + + # Clone the gh-pages branch + git clone --single-branch --branch $BRANCH_NAME https://github.com/${{ github.repository }} gh-pages + cd gh-pages + + # Check if the preview directory exists, and delete it if it does + if [ -d "$PREVIEW_DIR" ]; then + echo "Deleting preview directory $PREVIEW_DIR" + rm -rf $PREVIEW_DIR + else + echo "Preview directory $PREVIEW_DIR does not exist. Skipping deletion." + fi + + # Configure git to use the GitHub Actions token for authentication + git config --global user.name "GitHub Actions" + git config --global user.email "actions@github.com" + + # Set the GitHub token for authentication + git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }} + + # Add and commit the changes (only if there's something to delete) + git add . + git diff --quiet || git commit -m "Remove preview for PR #${PR_NUMBER}" + git push origin $BRANCH_NAME + + cleanup-comment: + needs: cleanup + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Double check preview directory deletion + run: | + # Check if the preview directory exists, and delete it if it does + if [ -d "docs-preview-${{ github.event.pull_request.number }}" ]; then + echo "Something went wrong, preview directory is not deleted." + exit 1 + else + echo "Preview directory has been deleted successfully, proceeding." + fi + + - name: Post cleanup verification + uses: peter-evans/create-or-update-comment@v4 + with: + issue-number: ${{ github.event.pull_request.number }} + body: | + ✅ Preview has been deleted successfully! diff --git a/.github/workflows/editorconfig.yml b/.github/workflows/editorconfig.yml index d411c89f..3d8ca360 100644 --- a/.github/workflows/editorconfig.yml +++ b/.github/workflows/editorconfig.yml @@ -30,7 +30,6 @@ jobs: - name: Install Nix uses: DeterminateSystems/nix-installer-action@main - - uses: DeterminateSystems/magic-nix-cache-action@main - name: Checking EditorConfig shell: bash diff --git a/.github/workflows/manual.yml b/.github/workflows/manual.yml index 5b66c8a6..1c8ab746 100644 --- a/.github/workflows/manual.yml +++ b/.github/workflows/manual.yml @@ -45,7 +45,6 @@ jobs: steps: - uses: actions/checkout@v4.1.7 - uses: DeterminateSystems/nix-installer-action@main - - uses: DeterminateSystems/magic-nix-cache-action@main - run: | nix build .#docs -Lv cp -r result/share/doc/nvf public diff --git a/configuration.nix b/configuration.nix index 3be1d39b..692337db 100644 --- a/configuration.nix +++ b/configuration.nix @@ -1,6 +1,7 @@ # This is the sample configuration for nvf, aiming to give you a feel of the default options -# while certain plugins are enabled. While it may act as one, this is not an overview of nvf's -# module options. To find a complete overview of nvf's options and examples, visit the manual. +# while certain plugins are enabled. While it may partially act as one, this is *not* quite +# an overview of nvf's module options. To find a complete and curated list of nvf module +# options, examples, instruction tutorials and more; please visit the online manual. # https://notashelf.github.io/nvf/options.html isMaximal: { config.vim = { @@ -13,7 +14,7 @@ isMaximal: { }; spellcheck = { - enable = isMaximal; + enable = true; }; lsp = { @@ -80,6 +81,7 @@ isMaximal: { ocaml.enable = false; elixir.enable = false; haskell.enable = false; + ruby.enable = false; tailwind.enable = false; svelte.enable = false; @@ -171,15 +173,18 @@ isMaximal: { utility = { ccc.enable = false; vim-wakatime.enable = false; + diffview-nvim.enable = true; + yanky-nvim.enable = false; icon-picker.enable = isMaximal; surround.enable = isMaximal; - diffview-nvim.enable = true; + leetcode-nvim.enable = isMaximal; + multicursors.enable = isMaximal; + motion = { hop.enable = true; leap.enable = true; precognition.enable = isMaximal; }; - images = { image-nvim.enable = false; }; diff --git a/docs/man/header.5 b/docs/man/header.5 index a28fc3dd..556a113a 100644 --- a/docs/man/header.5 +++ b/docs/man/header.5 @@ -1,13 +1,16 @@ -.TH "nvf" "5" "01/01/1980" "nvf" +.TH "nvf" "5" "January 1, 1980" "nvf" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" enable line breaks after slashes .cflags 4 / + .SH "NAME" -nvf configuration specification -.SH "OPTIONS" -.PP -You can use the following options to configure nvf: -.PP +nvf \- Configuration specification for the nvf. + +.SH "DESCRIPTION" +The nvf configuration specification provides a declarative structure for configuring Neovim using Nix with few +lines of Nix. This document outlines the available options and their usage to create modular, reusable, and +reproducible configurations using nvf's module system options. For tips, tricks and possible quirks with available +plugins please visit https://notashelf.github.io/nvf/ diff --git a/docs/man/nvf.1 b/docs/man/nvf.1 index 0f1e36dc..d7519651 100644 --- a/docs/man/nvf.1 +++ b/docs/man/nvf.1 @@ -1,5 +1,5 @@ .Dd January 1, 1980 -.Dt nvf 1 +.Dt NVF 1 .Os nvf .\" disable hyphenation .nh @@ -7,27 +7,46 @@ .ad l .\" enable line breaks after slashes .cflags 4 / + .Sh NAME .Nm nvf -.Nd A highly modular, extensible and distro-agnostic Neovim configuration framework for Nix/NixOS. -. +.Nd A modular, extensible, and distro-agnostic Neovim configuration framework for Nix/NixOS. + +.Sh DESCRIPTION +.Nm nvf +is a highly modular, configurable, extensible, and easy-to-use Neovim configuration in Nix. +Designed for flexibility and ease of use, nvf allows you to easily configure your fully featured +Neovim instance with a few lines of Nix. + +.Sh COMMANDS +The following commands are bundled with nvf to allow easier debugging of your configuration. + +.Bl -tag -width Ds +.It Nm nvf-print-config +Outputs the full configuration of the current `nvf` setup. This command is useful for debugging +or inspecting the applied configuration. +.Pp +.It Nm nvf-print-config-path +Prints the file path to the configuration file currently in use. This command is helpful for locating +the source configuration file for troubleshooting or easily sharing it via online paste utilities. +.El + .Sh BUGS .Pp -Please report any bugs that you might encounter on the -\m[blue]\fBproject issue tracker\fR\m[]\&. +Please report any bugs on the project issue tracker: +.Lk https://github.com/notashelf/nvf/issues .Sh SEE ALSO .Pp -\fBnvf\fR(5) +.Fn nvf 5 .Sh AUTHOR .Pp -\fBnvf contributors\fR +.Fn nvf contributors .RS 4 -Author. +Primary contributors and maintainers of the project. .RE .Sh COPYRIGHT -.br -Copyright \(co 2023\(en2024 nvf contributors -.br +.Pp +Copyright (c) 2023–2025 nvf contributors. diff --git a/docs/manual.nix b/docs/manual.nix index 4becdf2d..50a5dab4 100644 --- a/docs/manual.nix +++ b/docs/manual.nix @@ -102,7 +102,7 @@ in --script script/anchor-use.js \ --script script/anchor-min.js \ --script script/search.js \ - --toc-depth 2 \ + --toc-depth 1 \ --section-toc-depth 1 \ manual.md \ "$dest/index.xhtml" diff --git a/docs/manual/configuring.md b/docs/manual/configuring.md index 3ac261fe..f891c7a6 100644 --- a/docs/manual/configuring.md +++ b/docs/manual/configuring.md @@ -3,7 +3,7 @@ ```{=include=} chapters configuring/custom-package.md configuring/custom-plugins.md -configuring/custom-inputs.md +configuring/overriding-plugins.md configuring/languages.md configuring/dags.md configuring/dag-entries.md diff --git a/docs/manual/configuring/custom-inputs.md b/docs/manual/configuring/custom-inputs.md deleted file mode 100644 index 4f2a523b..00000000 --- a/docs/manual/configuring/custom-inputs.md +++ /dev/null @@ -1,53 +0,0 @@ -# Custom Inputs {#ch-custom-inputs} - -One of the greatest strengths of **nvf** is its ability to get plugins from -flake inputs and build them locally from any given source. For plugins that do -not require any kind of additional building step, this is a powerful method of -adding plugins to your configuration that are not packaged in nixpkgs, or those -you want to track from source without relying on nixpkgs. - -The [additional plugins section](#sec-additional-plugins) details the addition -of new plugins to nvf under regular circumstances, i.e. while making a pull -request to the project. You may _override_ those plugin inputs in your own -`flake.nix` to change source versions, e.g., to use newer versions of plugins -that are not yet updated in **nvf**. - -```nix -{ - - inputs = { - # ... - - # The name here is arbitrary, you can name it whatever. - # This will add a plugin input called "your-neodev-input" - # that you can reference in a `follows` line. - your-neodev-input = { - url = "github:folke/neodev.nvim"; - flake = false; - }; - - nvf = { - url = "github:notashelf/nvf"; - - # The name of the input must match for the follows line - # plugin-neodev-nvim is what the input is called inside nvf - # so you must match the exact name here. - inputs.plugin-neodev-nvim.follows = "your-neodev-input"; - }; - # ... - }; -} -``` - -This will override the source for the `neodev.nvim` plugin that is used in nvf -with your own input. You can update your new input via `nix flake update` or -more specifically `nix flake update ` to keep it up to date. - -::: {.warning} - -While updating plugin inputs, make sure that any configuration that has been -deprecated in newer versions is changed in the plugin's `setupOpts`. If you -depend on a new version, requesting a version bump in the issues section is a -more reliable option. - -::: diff --git a/docs/manual/configuring/overriding-plugins.md b/docs/manual/configuring/overriding-plugins.md new file mode 100644 index 00000000..bb698666 --- /dev/null +++ b/docs/manual/configuring/overriding-plugins.md @@ -0,0 +1,35 @@ +# Overriding plugins {#ch-overriding-plugins} + +The [additional plugins section](#sec-additional-plugins) details the addition +of new plugins to nvf under regular circumstances, i.e. while making a pull +request to the project. You may _override_ those plugins in your config +to change source versions, e.g., to use newer versions of plugins +that are not yet updated in **nvf**. + +```nix +vim.pluginOverrides = { + lazydev-nvim = pkgs.fetchFromGitHub { + owner = "folke"; + repo = "lazydev.nvim"; + rev = ""; + hash = ""; + }; + # It's also possible to use a flake input + lazydev-nvim = inputs.lazydev-nvim; + # Or a local path + lazydev-nvim = ./lazydev; + # Or a npins pin... etc +}; +``` + +This will override the source for the `neodev.nvim` plugin that is used in nvf +with your own plugin. + +::: {.warning} + +While updating plugin inputs, make sure that any configuration that has been +deprecated in newer versions is changed in the plugin's `setupOpts`. If you +depend on a new version, requesting a version bump in the issues section is a +more reliable option. + +::: diff --git a/docs/manual/hacking/additional-plugins.md b/docs/manual/hacking/additional-plugins.md index e67fa96b..0ed252c7 100644 --- a/docs/manual/hacking/additional-plugins.md +++ b/docs/manual/hacking/additional-plugins.md @@ -1,36 +1,25 @@ # Adding Plugins {#sec-additional-plugins} -To add a new Neovim plugin, first add the source url in the inputs section of -`flake.nix` with the prefix `plugin-` +To add a new Neovim plugin, use `npins` + +Use: + +`nix-shell -p npins` or `nix shell nixpkgs#npins` + +Then run: + +`npins add --name github -b ` + +Be sure to replace any non-alphanumeric characters with `-` for `--name` + +For example + +`npins add --name lazydev-nvim github folke lazydev.nvim -b main` + +You can now reference this plugin as a **string**. ```nix -{ - inputs = { - # ... - plugin-neodev-nvim = { - url = "github:folke/neodev.nvim"; - flake = false; - }; - # ... - }; -} -``` - -Prepending `plugin-` to the name of the input will allow nvf to automatically -discover inputs that are marked as plugins, and make them available in -`vim.startPlugins` or other areas that require a very specific plugin type as it -is defined in `@NVF_REPO@/lib/types/plugins.nix` - -The addition of the `plugin-` prefix will allow **nvf** to autodiscover the -input from the flake inputs automatically, allowing you to refer to it in areas -that require a very specific plugin type as defined in `lib/types/plugins.nix` - -You can now reference this plugin using its string name, the plugin will be -built with the name and source URL from the flake input, allowing you to refer -to it as a **string**. - -```nix -config.vim.startPlugins = ["neodev-nvim"]; +config.vim.startPlugins = ["lazydev-nvim"]; ``` ## Modular setup options {#sec-modular-setup-options} diff --git a/docs/manual/hacking/guidelines.md b/docs/manual/hacking/guidelines.md index 882deea8..a1db27e8 100644 --- a/docs/manual/hacking/guidelines.md +++ b/docs/manual/hacking/guidelines.md @@ -14,14 +14,11 @@ necessarily) before you start developing. ## Adding Documentation {#sec-guidelines-documentation} -Most, if not all, changes warrant changes to the documentation. Module options -should be documented with -[Nixpkgs-flavoured Markdown](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup), -albeit with exceptions. +[Nixpkgs Flavoured Markdown]: https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax -::: {.note} As of **v0.5**, **nvf** is itself documented using full markdown in -both module options and the manual. With **v0.6**, this manual has also been -converted to markdown in full. ::: +Almost all changes warrant updates to the documentation: at the very least, you +must update the changelog. Both the manual and module options use +[Nixpkgs Flavoured Markdown]. The HTML version of this manual containing both the module option descriptions and the documentation of **nvf** (such as this page) can be generated and opened @@ -117,10 +114,11 @@ applies to string literals and module descriptions and documentation. ### Nix {#sec-code-style-nix} -**nvf** is formatted by the -[alejandra](https://github.com/kamadorueda/alejandra) tool and the formatting is -checked in the pull request and push workflows. Run the `nix fmt` command inside -the project repository before submitting your pull request. +[alejandra]: https://github.com/kamadorueda/alejandra + +**nvf** is formatted by the [alejandra] tool and the formatting is checked in +the pull request and push workflows. Run the `nix fmt` command inside the +project repository before submitting your pull request. While Alejandra is mostly opinionated on how code looks after formatting, certain changes are done at the user's discretion based on how the original code @@ -138,10 +136,14 @@ module = { # same as parent modules, unfold submodules subModule = { # this is an option that contains more than one nested value + # Note: try to be careful about the ordering of `mkOption` arguments. + # General rule of thumb is to order from least to most likely to change. + # This is, for most cases, type < default < description. + # Example, if present, would be between default and description someOtherValue = mkOption { type = lib.types.bool; - description = "Some other description"; default = true; + description = "Some other description"; }; }; } diff --git a/docs/manual/installation/custom-configuration.md b/docs/manual/installation/custom-configuration.md index b6c27163..940f35a3 100644 --- a/docs/manual/installation/custom-configuration.md +++ b/docs/manual/installation/custom-configuration.md @@ -23,15 +23,17 @@ An example flake that exposes your custom Neovim configuration might look like nvf.url = "github:notashelf/nvf"; }; - outputs = { - self, - nixpkgs, - ... - } @ inputs: { - packages."x86_64-linux" = let - neovimConfigured = (inputs.nvf.lib.neovimConfiguration { - inherit (nixpkgs.legacyPackages."x86_64-linux") pkgs; - modules = [{ + outputs = {nixpkgs, ...} @ inputs: { + packages.x86_64-linux = { + # Set the default package to the wrapped instance of Neovim. + # This will allow running your Neovim configuration with + # `nix run` and in addition, sharing your configuration with + # other users in case your repository is public. + default = + (inputs.nvf.lib.neovimConfiguration { + pkgs = nixpkgs.legacyPackages.x86_64-linux; + modules = [ + { config.vim = { # Enable custom theming options theme.enable = true; @@ -43,14 +45,10 @@ An example flake that exposes your custom Neovim configuration might look like # reference in Appendix B of the nvf manual. # ... }; - }]; - }); - in { - # Set the default package to the wrapped instance of Neovim. - # This will allow running your Neovim configuration with - # `nix run` and in addition, sharing your configuration with - # other users in case your repository is public. - default = neovimConfigured.neovim; + } + ]; + }) + .neovim; }; }; } diff --git a/docs/manual/installation/modules/home-manager.md b/docs/manual/installation/modules/home-manager.md index a2170159..2b359af5 100644 --- a/docs/manual/installation/modules/home-manager.md +++ b/docs/manual/installation/modules/home-manager.md @@ -10,12 +10,18 @@ To use it, we first add the input flake. ```nix { inputs = { + # Optional, if you intend to follow nvf's obsidian-nvim input + # you must also add it as a flake input. obsidian-nvim.url = "github:epwalsh/obsidian.nvim"; + + # Required, nvf works best and only directly supports flakes nvf = { url = "github:notashelf/nvf"; - # you can override input nixpkgs + # You can override the input nixpkgs to follow your system's + # instance of nixpkgs. This is safe to do as nvf does not depend + # on a binary cache. inputs.nixpkgs.follows = "nixpkgs"; - # you can also override individual plugins + # Optionally, you can also override individual plugins # for example: inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- this will use the obsidian-nvim from your inputs }; @@ -27,8 +33,8 @@ Followed by importing the home-manager module somewhere in your configuration. ```nix { - # assuming nvf is in your inputs and inputs is in the argset - # see example below + # Assuming "nvf" is in your inputs and inputs is in the argument set. + # See example installation below imports = [ inputs.nvf.homeManagerModules.default ]; } ``` @@ -43,13 +49,13 @@ Followed by importing the home-manager module somewhere in your configuration. nvf.url = "github:notashelf/nvf"; }; - outputs = { nixpkgs, home-manager, nvf, ... }: let - system = "x86_64-linux"; in { + outputs = { nixpkgs, home-manager, nvf, ... }: { # ↓ this is your home output in the flake schema, expected by home-manager - "your-username@your-hostname" = home-manager.lib.homeManagerConfiguration + "your-username@your-hostname" = home-manager.lib.homeManagerConfiguration { + pkgs = nixpkgs.legacyPackages.x86_64-linux; modules = [ nvf.homeManagerModules.default # <- this imports the home-manager module that provides the options - ./home.nix # <- your home entrypoint + ./home.nix # <- your home entrypoint, `programs.nvf.*` may be defined here ]; }; }; diff --git a/docs/manual/installation/modules/nixos.md b/docs/manual/installation/modules/nixos.md index d8be2035..bcf7472b 100644 --- a/docs/manual/installation/modules/nixos.md +++ b/docs/manual/installation/modules/nixos.md @@ -10,12 +10,18 @@ To use it, we first add the input flake. ```nix { inputs = { + # Optional, if you intend to follow nvf's obsidian-nvim input + # you must also add it as a flake input. obsidian-nvim.url = "github:epwalsh/obsidian.nvim"; + + # Required, nvf works best and only directly supports flakes nvf = { url = "github:notashelf/nvf"; - # you can override input nixpkgs + # You can override the input nixpkgs to follow your system's + # instance of nixpkgs. This is safe to do as nvf does not depend + # on a binary cache. inputs.nixpkgs.follows = "nixpkgs"; - # you can also override individual plugins + # Optionally, you can also override individual plugins # for example: inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- this will use the obsidian-nvim from your inputs }; @@ -42,13 +48,12 @@ Followed by importing the NixOS module somewhere in your configuration. nvf.url = "github:notashelf/nvf"; }; - outputs = { nixpkgs, nvf, ... }: let - system = "x86_64-linux"; in { + outputs = { nixpkgs, nvf, ... }: { # ↓ this is your host output in the flake schema - nixosConfigurations."yourUsername»" = nixpkgs.lib.nixosSystem { + nixosConfigurations."your-hostname" = nixpkgs.lib.nixosSystem { modules = [ nvf.nixosModules.default # <- this imports the NixOS module that provides the options - ./configuration.nix # <- your host entrypoint + ./configuration.nix # <- your host entrypoint, `programs.nvf.*` may be defined here ]; }; }; diff --git a/docs/manual/installation/standalone/nixos.md b/docs/manual/installation/standalone/nixos.md index a78c8dee..267d15b7 100644 --- a/docs/manual/installation/standalone/nixos.md +++ b/docs/manual/installation/standalone/nixos.md @@ -16,26 +16,32 @@ the default theme enabled. You may use other options inside `config.vim` in nvf.url = "github:notashelf/nvf"; }; - outputs = {nixpkgs, nvf, ...}: let - system = "x86_64-linux"; - pkgs = nixpkgs.legacyPackages.${system}; - configModule = { - # Add any custom options (and do feel free to upstream them!) - # options = { ... }; - - config.vim = { - theme.enable = true; - # and more options as you see fit... - }; - }; - - customNeovim = nvf.lib.neovimConfiguration { - inherit pkgs; - modules = [configModule]; - }; - in { + outputs = { + nixpkgs, + nvf, + self, + ... + }: { # This will make the package available as a flake output under 'packages' - packages.${system}.my-neovim = customNeovim.neovim; + packages.x86_64-linux.my-neovim = + (nvf.lib.neovimConfiguration { + pkgs = nixpkgs.legacyPackages.x86_64-linux; + modules = [ + # Or move this to a separate file and add it's path here instead + # IE: ./nvf_module.nix + ( + {pkgs, ...}: { + # Add any custom options (and do feel free to upstream them!) + # options = { ... }; + config.vim = { + theme.enable = true; + # and more options as you see fit... + }; + } + ) + ]; + }) + .neovim; # Example nixosConfiguration using the configured Neovim package nixosConfigurations = { @@ -43,11 +49,13 @@ the default theme enabled. You may use other options inside `config.vim` in # ... modules = [ # This will make wrapped neovim available in your system packages - {environment.systemPackages = [customNeovim.neovim];} + # Can also move this to another config file if you pass inputs/self around with specialArgs + ({pkgs, ...}: { + environment.systemPackages = [self.packages.${pkgs.stdenv.system}.neovim]; + }) ]; # ... }; }; }; -} -``` +}``` diff --git a/docs/manual/manual.md b/docs/manual/manual.md index fd7ddcd9..fd225766 100644 --- a/docs/manual/manual.md +++ b/docs/manual/manual.md @@ -11,6 +11,7 @@ try-it-out.md default-configs.md installation.md configuring.md +tips.md ``` ```{=include=} chapters diff --git a/docs/manual/options.md b/docs/manual/options.md index 3b70484f..61282dfa 100644 --- a/docs/manual/options.md +++ b/docs/manual/options.md @@ -1,9 +1,13 @@ -# Neovim Flake Configuration Options {#ch-options} +# nvf Configuration Options {#ch-options} Below are the module options provided by nvf, in no particular order. Most options will include useful comments, warnings or setup tips on how a module option is meant to be used as well as examples in complex cases. +An offline version of this page is bundled with nvf as a part of the manpages +which you can access with `man 5 nvf`. Please us know if you believe any of the +options below are missing useful examples. +