diff --git a/.editorconfig b/.editorconfig index 43456223..1f39b72e 100644 --- a/.editorconfig +++ b/.editorconfig @@ -14,15 +14,17 @@ indent_style = space indent_size = 2 trim_trailing_whitespace = false -[*.{js,nix,yml,yaml}] +[*.{js,json,nix,yml,yaml,toml}] indent_style = space indent_size = 2 tab_width = 2 -[*.{diff,patch}] +[*.{diff,patch,lock}] end_of_line = unset insert_final_newline = unset trim_trailing_whitespace = unset -[*.lock] +[npins/sources.json] +indent_style = unset indent_size = unset +trim_trailing_whitespace = unset diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index de6ff5ef..2fb071ca 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1 +1,5 @@ -* @NotAShelf +# Codeowners should be used to distinguish the maintainers of the project +# and not contributors of specific modules to nvf. While adding a new module +# please consider adding yourself to 'meta.maintainers' in the module instead +# of CODEOWNERS here. +* @NotAShelf @horriblename @Soliprem diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index a43a9445..2379973f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,48 +2,72 @@ ## Table of Contents -- [Welcome](#welcome) -- [Contributing](#contributing) +- [Preface](#preface) +- [Contributing Process](#contributing-process) - [Code of Conduct](#code-of-conduct) -## Welcome +## Preface -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. +[LICENSE]: ../LICENSE -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. +I am glad you are thinking about contributing to nvf! The project is shaped by +contributors and user feedback, and all contributions are appreciated. -If you have any questions regarding those files, feel free to open an issue or -[shoot me an email](mailto:me@notashelf.dev). Discussions tab is also available -for more informal discussions. +If you are unsure about anything, whether a change is necessary or if it would +be accepted _had_ you created a PR, please just ask! Or submit the issue or pull +request anyway, the worst that can happen is that you will be politely asked to +change something. Friendly contributions are _always_ welcome. -## Contributing +Before you contribute, I encourage you to read the rest of this document for our +contributing policy and guidelines, followed by the [LICENSE] to understand how +your contributions are licensed. -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 +If you have any questions regarding those files, or would like to ask a question +that is not covered by any of them, please feel free to open an issue! +Discussions tab is also available for less formal discussions. You may also +choose to contact me on Discord or Matrix if you would like to talk to me +personally. + +## Contributing Process + +[pull request template]: ./PULL_REQUEST_TEMPLATE.md + +The contribution process is mostly documented in the [pull request template]. +When you create a pull request, you will find a checklist of items to complete +before it can be submitted. We ask that you please complete it before submitting +a pull request to help maintainers provide more specific feedback. 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 guidelines over at -[the documentation](https://notashelf.github.io/nvf#hacking) +We provide instructions for a healthy contribution to nvf. This includes +**styling**, **commit formats**, **how-to guides for common contributions**. You +are strongly encouraged to read the contributing guidelines in full over at +[the documentation](https://notashelf.github.io/nvf#hacking). + +A general gist of our requirements is that you must + +1. Write clean Nix code +2. Self-test your changes +3. Document your changes + +Though, please take a look at the manual for the complete contributing guide. +Please also feel free to let us know if you feel that something is missing. We +hope to provide clear, comprehensive instructions that make the contribution +process a breeze. ### Code of Conduct -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. +This project does not have a formal code of conduct yet, and to be perfectly +honest I am not entirely positive if I want one or if it will _ever_ have one. +This project is not expected to be a hotbed of activity, and I trust my +contributors to keep it civil and respectful. + +I do, however, want to make sure that everyone who does contribute feels welcome +and safe around project spaces. As such, I will do my best to make sure anyone +who disrupts the project or engages in negative behaviour will are dealt with +appropriately, and swiftly. You are invited to share any concerns that you have +with the projects moderation, be it over public or private spaces. If you feel that you are not being treated with respect, please contact me directly. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index c9270b26..be97db2a 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -1,60 +1,120 @@ name: "🐛 Bug Report" -description: "Submit a bug report to help us improve" -#title: "[Bug] " +description: "Submit a bug report to help us improve nvf" +title: "" labels: [bug] body: - type: checkboxes - id: no-duplicate-issues attributes: - label: "⚠️ Please verify that this bug has NOT been reported before." - description: "Search in the issues sections by clicking [HERE](https://github.com/notashelf/neovim-flake/issues?q=)" + label: I have confirmed that this is a bug related to nvf + description: >- + If you are unsure whether this is a bug, a packaging issue, or user error that is *not* + stemming from nvf, please consider creating a [discussion](https://github.com/notashelf/nvf/discussions) + post instead. Invalid bug reports will be closed without an explanation. options: - - label: "I checked all existing issues and didn't find a similar issue" - required: true + - required: true + label: >- + This is a bug, and not an user error or a support request. I understand that my issue + will be closed if it is not a bug in nvf. + - required: true + label: >- + I have checked the [issues tab](https://github.com/notashelf/nvf/issues?q=is%3Aissue) + and confirmed that my issue has not yet been reported. I understand that my issue will + be closed if it is a duplicate. + - type: textarea - id: description - validations: - required: false attributes: - label: "Description" - description: "You could also upload screenshots, if necessary" + label: Description + placeholder: "Describe the issue here..." + description: >- + Describe the issue in detail, with steps you have taken included. If applicable, please include + a minimal reproducible example, relevant Nix logs, comparisons with alternative commands and + screenshots. Do note that **logs** are preferred over screenshots. + validations: + required: true + + - type: dropdown + attributes: + label: Installation Method + description: "How was nvf installed?" + options: + - NixOS Module (`nixosModules.default`) + - Home Manager Module (`homeManagerModules.default`) + - Standalone (flake outputs, `nix profile install`, etc.) + - Other + validations: + required: true + + - type: textarea + attributes: + label: Installation Method (Other) + description: "If you have selected 'Other' in the previous section, please describe your installation method" + placeholder: >- + I installed nvf from... + + - type: textarea + attributes: + label: nvf Version + description: "Which version of nvf are you using? If added as a flake input, write 'master'" + placeholder: >- + For example, v0.8 if consuming nvf from a tagged release. + validations: + required: true + - type: textarea id: steps-to-reproduce + attributes: + label: Reproduction steps + description: "How do you trigger this bug? Please walk us through the problem, step by step" + placeholder: >- + 1. Do this + 2. Do that + 3. Observe validations: required: true - attributes: - label: "👟 Reproduction steps" - description: "How do you trigger this bug? Please walk us through the problem, step by step" - placeholder: "..." + - type: textarea id: expected-behavior - validations: - required: true attributes: - label: "👀 Expected behavior" + label: Expected behavior description: "What did you think would or should happen?" placeholder: "..." + validations: + required: true + - type: textarea id: actual-behavior - validations: - required: true attributes: - label: "😓 Actual Behavior" + label: Actual Behavior description: "What actually happen?" placeholder: "..." - - type: input - id: nix-metadata - attributes: - label: "💻 Metadata" - description: 'Please run `nix-shell -p nix-info --run "nix-info -m"` and paste the result.' - placeholder: '[user@system:~]$ nix-shell -p nix-info --run "nix-info -m"' validations: required: true + + - type: textarea + attributes: + label: System Information + description: "Output of `nix-info --markdown`" + render: bash + placeholder: |- + '[user@system:~]$ nix-shell -p nix-info --run "nix-info --markdown" + - system: + - host os: + - multi-user?: + - sandbox: + - version: + - nixpkgs: + validations: + required: true + - type: textarea id: logs attributes: - label: "📝 Relevant log output" - description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. render: bash + label: "Relevant log output" + description: >- + Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. + + > [!TIP] + > You can get your nvf configuration with `nvf-print-config` and attach it by using a service like termbin.com validations: required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yaml b/.github/ISSUE_TEMPLATE/feature_request.yaml index d7ed2654..819891df 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yaml +++ b/.github/ISSUE_TEMPLATE/feature_request.yaml @@ -1,58 +1,72 @@ name: 🚀 Feature Request description: "Propose a new feature" -#title: "[Feature] " +title: "" labels: [feature-request] body: - type: checkboxes - id: no-duplicate-issues attributes: - label: "⚠️ Please verify that this feature request has NOT been suggested before." - description: "Search in the issues sections by clicking [HERE](https://github.com/notashelf/neovim-flake/issues?q=)" + label: I have verified that this feature request has not been made before + description: >- + Before opening a new issue for feature requests, please consider searching through currently + open issues [here](https://github.com/notashelf/nvf/issues). If you would like to discuss a + new addition beforehand, you may first want to create a new discussion threat and discuss it + with the maintainers [on the discussions tab](https://github.com/notashelf/nvf/discussions) options: - - label: "I checked and didn't find a similar feature request" - required: true + - required: true + label: >- + I have checked the [issues tab](https://github.com/notashelf/nvf/issues?q=is%3Aissue), + and did not find a similar feature request. I understand that my issue will be closed + if it is a duplicate. + - type: dropdown id: feature-area attributes: - label: "🏷️ Feature Type" - description: "What kind of a feature request is this?" + label: Feature Type + description: Please describe the kind of addition this is multiple: true options: - - New Command - - New Addon - - API Additions + - New Plugin + - Update Request (Plugin/Nixpkgs) + - Documentation Updates - Other validations: required: true + + - type: textarea id: feature-description + attributes: + label: Feature description + description: >- + Please provide a clear and concise description of the desired addition. If this is a plugin + addition, please also include a link to the desired plugin and the reason why you think this + is a good addition. Keep in mind that we may refuse plugin requests as nvf already provides + appropriate methods of installing plugins in user configurations. + placeholder: >- + "nvf currently does [...], which really frustrates me" or "You should add [...] because I think + [...]" validations: required: true - attributes: - label: "🔖 Feature description" - description: "A clear and concise description of what your feature request is." - placeholder: "'You should add [...]' or '[...] has always frustrated me' " - - type: textarea - id: solution - validations: - required: true - attributes: - label: "✔️ Solution" - description: "A clear and concise description of what you want to happen." - placeholder: "In my use-case, I would like [...]" + - type: textarea id: alternatives + attributes: + label: Alternatives + description: >- + If you have tried anything before creating this issue, please give us a clear and concise + description of any alternative solutions or methods you have considered. + placeholder: "I have considered [...]" validations: required: false - attributes: - label: "❓ Alternatives" - description: "A clear and concise description of any alternative solutions or features you've considered." - placeholder: "I have considered [...]" + - type: textarea id: additional-context + attributes: + label: Additional Context + description: >- + If there is anything else you would like to mention, such as additional context or screenshots + demonstrating the requested feature, please add them here. This field is optional, but you may + be requested to provide further context. Please ensure that your feature request clearly describes + the requested feature in good detail. validations: required: false - attributes: - label: "📝 Additional Context" - description: "Add any other context or screenshots about the feature request here." - placeholder: "..." diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE.md similarity index 76% rename from .github/PULL_REQUEST_TEMPLATE/pull_request_template.md rename to .github/PULL_REQUEST_TEMPLATE.md index b2a26919..66fe9c0f 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/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/labels.yml b/.github/labels.yml new file mode 100644 index 00000000..34c3bf2c --- /dev/null +++ b/.github/labels.yml @@ -0,0 +1,55 @@ +# This file is used by .github/workflows/labels.yml +"topic: plugins": + - any: + - changed-files: + - any-glob-to-any-file: + - modules/plugins/**/* + +"topic: modules": + - any: + - changed-files: + - any-glob-to-any-file: + - modules/**/* + +"topic: dependencies": + - any: + - changed-files: + - any-glob-to-any-file: + - npins + - flake.lock + +"topic: CI": + - any: + - changed-files: + - any-glob-to-any-file: + - .github/workflows/*.yml + - .github/typos.toml + - .github/dependabot.yml + +"topic: meta": + - any: + - changed-files: + - any-glob-to-any-file: + - .github/CODEOWNERS + - LICENSE + - .github/README.md + - .github/funding.yml + - .github/assets + - .github/*_TEMPLATE + - .gitignore + - .editorconfig + - release.json + +"topic: documentation": + - any: + - changed-files: + - any-glob-to-any-file: + - docs/**/* + - .github/CONTRIBUTING.md + - .github/README.md +"topic: packaging": + - any: + - changed-files: + - any-glob-to-any-file: + - flake.nix + - flake/packages.nix diff --git a/.github/typos.toml b/.github/typos.toml index df76201c..2cd18dde 100644 --- a/.github/typos.toml +++ b/.github/typos.toml @@ -1,2 +1,10 @@ -default.extend-ignore-words-re = ["(?i)(noice)", "befores", "annote", "viw"] +files.extend-exclude = ["npins/sources.json"] +default.extend-ignore-words-re = [ + "(?i)(noice)", + "befores", + "annote", + "viw", + "BA", # somehow "BANanaD3V" is valid, but BA is not... +] + diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml new file mode 100644 index 00000000..7868e55b --- /dev/null +++ b/.github/workflows/backport.yml @@ -0,0 +1,33 @@ +name: Backport PR on Label + +on: + pull_request_target: + types: + - labeled + +# Permissions needed for the korthout/backport-action to create branches and PRs +permissions: + contents: write + pull-requests: write + +jobs: + backport: + name: Create Backport PR + runs-on: ubuntu-latest + if: | + github.event.pull_request.merged == true && startsWith(github.event.label.name, 'backport-') + steps: + - uses: actions/checkout@v5 + with: + ref: ${{ github.event.pull_request.head.sha }} + token: ${{ steps.app-token.outputs.token }} + + - name: Backport Action + uses: korthout/backport-action@v3 + with: + # Regex pattern for labels that should trigger a backport AND extracts the target branch + # from the name (e.g. v0.x or v0.x.y; we use zerover). This action will ONLY proceed if + # the label that triggered the workflow fully matches this pattern. + # Example matching labels: "backport-v0.1", "backport-v0.10.1" + # Example non-matching labels: "backport-foo", "backport-v1.0" + label_pattern: '^backport-(v0\.\d+(\.\d+)?)$' diff --git a/.github/workflows/cachix.yml b/.github/workflows/cachix.yml index 4aa0b215..13995cb6 100644 --- a/.github/workflows/cachix.yml +++ b/.github/workflows/cachix.yml @@ -21,23 +21,13 @@ jobs: - nix - maximal steps: - - uses: easimon/maximize-build-space@v10 - name: Maximize build space - with: - overprovision-lvm: true - remove-android: true - remove-dotnet: true - remove-haskell: true - remove-codeql: true - - - uses: actions/checkout@v4 + - uses: actions/checkout@v5 name: Checkout - name: Install Nix uses: DeterminateSystems/nix-installer-action@main - - uses: DeterminateSystems/magic-nix-cache-action@main - - uses: cachix/cachix-action@v15 + - uses: cachix/cachix-action@v16 with: authToken: ${{ secrets.CACHIX_TOKEN }} extraPullNames: nix-community diff --git a/.github/workflows/check-docs.yml b/.github/workflows/check-docs.yml deleted file mode 100644 index b543c813..00000000 --- a/.github/workflows/check-docs.yml +++ /dev/null @@ -1,57 +0,0 @@ -name: "Validate flake & check documentation" -on: - pull_request: - workflow_dispatch: - push: - branches: - - main - paths: - - docs/** -jobs: - flake-docs-check: - name: Validate Flake Documentation - runs-on: ubuntu-latest - strategy: - matrix: - package: - - docs - - docs-html - - docs-manpages - - docs-json - steps: - - name: Install Nix - uses: DeterminateSystems/nix-installer-action@main - - uses: DeterminateSystems/magic-nix-cache-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 .#${{ matrix.package }} --print-build-logs - - - name: Get current date - id: get-date - # output format: 2023-12-22-120000 - run: echo "date=$(date +'%Y-%m-%d-%H%M%S')" >> ${GITHUB_OUTPUT} - - - name: Upload doc artifacts - uses: actions/upload-artifact@v4 - 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 diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 8101b8b1..331048b6 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -1,4 +1,6 @@ -name: "Validate flake & check formatting" +name: "Treewide Checks" +permissions: read-all + on: pull_request: workflow_dispatch: @@ -6,33 +8,158 @@ on: branches: - main paths-ignore: - - .github/** - assets/** - - .gitignore + jobs: nix-flake-check: - name: Validate Flake + name: "Validate flake" runs-on: ubuntu-latest + if: "!contains(github.event.pull_request.title, '[skip ci]')" steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Install Nix uses: DeterminateSystems/nix-installer-action@main - - uses: DeterminateSystems/magic-nix-cache-action@main - name: Check Flake run: nix flake check format-with-alejandra: - name: Formatting via Alejandra + name: "Check formatting" runs-on: ubuntu-latest + if: "!contains(github.event.pull_request.title, '[skip ci]')" steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Install Nix uses: DeterminateSystems/nix-installer-action@main - - uses: DeterminateSystems/magic-nix-cache-action@main - - run: nix run nixpkgs#alejandra -- -c . + - name: Check formatting via Alejandra + run: nix run nixpkgs#alejandra -- --check . --exclude npins + + - name: Check formatting via Deno + run: nix run nixpkgs#deno -- fmt --check --ext md **/*.md + + - if: ${{ failure() }} + shell: bash + run: | + echo "::error:: Current codebase contains formatting errors that were caught by the CI!" + echo "Please ensure that all Nix code is formatted with Alejandra, and Markdown with `deno fmt" + echo "[skip ci] label may be added to the PR title if this is a one-time issue and is safe to ignore" + exit 1 + + check-typos: + name: "Check source tree for typos" + runs-on: ubuntu-latest + if: "!contains(github.event.pull_request.title, '[skip ci]')" + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Check for typos + uses: crate-ci/typos@master + with: + config: .github/typos.toml + + - 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 added to the PR title if this is a one-time issue and is safe to ignore" + exit 1 + + flake-docs-check: + name: "Validate documentation builds" + runs-on: ubuntu-latest + if: "!contains(github.event.pull_request.title, '[skip ci]')" + strategy: + matrix: + package: + - docs + - docs-html + - docs-manpages + - docs-json + steps: + - name: Install Nix + uses: DeterminateSystems/nix-installer-action@main + + - name: Checkout + uses: actions/checkout@v5 + + - name: Set default git branch (to reduce log spam) + run: git config --global init.defaultBranch main + + - name: Build documentation packages + run: nix build .#${{ matrix.package }} --print-build-logs + + - name: Get current date + id: get-date + # output format: 2023-12-22-120000 + run: echo "date=$(date +'%Y-%m-%d-%H%M%S')" >> ${GITHUB_OUTPUT} + + - name: Upload doc artifacts + uses: actions/upload-artifact@v4 + with: + name: "${{ matrix.package }}" + path: result/share/doc/nvf + + flake-docs-linkcheck: + name: "Validate hyperlinks in documentation sources" + runs-on: ubuntu-latest + if: "!contains(github.event.pull_request.title, '[skip ci]')" + steps: + - name: Install Nix + uses: DeterminateSystems/nix-installer-action@main + + - name: Checkout + uses: actions/checkout@v5 + + - name: Build linkcheck package + run: nix build .#docs-linkcheck -Lv + + check-editorconfig: + name: "Validate Editorconfig conformance" + runs-on: ubuntu-latest + if: "!contains(github.event.pull_request.title, '[skip ci]')" + steps: + - name: Checkout + uses: actions/checkout@v5 + with: + fetch-depth: 2 # slows down checkout, but we need to compare against the previous commit on push events + + - name: Get list of changed files from PR + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + shell: bash + run: | + if [[ "${{ github.event_name }}" == "pull_request" ]]; then + gh api repos/${{ github.repository }}/pulls/${{ github.event.number }}/files --paginate \ + | jq -r '.[] | select(.status != "removed") | .filename' \ + > "$HOME/changed_files" + else + git diff --name-only HEAD^ > "$HOME/changed_files" + fi + + - name: Print list of changed files + run: | + cat "$HOME/changed_files" + + - name: Install Nix + uses: DeterminateSystems/nix-installer-action@main + + - name: Checking Editorconfig conformance + shell: bash + run: | + < "$HOME/changed_files" nix-shell -p editorconfig-checker \ + --run 'xargs -r editorconfig-checker -disable-indent-size --exclude flake.lock' + + - if: ${{ failure() }} + shell: bash + run: | + echo "::error:: Current formatting does not fit convention provided by .editorconfig located in the project root." + echo "Please make sure your editor properly integrates editorconfig, Neovim does so by default." + echo "See https://editorconfig.org/#download on how to integrate Editorconfig to your editor." + exit 1 diff --git a/.github/workflows/cleanup.yml b/.github/workflows/cleanup.yml index 204dcba7..1ed6a1ec 100644 --- a/.github/workflows/cleanup.yml +++ b/.github/workflows/cleanup.yml @@ -1,19 +1,23 @@ -name: Cleanup +name: Delete Stale Branches +permissions: + contents: write + on: workflow_dispatch: schedule: - cron: "0 4 1 * *" # 4AM on 1st of every month - cron: "0 4 15 * *" # 4AM on the 15th of every month + jobs: branches: name: Cleanup old branches runs-on: ubuntu-latest steps: - name: "Checkout" - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: "Delete old branches" - uses: beatlabs/delete-old-branches-action@v0.0.10 + uses: beatlabs/delete-old-branches-action@v0.0.11 with: repo_token: "${{ secrets.GITHUB_TOKEN }}" date: "1 months ago" diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml index e6d2e662..444e87d6 100644 --- a/.github/workflows/docs-preview.yml +++ b/.github/workflows/docs-preview.yml @@ -9,7 +9,7 @@ on: - "modules/**" - "docs/**" -# Defining permissions here passes it to all workflows. +# Defining permissions here passes it to all jobs. # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token permissions: contents: write @@ -26,16 +26,15 @@ jobs: steps: - name: Install Nix uses: DeterminateSystems/nix-installer-action@main - - uses: DeterminateSystems/magic-nix-cache-action@main - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - 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 + run: nix build .#docs-html --print-build-logs || exit 1 - name: Deploy to GitHub Pages preview run: | @@ -128,7 +127,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Delete preview for closed/merged PR run: | @@ -165,7 +164,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Double check preview directory deletion run: | diff --git a/.github/workflows/editorconfig.yml b/.github/workflows/editorconfig.yml deleted file mode 100644 index d411c89f..00000000 --- a/.github/workflows/editorconfig.yml +++ /dev/null @@ -1,47 +0,0 @@ -name: "Check validity of .editorconfig" - -permissions: read-all - -on: - pull_request: - -jobs: - check-editorconfig: - runs-on: ubuntu-latest - if: "!contains(github.event.pull_request.title, '[skip ci]')" - steps: - - name: Get list of changed files from PR - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - gh api \ - repos/notashelf/nvf/pulls/${{github.event.number}}/files --paginate \ - | jq '.[] | select(.status != "removed") | .filename' \ - > "$HOME/changed_files" - - - name: Print list of changed files - run: | - cat "$HOME/changed_files" - - - name: Checkout - uses: actions/checkout@v4 - with: - ref: refs/pull/${{ github.event.pull_request.number }}/merge - - - name: Install Nix - uses: DeterminateSystems/nix-installer-action@main - - uses: DeterminateSystems/magic-nix-cache-action@main - - - name: Checking EditorConfig - shell: bash - run: | - cat "$HOME/changed_files" | nix-shell -p editorconfig-checker.out --run 'xargs -r editorconfig-checker -disable-indentation -exclude flake.lock --verbose' - echo -n "Check status: $?" - - - name: Fail Gracefully - if: ${{ failure() }} - shell: bash - run: | - echo "::error:: Current formatting does not fit convention provided by .editorconfig located in the project root." - echo "Please make sure your editor properly integrates editorconfig. See https://editorconfig.org/#download for more." - exit 1 diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml new file mode 100644 index 00000000..b24c00aa --- /dev/null +++ b/.github/workflows/labeler.yml @@ -0,0 +1,21 @@ +name: "Label PR" + +on: + pull_request_target: + types: [edited, opened, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + +jobs: + labels: + name: "Label PR" + runs-on: ubuntu-latest + if: "!contains(github.event.pull_request.title, '[skip ci]')" + steps: + - uses: actions/labeler@v6 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + configuration-path: .github/labels.yml + sync-labels: true diff --git a/.github/workflows/manual.yml b/.github/workflows/manual.yml index 5b66c8a6..3b4cc38b 100644 --- a/.github/workflows/manual.yml +++ b/.github/workflows/manual.yml @@ -28,7 +28,7 @@ jobs: outputs: should_run: ${{ steps.should_run.outputs.should_run }} steps: - - uses: actions/checkout@v4.1.7 + - uses: actions/checkout@v5 - name: print latest_commit run: echo ${{ github.sha }} @@ -43,9 +43,8 @@ jobs: if: ${{ needs.check_date.outputs.should_run != 'false' }} runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4.1.7 + - uses: actions/checkout@v5 - 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/.github/workflows/typos.yml b/.github/workflows/typos.yml deleted file mode 100644 index d74ee5b7..00000000 --- a/.github/workflows/typos.yml +++ /dev/null @@ -1,30 +0,0 @@ -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 diff --git a/.github/README.md b/README.md similarity index 61% rename from .github/README.md rename to README.md index 9a059419..7786636a 100644 --- a/.github/README.md +++ b/README.md @@ -1,5 +1,6 @@ +
- nvf Logo + nvf Logo

nvf

@@ -46,7 +47,7 @@ [Features]: #features [Get Started]: #get-started [Documentation]: #documentation -[Help]: #help +[Help]: #getting-help [Contribute]: #contributing [FAQ]: #frequently-asked-questions [Credits]: #credits @@ -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,32 @@ 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. + - Any and all 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 [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 @@ -96,7 +122,7 @@ the following in order to take **nvf** out for a spin. ```bash # Run the default package -nix run github:notashelf/nvf +$ nix run github:notashelf/nvf ``` This will get you a feel for the base configuration and UI design. Though, none @@ -104,20 +130,25 @@ of the configuration options are final as **nvf** is designed to be modular and configurable. > [!TIP] -> The flake exposes `#nix` as the default package, providing minimal language -> support and various utilities. You may also use the `#nix` or `#maximal` -> packages provided by the this flake to get try out different configurations. +> The flake exposes `nix` as the default package, which will be evaluated when +> you run `nix build` or `nix run` on this repo. It is minimal, and providing +> limited language support and various utilities. We also expose the `maximal` +> package, which you may choose to build if you'd like to see more of nvf's +> built-in modules. Please keep in mind that those are demo packages, nvf does +> not ship a default configuration if installed as a NixOS/Home-Manager module +> or via standalone method. -It is as simple as changing the target output to get a different configuration. -For example, to get a configuration with large language coverage, run: +It is as simple as changing the target output in your `nix run` command to get a +different configuration. For example, to get a configuration with large language +coverage, run: ```bash # Run the maximal package -nix run github:notashelf/nvf#maximal +$ nix run github:notashelf/nvf#maximal ``` Similar instructions will apply for `nix profile install`. However, you are -recommended to instead use the module system as described in the manual. +recommended to instead use the module system as described in the [nvf manual]. > [!NOTE] > The `maximal` configuration is quite large, and might take a while to build. @@ -130,6 +161,10 @@ instructions. ## Documentation +**nvf** prides itself in its rich, intuitive documentation. The chapter below +covers several methods through which you can install **nvf**. If you believe +something is missing, or could be done better, please feel free to contact us! + ### Installation The _recommended_ way of installing nvf is using either the NixOS or the @@ -138,7 +173,7 @@ install **nvf** as a standalone package, or a flake output. See the rendered [nvf manual] for detailed and up-to-date installation guides, configurations, available options, release notes and more. Tips for installing -userspace plugins is also contained in the documentation. +userspace plugins are also contained in the documentation. > [!TIP] > While using NixOS or Home-Manager modules, @@ -155,16 +190,18 @@ requests are also welcome, and appreciated. 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. +We are not yet on spaces like matrix or IRC, so please use the issue tracker for +now. The [discussions tab] can also be a place to request help from community +members, or engage in productive discussion with the maintainers. ## Contributing +[contributing guide]: .github/CONTRIBUTING.md + I am always looking for new ways to help improve this flake. If you would like -to contribute, please read the [contributing guide](CONTRIBUTING.md) before -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. +to contribute, please read the [contributing guide] before 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. ## Frequently Asked Questions @@ -173,49 +210,64 @@ 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. It has been reported that **Android** is also +supported through the Home-Manager module, or using standalone package. 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. +better prepare for 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.*` options in Nix to +further configure Neovim. ## Credits ### Co-Maintainers -Alongside myself, nvf is developed by those talented folk: +Alongside [myself](https://github.com/notashelf), nvf is developed by those +talented folk. **nvf** would not be what it is today without their invaluable +contributions. - [**@horriblename**](https://github.com/horriblename) - ([Liberapay](https://liberapay.com/horriblename/))- For actively implementing + ([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. +- [**@Soliprem**](https://github.com/soliprem) - For rigorously implementing + missing features and excellent work on new language modules. Please do remember to extend your thanks (financially or otherwise) if this project has been helpful to you. @@ -232,20 +284,20 @@ heart-felt thanks to - [**@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. + possible, great ideas and module additions. - [**@Yavko**](https://github.com/Yavko) - For the amazing **nvf** logo - [**@FrothyMarrow**](https://github.com/FrothyMarrow) - For seeing mistakes - that I could not. + that I could not and contributing good ideas & code. - [**@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. + [mnw], and occasional improvements to the codebase. +- [**@Diniamo**](https://github.com/Diniamo) - For actively submitting pull + requests, issues and assistance with co-maintenance of nvf. 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) @@ -263,7 +315,6 @@ including: I am grateful for their previous work and inspiration, and I wholeheartedly recommend checking their work out. -
## License diff --git a/configuration.nix b/configuration.nix index 2159edc8..68776638 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 = { @@ -14,17 +15,21 @@ isMaximal: { spellcheck = { enable = true; + programmingWordlist.enable = isMaximal; }; lsp = { + # This must be enabled for the language modules to hook into + # the LSP API. + enable = true; + formatOnSave = true; lspkind.enable = false; lightbulb.enable = true; lspsaga.enable = false; trouble.enable = true; - lspSignature.enable = true; + lspSignature.enable = !isMaximal; # conflicts with blink in maximal otter-nvim.enable = isMaximal; - lsplines.enable = isMaximal; nvim-docs-view.enable = isMaximal; }; @@ -38,7 +43,6 @@ isMaximal: { # This section does not include a comprehensive list of available language modules. # To list all available language module options, please visit the nvf manual. languages = { - enableLSP = true; enableFormat = true; enableTreesitter = true; enableExtraDiagnostics = true; @@ -81,6 +85,7 @@ isMaximal: { elixir.enable = false; haskell.enable = false; ruby.enable = false; + fsharp.enable = false; tailwind.enable = false; svelte.enable = false; @@ -123,7 +128,15 @@ isMaximal: { autopairs.nvim-autopairs.enable = true; - autocomplete.nvim-cmp.enable = true; + # nvf provides various autocomplete options. The tried and tested nvim-cmp + # is enabled in default package, because it does not trigger a build. We + # enable blink-cmp in maximal because it needs to build its rust fuzzy + # matcher library. + autocomplete = { + nvim-cmp.enable = !isMaximal; + blink-cmp.enable = isMaximal; + }; + snippets.luasnip.enable = true; filetree = { @@ -149,6 +162,7 @@ isMaximal: { enable = true; gitsigns.enable = true; gitsigns.codeActions.enable = false; # throws an annoying debug message + neogit.enable = isMaximal; }; minimap = { @@ -172,17 +186,24 @@ 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; + smart-splits.enable = isMaximal; + undotree.enable = isMaximal; + nvim-biscuits.enable = isMaximal; + motion = { hop.enable = true; leap.enable = true; precognition.enable = isMaximal; }; - images = { image-nvim.enable = false; + img-clip.enable = isMaximal; }; }; @@ -230,6 +251,8 @@ isMaximal: { enable = false; cmp.enable = isMaximal; }; + codecompanion-nvim.enable = false; + avante-nvim.enable = isMaximal; }; session = { diff --git a/default.nix b/default.nix new file mode 100644 index 00000000..e597b612 --- /dev/null +++ b/default.nix @@ -0,0 +1,15 @@ +(import ( + let + lock = builtins.fromJSON (builtins.readFile ./flake.lock); + inherit (lock.nodes.flake-compat.locked) url rev narHash; + in + builtins.fetchTarball { + url = "${url}/archive/${rev}.tar.gz"; + sha256 = narHash; + } + ) { + src = ./.; + copySourceTreeToStore = false; + useBuiltinsFetchTree = true; + }) +.defaultNix diff --git a/docs/default.nix b/docs/default.nix index 48cff563..49f90b80 100644 --- a/docs/default.nix +++ b/docs/default.nix @@ -12,6 +12,7 @@ inherit ( (lib.evalModules { + specialArgs = {inherit inputs;}; modules = import ../modules/modules.nix { inherit lib pkgs; @@ -95,8 +96,6 @@ inherit (nvimModuleDocs) optionsJSON; }; in { - inherit (inputs) nmd; - # TODO: Use `hmOptionsDocs.optionsJSON` directly once upstream # `nixosOptionsDoc` is more customizable. options.json = 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..95195f78 100644 --- a/docs/manual/configuring.md +++ b/docs/manual/configuring.md @@ -1,10 +1,21 @@ # Configuring nvf {#ch-configuring} +[helpful tips section]: #ch-helpful-tips + +nvf allows for _very_ extensive configuration in Neovim through the Nix module +interface. The below chapters describe several of the options exposed in nvf for +your convenience. You might also be interested in the [helpful tips section] for +more advanced or unusual configuration options supported by nvf. + +Note that this section does not cover module _options_. For an overview of all +module options provided by nvf, please visit the [appendix](/nvf/options.html) + ```{=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 +configuring/autocmds.md ``` diff --git a/docs/manual/configuring/autocmds.md b/docs/manual/configuring/autocmds.md new file mode 100644 index 00000000..e547ace2 --- /dev/null +++ b/docs/manual/configuring/autocmds.md @@ -0,0 +1,119 @@ +# Autocommands and Autogroups {#ch-autocmds-augroups} + +This module allows you to declaratively configure Neovim autocommands and +autogroups within your Nix configuration. + +## Autogroups (`vim.augroups`) {#sec-vim-augroups} + +Autogroups (`augroup`) organize related autocommands. This allows them to be +managed collectively, such as clearing them all at once to prevent duplicates. +Each entry in the list is a submodule with the following options: + +| Option | Type | Default | Description | Example | +| :------- | :----- | :------ | :--------------------------------------------------------------------------------------------------- | :---------------- | +| `enable` | `bool` | `true` | Enables or disables this autogroup definition. | `true` | +| `name` | `str` | _None_ | **Required.** The unique name for the autogroup. | `"MyFormatGroup"` | +| `clear` | `bool` | `true` | Clears any existing autocommands within this group before adding new ones defined in `vim.autocmds`. | `true` | + +**Example:** + +```nix +{ + vim.augroups = [ + { + name = "MyCustomAuGroup"; + clear = true; # Clear previous autocommands in this group on reload + } + { + name = "Formatting"; + # clear defaults to true + } + ]; +} +``` + +## Autocommands (`vim.autocmds`) {#sec-vim-autocmds} + +Autocommands (`autocmd`) trigger actions based on events happening within Neovim +(e.g., saving a file, entering a buffer). Each entry in the list is a submodule +with the following options: + +| Option | Type | Default | Description | Example | +| :--------- | :-------------------- | :------ | :---------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------- | +| `enable` | `bool` | `true` | Enables or disables this autocommand definition. | `true` | +| `event` | `nullOr (listOf str)` | `null` | **Required.** List of Neovim events that trigger this autocommand (e.g., `BufWritePre`, `FileType`). | `[ "BufWritePre" ]` | +| `pattern` | `nullOr (listOf str)` | `null` | List of file patterns (globs) to match against (e.g., `*.py`, `*`). If `null`, matches all files for the given event. | `[ "*.lua", "*.nix" ]` | +| `callback` | `nullOr luaInline` | `null` | A Lua function to execute when the event triggers. Use `lib.generators.mkLuaInline`. **Cannot be used with `command`.** | `lib.generators.mkLuaInline "function() print('File saved!') end"` | +| `command` | `nullOr str` | `null` | A Vimscript command to execute when the event triggers. **Cannot be used with `callback`.** | `"echo 'File saved!'"` | +| `group` | `nullOr str` | `null` | The name of an `augroup` (defined in `vim.augroups`) to associate this autocommand with. | `"MyCustomAuGroup"` | +| `desc` | `nullOr str` | `null` | A description for the autocommand (useful for introspection). | `"Format buffer on save"` | +| `once` | `bool` | `false` | If `true`, the autocommand runs only once and then automatically removes itself. | `false` | +| `nested` | `bool` | `false` | If `true`, allows this autocommand to trigger other autocommands. | `false` | + +:::{.warning} + +You cannot define both `callback` (for Lua functions) and `command` (for +Vimscript) for the same autocommand. Choose one. + +::: + +**Examples:** + +```nix +{ lib, ... }: +{ + vim.augroups = [ { name = "UserSetup"; } ]; + + vim.autocmds = [ + # Example 1: Using a Lua callback + { + event = [ "BufWritePost" ]; + pattern = [ "*.lua" ]; + group = "UserSetup"; + desc = "Notify after saving Lua file"; + callback = lib.generators.mkLuaInline '' + function() + vim.notify("Lua file saved!", vim.log.levels.INFO) + end + ''; + } + + # Example 2: Using a Vim command + { + event = [ "FileType" ]; + pattern = [ "markdown" ]; + group = "UserSetup"; + desc = "Set spellcheck for Markdown"; + command = "setlocal spell"; + } + + # Example 3: Autocommand without a specific group + { + event = [ "BufEnter" ]; + pattern = [ "*.log" ]; + desc = "Disable line numbers in log files"; + command = "setlocal nonumber"; + # No 'group' specified + } + + # Example 4: Using Lua for callback + { + event = [ "BufWinEnter" ]; + pattern = [ "*" ]; + desc = "Simple greeting on entering a buffer window"; + callback = lib.generators.mkLuaInline '' + function(args) + print("Entered buffer: " .. args.buf) + end + ''; + + # Run only once per session trigger + once = true; + } + ]; +} +``` + +These definitions are automatically translated into the necessary Lua code to +configure `vim.api.nvim_create_augroup` and `vim.api.nvim_create_autocmd` when +Neovim starts. 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/custom-package.md b/docs/manual/configuring/custom-package.md index 51d996b6..3e9e324a 100644 --- a/docs/manual/configuring/custom-package.md +++ b/docs/manual/configuring/custom-package.md @@ -1,12 +1,12 @@ # Custom Neovim Package {#ch-custom-package} As of v0.5, you may now specify the Neovim package that will be wrapped with -your configuration. This is done with the `vim.package` option. +your configuration. This is done with the [](#opt-vim.package) option. ```nix {inputs, pkgs, ...}: { # using the neovim-nightly overlay - vim.package = inputs.neovim-overlay.packages.${pkgs.system}.neovim; + vim.package = inputs.neovim-overlay.packages.${pkgs.stdenv.system}.neovim; } ``` diff --git a/docs/manual/configuring/custom-plugins.md b/docs/manual/configuring/custom-plugins.md index 79a691e2..bf986a0f 100644 --- a/docs/manual/configuring/custom-plugins.md +++ b/docs/manual/configuring/custom-plugins.md @@ -1,22 +1,33 @@ # Custom Plugins {#ch-custom-plugins} -**nvf**, by default, exposes a wide variety of plugins as module options for -your convenience and bundles necessary dependencies into **nvf**'s runtime. In -case a plugin is not available in **nvf**, you may consider making a pull -request to **nvf** to include it as a module or you may add it to your -configuration locally. +**nvf** exposes a very wide variety of plugins by default, which are consumed by +module options. This is done for your convenience, and to bundle all necessary +dependencies into **nvf**'s runtime with full control of versioning, testing and +dependencies. In the case a plugin you need is _not_ available, you may consider +making a pull request to add the package you're looking for, or you may add it +to your configuration locally. The below section describes how new plugins may +be added to the user's configuration. ## Adding Plugins {#ch-adding-plugins} -There are multiple ways of adding custom plugins to your **nvf** configuration. +Per **nvf**'s design choices, there are several ways of adding custom plugins to +your configuration as you need them. As we aim for extensive configuration, it +is possible to add custom plugins (from nixpkgs, pinning tools, flake inputs, +etc.) to your Neovim configuration before they are even implemented in **nvf** +as a module. -You can use custom plugins, before they are implemented in the flake. To add a -plugin to the runtime, you need to add it to the [](#opt-vim.startPlugins) list -in your configuration. +:::{.info} -Adding a plugin to `startPlugins` will not allow you to configure the plugin -that you have added, but **nvf** provides multiple way of configuring any custom -plugins that you might have added to your configuration. +To add a plugin to your runtime, you will need to add it to +[](#opt-vim.startPlugins) list in your configuration. This is akin to cloning a +plugin to `~/.config/nvim`, but they are only ever placed in the Nix store and +never exposed to the outside world for purity and full isolation. + +::: + +As you would configure a cloned plugin, you must configure the new plugins that +you've added to `startPlugins.` **nvf** provides multiple ways of configuring +any custom plugins that you might have added to your configuration. ```{=include=} sections custom-plugins/configuring.md diff --git a/docs/manual/configuring/custom-plugins/configuring.md b/docs/manual/configuring/custom-plugins/configuring.md index c0935f03..a4b3ce19 100644 --- a/docs/manual/configuring/custom-plugins/configuring.md +++ b/docs/manual/configuring/custom-plugins/configuring.md @@ -1,13 +1,20 @@ # Configuring {#sec-configuring-plugins} Just making the plugin to your Neovim configuration available might not always -be enough. In that case, you can write custom lua config using either -`config.vim.lazy.plugins.*.setupOpts` `config.vim.extraPlugins.*.setup` or -`config.vim.luaConfigRC`. +be enough., for example, if the plugin requires a setup table. In that case, you +can write custom Lua configuration using one of -The first option uses an extended version of `lz.n`'s PluginSpec. `setupModule` -and `setupOpt` can be used if the plugin uses a `require('module').setup(...)` -pattern. Otherwise, the `before` and `after` hooks should do what you need. +- `config.vim.lazy.plugins.*.setupOpts` +- `config.vim.extraPlugins.*.setup` +- `config.vim.luaConfigRC`. + +## Lazy Plugins {#ch-vim-lazy-plugins} + +`config.vim.lazy.plugins.*.setupOpts` is useful for lazy-loading plugins, and +uses an extended version of `lz.n's` `PluginSpec` to expose a familiar +interface. `setupModule` and `setupOpt` can be used if the plugin uses a +`require('module').setup(...)` pattern. Otherwise, the `before` and `after` +hooks should do what you need. ```nix { @@ -25,50 +32,61 @@ pattern. Otherwise, the `before` and `after` hooks should do what you need. } ``` -The second option uses an attribute set, which maps DAG section names to a +## Standard API {#ch-vim-extra-plugins} + +`vim.extraPlugins` uses an attribute set, which maps DAG section names to a custom type, which has the fields `package`, `after`, `setup`. They allow you to set the package of the plugin, the sections its setup code should be after (note that the `extraPlugins` option has its own DAG scope), and the its setup code respectively. For example: ```nix -config.vim.extraPlugins = with pkgs.vimPlugins; { - aerial = { - package = aerial-nvim; - setup = "require('aerial').setup {}"; - }; +{pkgs, ...}: { + config.vim.extraPlugins = { + aerial = { + package = pkgs.vimPlugins.aerial-nvim; + setup = "require('aerial').setup {}"; + }; - harpoon = { - package = harpoon; - setup = "require('harpoon').setup {}"; - after = ["aerial"]; # place harpoon configuration after aerial + harpoon = { + package = pkgs.vimPlugins.harpoon; + setup = "require('harpoon').setup {}"; + after = ["aerial"]; # place harpoon configuration after aerial + }; }; } ``` -The third option also uses an attribute set, but this one is resolved as a DAG +### Setup using luaConfigRC {#setup-using-luaconfigrc} + +`vim.luaConfigRC` also uses an attribute set, but this one is resolved as a DAG directly. The attribute names denote the section names, and the values lua code. For example: ```nix { - # this will create an "aquarium" section in your init.lua with the contents of your custom config - # which will be *appended* to the rest of your configuration, inside your init.vim + # This will create a section called "aquarium" in the 'init.lua' with the + # contents of your custom configuration. By default 'entryAnywhere' is implied + # in DAGs, so this will be inserted to an arbitrary position. In the case you + # wish to control the position of this section with more precision, please + # look into the DAGs section of the manual. config.vim.luaConfigRC.aquarium = "vim.cmd('colorscheme aquiarum')"; } ``` +[DAG system]: #ch-using-dags +[DAG section]: #ch-dag-entries ::: {.note} -One of the greatest strengths of nvf is the ability to order -snippets of configuration via the DAG system. It will allow specifying positions -of individual sections of configuration as needed. nvf provides helper functions +One of the **greatest strengths** of **nvf** is the ability to order +configuration snippets precisely using the [DAG system]. DAGs +are a very powerful mechanism that allows specifying positions +of individual sections of configuration as needed. We provide helper functions in the extended library, usually under `inputs.nvf.lib.nvim.dag` that you may use. -Please refer to the [DAG section](/index.xhtml#ch-dag-entries) in the nvf manual +Please refer to the [DAG section] in the nvf manual to find out more about the DAG system. ::: - diff --git a/docs/manual/configuring/custom-plugins/lazy-method.md b/docs/manual/configuring/custom-plugins/lazy-method.md index c6fd7106..c16966b8 100644 --- a/docs/manual/configuring/custom-plugins/lazy-method.md +++ b/docs/manual/configuring/custom-plugins/lazy-method.md @@ -1,7 +1,8 @@ # Lazy Method {#sec-lazy-method} -As of version **0.7**, we exposed an API for configuring lazy-loaded plugins via -`lz.n` and `lzn-auto-require`. +As of version **0.7**, an API is exposed to allow configuring lazy-loaded +plugins via `lz.n` and `lzn-auto-require`. Below is a comprehensive example of +how it may be loaded to lazy-load an arbitrary plugin. ```nix { @@ -38,3 +39,24 @@ As of version **0.7**, we exposed an API for configuring lazy-loaded plugins via }; } ``` + +## LazyFile event {#sec-lazyfile-event} + +**nvf** re-implements `LazyFile` as a familiar user event to load a plugin when +a file is opened: + +```nix +{ + config.vim.lazy.plugins = { + "aerial.nvim" = { + package = pkgs.vimPlugins.aerial-nvim; + event = [{event = "User"; pattern = "LazyFile";}]; + # ... + }; + }; +} +``` + +You can consider the `LazyFile` event as an alias to the combination of +`"BufReadPost"`, `"BufNewFile"` and `"BufWritePre"`, i.e., a list containing all +three of those events: `["BufReadPost" "BufNewFile" "BufWritePre"]` diff --git a/docs/manual/configuring/custom-plugins/legacy-method.md b/docs/manual/configuring/custom-plugins/legacy-method.md index b2bddf43..6c399aaf 100644 --- a/docs/manual/configuring/custom-plugins/legacy-method.md +++ b/docs/manual/configuring/custom-plugins/legacy-method.md @@ -1,26 +1,31 @@ # Legacy Method {#sec-legacy-method} -Prior to version v0.5, the method of adding new plugins was adding the plugin -package to `vim.startPlugins` and add its configuration as a DAG under one of -`vim.configRC` or `vim.luaConfigRC`. Users who have not yet updated to 0.5, or -prefer a more hands-on approach may use the old method where the load order of -the plugins is determined by DAGs. +Prior to version **0.5**, the method of adding new plugins was adding the plugin +package to [](#opt-vim.startPlugins) and adding its configuration as a DAG under +one of `vim.configRC` or [](#opt-vim.luaConfigRC). While `configRC` has been +deprecated, users who have not yet updated to 0.5 or those who prefer a more +hands-on approach may choose to use the old method where the load order of the +plugins is explicitly determined by DAGs without internal abstractions. -## Adding plugins {#sec-adding-plugins} +## Adding New Plugins {#sec-adding-new-plugins} -To add a plugin not available in nvf as a module to your configuration, you may -add it to [](#opt-vim.startPlugins) in order to make it available to Neovim at -runtime. +To add a plugin not available in **nvf** as a module to your configuration using +the legacy method, you must add it to [](#opt-vim.startPlugins) in order to make +it available to Neovim at runtime. ```nix {pkgs, ...}: { # Add a Neovim plugin from Nixpkgs to the runtime. + # This does not need to come explicitly from packages. 'vim.startPlugins' + # takes a list of *string* (to load internal plugins) or *package* to load + # a Neovim package from any source. vim.startPlugins = [pkgs.vimPlugins.aerial-nvim]; } ``` -And to configure the added plugin, you can use the `luaConfigRC` option to -provide configuration as a DAG using the **nvf** extended library. +Once the package is available in Neovim's runtime, you may use the `luaConfigRC` +option to provide configuration as a DAG using the **nvf** extended library in +order to configure the added plugin, ```nix {inputs, ...}: let @@ -29,6 +34,8 @@ provide configuration as a DAG using the **nvf** extended library. # to specialArgs, the 'inputs' prefix may be omitted. inherit (inputs.nvf.lib.nvim.dag) entryAnywhere; in { + # luaConfigRC takes Lua configuration verbatim and inserts it at an arbitrary + # position by default or if 'entryAnywhere' is used. vim.luaConfigRC.aerial-nvim= entryAnywhere '' require('aerial').setup { -- your configuration here diff --git a/docs/manual/configuring/custom-plugins/non-lazy-method.md b/docs/manual/configuring/custom-plugins/non-lazy-method.md index 351af2eb..24ef7688 100644 --- a/docs/manual/configuring/custom-plugins/non-lazy-method.md +++ b/docs/manual/configuring/custom-plugins/non-lazy-method.md @@ -1,14 +1,15 @@ # Non-lazy Method {#sec-non-lazy-method} -As of version **0.5**, we have a more extensive API for configuring plugins, -under `vim.extraPlugins`. Instead of using DAGs exposed by the library, you may -use the extra plugin module as follows: +As of version **0.5**, we have a more extensive API for configuring plugins that +should be preferred over the legacy method. This API is available as +[](#opt-vim.extraPlugins). Instead of using DAGs exposed by the library +_directly_, you may use the extra plugin module as follows: ```nix -{ - config.vim.extraPlugins = with pkgs.vimPlugins; { +{pkgs, ...}: { + config.vim.extraPlugins = { aerial = { - package = aerial-nvim; + package = pkgs.vimPlugins.aerial-nvim; setup = '' require('aerial').setup { -- some lua configuration here @@ -17,10 +18,12 @@ use the extra plugin module as follows: }; harpoon = { - package = harpoon; + package = pkgs.vimPlugins.harpoon; setup = "require('harpoon').setup {}"; after = ["aerial"]; }; }; } ``` + +This provides a level of abstraction over the DAG system for faster iteration. diff --git a/docs/manual/configuring/dags.md b/docs/manual/configuring/dags.md index 34351826..08e82bab 100644 --- a/docs/manual/configuring/dags.md +++ b/docs/manual/configuring/dags.md @@ -14,14 +14,17 @@ explains in more detail the overall usage logic of the DAG type. ## entryAnywhere {#sec-types-dag-entryAnywhere} -> `lib.dag.entryAnywhere (value: T) : DagEntry` +> `nvf.lib.nvim.dag.entryAnywhere (value: T) : DagEntry` Indicates that `value` can be placed anywhere within the DAG. This is also the default for plain attribute set entries, that is ```nix +# For 'nvf' to be available in module's arguments, +# it needs to be inherited from imports in the modules array as: +# modules = [{ _module.args = { inherit nvf; }; } ...]; foo.bar = { - a = lib.dag.entryAnywhere 0; + a = nvf.lib.nvim.dag.entryAnywhere 0; } ``` @@ -37,7 +40,7 @@ are equivalent. ## entryAfter {#ch-types-dag-entryAfter} -> `lib.dag.entryAfter (afters: list string) (value: T) : DagEntry` +> `nvf.lib.nvim.dag.entryAfter (afters: list string) (value: T) : DagEntry` Indicates that `value` must be placed _after_ each of the attribute names in the given list. For example @@ -45,7 +48,7 @@ given list. For example ```nix foo.bar = { a = 0; - b = lib.dag.entryAfter [ "a" ] 1; + b = nvf.lib.nvim.dag.entryAfter [ "a" ] 1; } ``` @@ -53,14 +56,14 @@ would place `b` after `a` in the graph. ## entryBefore {#ch-types-dag-entryBefore} -> `lib.dag.entryBefore (befores: list string) (value: T) : DagEntry` +> `nvf.lib.nvim.dag.entryBefore (befores: list string) (value: T) : DagEntry` Indicates that `value` must be placed _before_ each of the attribute names in the given list. For example ```nix foo.bar = { - b = lib.dag.entryBefore [ "a" ] 1; + b = nvf.lib.nvim.dag.entryBefore [ "a" ] 1; a = 0; } ``` @@ -69,7 +72,7 @@ would place `b` before `a` in the graph. ## entryBetween {#sec-types-dag-entryBetween} -> `lib.dag.entryBetween (befores: list string) (afters: list string) (value: T) : DagEntry` +> `nvf.lib.nvim.dag.entryBetween (befores: list string) (afters: list string) (value: T) : DagEntry` Indicates that `value` must be placed _before_ the attribute names in the first list and _after_ the attribute names in the second list. For example @@ -77,7 +80,7 @@ list and _after_ the attribute names in the second list. For example ```nix foo.bar = { a = 0; - c = lib.dag.entryBetween [ "b" ] [ "a" ] 2; + c = nvf.lib.nvim.dag.entryBetween [ "b" ] [ "a" ] 2; b = 1; } ``` @@ -92,13 +95,13 @@ functions take a `tag` as argument and the DAG entries will be named ## entriesAnywhere {#sec-types-dag-entriesAnywhere} -> `lib.dag.entriesAnywhere (tag: string) (values: [T]) : Dag` +> `nvf.lib.nvim.dag.entriesAnywhere (tag: string) (values: [T]) : Dag` Creates a DAG with the given values with each entry labeled using the given tag. For example ```nix -foo.bar = lib.dag.entriesAnywhere "a" [ 0 1 ]; +foo.bar = nvf.lib.nvim.dag.entriesAnywhere "a" [ 0 1 ]; ``` is equivalent to @@ -106,13 +109,13 @@ is equivalent to ```nix foo.bar = { a-0 = 0; - a-1 = lib.dag.entryAfter [ "a-0" ] 1; + a-1 = nvf.lib.nvim.dag.entryAfter [ "a-0" ] 1; } ``` ## entriesAfter {#sec-types-dag-entriesAfter} -> `lib.dag.entriesAfter (tag: string) (afters: list string) (values: [T]) : Dag` +> `nvf.lib.nvim.dag.entriesAfter (tag: string) (afters: list string) (values: [T]) : Dag` Creates a DAG with the given values with each entry labeled using the given tag. The list of values are placed are placed _after_ each of the attribute names in @@ -120,7 +123,7 @@ The list of values are placed are placed _after_ each of the attribute names in ```nix foo.bar = - { b = 0; } // lib.dag.entriesAfter "a" [ "b" ] [ 1 2 ]; + { b = 0; } // nvf.lib.nvim.dag.entriesAfter "a" [ "b" ] [ 1 2 ]; ``` is equivalent to @@ -128,14 +131,14 @@ is equivalent to ```nix foo.bar = { b = 0; - a-0 = lib.dag.entryAfter [ "b" ] 1; - a-1 = lib.dag.entryAfter [ "a-0" ] 2; + a-0 = nvf.lib.nvim.dag.entryAfter [ "b" ] 1; + a-1 = nvf.lib.nvim.dag.entryAfter [ "a-0" ] 2; } ``` ## entriesBefore {#sec-types-dag-entriesBefore} -> `lib.dag.entriesBefore (tag: string) (befores: list string) (values: [T]) : Dag` +> `nvf.lib.nvim.dag.entriesBefore (tag: string) (befores: list string) (values: [T]) : Dag` Creates a DAG with the given values with each entry labeled using the given tag. The list of values are placed _before_ each of the attribute names in `befores`. @@ -143,7 +146,7 @@ For example ```nix foo.bar = - { b = 0; } // lib.dag.entriesBefore "a" [ "b" ] [ 1 2 ]; + { b = 0; } // nvf.lib.nvim.dag.entriesBefore "a" [ "b" ] [ 1 2 ]; ``` is equivalent to @@ -152,13 +155,13 @@ is equivalent to foo.bar = { b = 0; a-0 = 1; - a-1 = lib.dag.entryBetween [ "b" ] [ "a-0" ] 2; + a-1 = nvf.lib.nvim.dag.entryBetween [ "b" ] [ "a-0" ] 2; } ``` ## entriesBetween {#sec-types-dag-entriesBetween} -> `lib.dag.entriesBetween (tag: string) (befores: list string) (afters: list string) (values: [T]) : Dag` +> `nvf.lib.nvim.dag.entriesBetween (tag: string) (befores: list string) (afters: list string) (values: [T]) : Dag` Creates a DAG with the given values with each entry labeled using the given tag. The list of values are placed _before_ each of the attribute names in `befores` @@ -166,7 +169,7 @@ and _after_ each of the attribute names in `afters`. For example ```nix foo.bar = - { b = 0; c = 3; } // lib.dag.entriesBetween "a" [ "b" ] [ "c" ] [ 1 2 ]; + { b = 0; c = 3; } // nvf.lib.nvim.dag.entriesBetween "a" [ "b" ] [ "c" ] [ 1 2 ]; ``` is equivalent to @@ -175,7 +178,7 @@ is equivalent to foo.bar = { b = 0; c = 3; - a-0 = lib.dag.entryAfter [ "c" ] 1; - a-1 = lib.dag.entryBetween [ "b" ] [ "a-0" ] 2; + a-0 = nvf.lib.nvim.dag.entryAfter [ "c" ] 1; + a-1 = nvf.lib.nvim.dag.entryBetween [ "b" ] [ "a-0" ] 2; } ``` diff --git a/docs/manual/configuring/languages.md b/docs/manual/configuring/languages.md index 74714365..252163fb 100644 --- a/docs/manual/configuring/languages.md +++ b/docs/manual/configuring/languages.md @@ -19,6 +19,7 @@ formatting to diagnostics. The following languages have sections under the - Go: [vim.languages.go.enable](#opt-vim.languages.go.enable) - Lua: [vim.languages.lua.enable](#opt-vim.languages.lua.enable) - PHP: [vim.languages.php.enable](#opt-vim.languages.php.enable) +- F#: [vim.languages.fsharp.enable](#opt-vim.languages.fsharp.enable) Adding support for more languages, and improving support for existing ones are great places where you can contribute with a PR. diff --git a/docs/manual/configuring/languages/lsp.md b/docs/manual/configuring/languages/lsp.md index 6d6ed5bc..2ddc08b5 100644 --- a/docs/manual/configuring/languages/lsp.md +++ b/docs/manual/configuring/languages/lsp.md @@ -1,17 +1,22 @@ # LSP Custom Packages/Command {#sec-languages-custom-lsp-packages} -In any of the `opt.languages..lsp.package` options you can provide -your own LSP package, or provide the command to launch the language server, as a -list of strings. You can use this to skip automatic installation of a language -server, and instead use the one found in your `$PATH` during runtime, for -example: +One of the strengths of **nvf** is convenient aliases to quickly configure LSP +servers through the Nix module system. By default the LSP packages for relevant +language modules will be pulled into the closure. If this is not desirable, you +may provide **a custom LSP package** (e.g., a Bash script that calls a command) +or **a list of strings** to be interpreted as the command to launch the language +server. By using a list of strings, you can use this to skip automatic +installation of a language server, and instead use the one found in your `$PATH` +during runtime, for example: ```nix vim.languages.java = { lsp = { enable = true; - # this expects jdt-language-server to be in your PATH - # or in `vim.extraPackages` + + # This expects 'jdt-language-server' to be in your PATH or in + # 'vim.extraPackages.' There are no additional checks performed to see + # if the command provided is valid. package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"]; }; } diff --git a/docs/manual/configuring/overriding-plugins.md b/docs/manual/configuring/overriding-plugins.md new file mode 100644 index 00000000..25a71559 --- /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/default-configs.md b/docs/manual/default-configs.md deleted file mode 100644 index 96ffa81a..00000000 --- a/docs/manual/default-configs.md +++ /dev/null @@ -1,10 +0,0 @@ -# Default Configs {#ch-default-configs} - -While you can configure **nvf** yourself using the builder, you can also use the -pre-built configs that are available. Here are a few default configurations you -can use. - -```{=include=} chapters -default-configs/maximal.md -default-configs/nix.md -``` diff --git a/docs/manual/default-configs/maximal.md b/docs/manual/default-configs/maximal.md deleted file mode 100644 index 36887633..00000000 --- a/docs/manual/default-configs/maximal.md +++ /dev/null @@ -1,11 +0,0 @@ -# Maximal {#sec-default-maximal} - -```bash -$ nix shell github:notashelf/nvf#maximal test.nix -``` - -It is the same fully configured Neovim as with the [Nix](#sec-default-nix) -configuration, but with every supported language enabled. - -::: {.note} Running the maximal config will download _a lot_ of packages as it -is downloading language servers, formatters, and more. ::: diff --git a/docs/manual/default-configs/nix.md b/docs/manual/default-configs/nix.md deleted file mode 100644 index 5210ef39..00000000 --- a/docs/manual/default-configs/nix.md +++ /dev/null @@ -1,9 +0,0 @@ -# Nix {#sec-default-nix} - -```bash -$ nix run github:notashelf/nvf#nix test.nix -``` - -Enables all the of Neovim plugins, with language support for specifically Nix. -This lets you see what a fully configured neovim setup looks like without -downloading a whole bunch of language servers and associated tools. diff --git a/docs/manual/hacking/additional-plugins.md b/docs/manual/hacking/additional-plugins.md index e67fa96b..1f7ba778 100644 --- a/docs/manual/hacking/additional-plugins.md +++ b/docs/manual/hacking/additional-plugins.md @@ -1,36 +1,92 @@ # 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-` +There are two methods for adding new Neovim plugins to **nvf**. npins is the +faster option that should be preferred if the plugin consists of pure Lua or +Vimscript code. In which case there is no building required, and we can easily +handle the copying of plugin files. Alternative method, which is required when +plugins try to build their own libraries (e.g., in Rust or C) that need to be +built with Nix to function correctly. + +## With npins {#sec-npins-for-plugins} + +npins is the standard method of adding new plugins to **nvf**. You simply need +the repository URL for the plugin, and can add it as a source to be built +automatically with one command. To add a new Neovim plugin, use `npins`. For +example: + +```bash +nix-shell -p npins # or nix shell nixpkgs#npins if using flakes +``` + +Then run: + +```bash +npins add --name github -b +``` + +::: {.note} + +Be sure to replace any non-alphanumeric characters with `-` for `--name`. For +example + +```bash +npins add --name lazydev-nvim github folke lazydev.nvim -b main +``` + +::: + +Once the `npins` command is done, you can start referencing the plugin as a +**string**. ```nix { - inputs = { - # ... - plugin-neodev-nvim = { - url = "github:folke/neodev.nvim"; - flake = false; - }; - # ... - }; + config.vim.startPlugins = ["lazydev-nvim"]; } ``` -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` +## Packaging Complex Plugins {#sec-pkgs-for-plugins} -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` +[blink.cmp]: https://github.com/Saghen/blink.cmp -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**. +Some plugins require additional packages to be built and substituted to function +correctly. For example [blink.cmp] requires its own fuzzy matcher library, built +with Rust, to be installed or else defaults to a much slower Lua implementation. +In the Blink documentation, you are advised to build with `cargo` but that is +not ideal since we are leveraging the power of Nix. In this case the ideal +solution is to write a derivation for the plugin. + +We use `buildRustPackage` to build the library from the repository root, and +copy everything in the `postInstall` phase. ```nix -config.vim.startPlugins = ["neodev-nvim"]; +postInstall = '' + cp -r {lua,plugin} "$out" + + mkdir -p "$out/doc" + cp 'doc/'*'.txt' "$out/doc/" + + mkdir -p "$out/target" + mv "$out/lib" "$out/target/release" +''; +``` + +In a similar fashion, you may utilize `stdenv.mkDerivation` and other Nixpkgs +builders to build your library from source, and copy the relevant files and Lua +plugin files in the `postInstall` phase. Do note, however, that you still need +to fetch the plugin sources somehow. npins is, once again, the recommended +option to fetch the plugin sources. Refer to the previous section on how to use +npins to add a new plugin. + +Plugins built from source must go into the `flake/pkgs/by-name` overlay. It will +automatically create flake outputs for individual packages. Lastly, you must add +your package to the plugin builder (`pluginBuilders`) function manually in +`modules/wrapper/build/config.nix`. Once done, you may refer to your plugin as a +**string**. + +```nix +{ + config.vim.startPlugins = ["blink-cmp"]; +} ``` ## Modular setup options {#sec-modular-setup-options} @@ -81,7 +137,7 @@ in { } ``` -This above config will result in this lua script: +This above config will result in this Lua script: ```lua require('plugin-name').setup({ @@ -112,23 +168,41 @@ own fields! As you've seen above, `toLuaObject` is used to convert our nix attrSet `cfg.setupOpts`, into a lua table. Here are some rules of the conversion: -1. nix `null` converts to lua `nil` -2. number and strings convert to their lua counterparts -3. nix attrSet/list convert into lua tables -4. you can write raw lua code using `lib.generators.mkLuaInline`. This function - is part of nixpkgs. +1. Nix `null` converts to lua `nil` +2. Number and strings convert to their lua counterparts +3. Nix attribute sets (`{}`) and lists (`[]`) convert into Lua dictionaries and + tables respectively. Here is an example of Nix -> Lua conversion. + - `{foo = "bar"}` -> `{["foo"] = "bar"}` + - `["foo" "bar"]` -> `{"foo", "bar"}` +4. You can write raw Lua code using `lib.generators.mkLuaInline`. This function + is part of nixpkgs, and is accessible without relying on **nvf**'s extended + library. + - `mkLuaInline "function add(a, b) return a + b end"` will yield the + following result: -Example: + ```nix + { + _type = "lua-inline"; + expr = "function add(a, b) return a + b end"; + } + ``` -```nix -vim.your-plugin.setupOpts = { - on_init = lib.generators.mkLuaInline '' - function() - print('we can write lua!') - end - ''; -} -``` + The above expression will be interpreted as a Lua expression in the final + config. Without the `mkLuaInline` function, you will only receive a string + literal. You can use it to feed plugin configuration tables Lua functions + that return specific values as expected by the plugins. + + ```nix + { + vim.your-plugin.setupOpts = { + on_init = lib.generators.mkLuaInline '' + function() + print('we can write lua!') + end + ''; + }; + } + ``` ## Lazy plugins {#sec-lazy-plugins} @@ -137,25 +211,24 @@ Lazy plugins are managed by `lz.n`. ```nix # in modules/.../your-plugin/config.nix -{lib, config, ...}: -let +{config, ...}: let cfg = config.vim.your-plugin; in { vim.lazy.plugins.your-plugin = { - # instead of vim.startPlugins, use this: + # Instead of vim.startPlugins, use this: package = "your-plugin"; - # if your plugin uses the `require('your-plugin').setup{...}` pattern + # ıf your plugin uses the `require('your-plugin').setup{...}` pattern setupModule = "your-plugin"; inherit (cfg) setupOpts; - # events that trigger this plugin to be loaded + # Events that trigger this plugin to be loaded event = ["DirChanged"]; cmd = ["YourPluginCommand"]; - # keymaps + # Plugin Keymaps keys = [ - # we'll cover this in detail in the keymaps section + # We'll cover this in detail in the 'keybinds' section { key = "d"; mode = "n"; @@ -163,7 +236,6 @@ in { } ]; }; -; } ``` @@ -174,7 +246,9 @@ require('lz.n').load({ { "name-of-your-plugin", after = function() - require('your-plugin').setup({--[[ your setupOpts ]]}) + require('your-plugin').setup({ + --[[ your setupOpts ]]-- + }) end, event = {"DirChanged"}, @@ -186,5 +260,7 @@ require('lz.n').load({ }) ``` -A full list of options can be found -[here](https://notashelf.github.io/nvf/options.html#opt-vim.lazy.plugins +[`vim.lazy.plugins` spec]: https://notashelf.github.io/nvf/options.html#opt-vim.lazy.plugins + +A full list of options can be found in the [`vim.lazy.plugins` spec] on the +rendered manual. diff --git a/docs/manual/hacking/keybinds.md b/docs/manual/hacking/keybinds.md index 3940466f..90623dd3 100644 --- a/docs/manual/hacking/keybinds.md +++ b/docs/manual/hacking/keybinds.md @@ -30,8 +30,8 @@ There are many settings available in the options. Please refer to the [documentation](https://notashelf.github.io/nvf/options.html#opt-vim.keymaps) to see a list of them. -**nvf** provides a helper function, so that you don't have to write the -mapping attribute sets every time: +**nvf** provides a helper function, so that you don't have to write the mapping +attribute sets every time: - `mkKeymap`, which mimics neovim's `vim.keymap.set` function diff --git a/docs/manual/installation/custom-configuration.md b/docs/manual/installation/custom-configuration.md index b6c27163..52f81573 100644 --- a/docs/manual/installation/custom-configuration.md +++ b/docs/manual/installation/custom-configuration.md @@ -23,34 +23,32 @@ 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; # Enable Treesitter - tree-sitter.enable = true; + treesitter.enable = true; # Other options will go here. Refer to the config # 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/flakes.md b/docs/manual/installation/modules/flakes.md new file mode 100644 index 00000000..273d2b00 --- /dev/null +++ b/docs/manual/installation/modules/flakes.md @@ -0,0 +1,33 @@ +### Prerequisites {#sec-flakes-prerequisites} + +To install nvf with flakes, you must make sure the following requirements are +met. + +1. Nix 2.4 or later must be installed. You may use `nix-shell` to get a later + version of Nix from nixpkgs. +2. Flake-related experimental features must be enabled. Namely, you need + `nix-command` and `flakes`. Some Nix vendors enable those by default, please + consult their documentation if you are not using mainstream Nix. + - When using NixOS, add the following to your `configuration.nix` and rebuild + your system. + + ```nix + nix.settings.experimental-features = "nix-command flakes"; + ``` + + - If you are not using NixOS, add the following to `nix.conf` (located at + `~/.config/nix/` or `/etc/nix/nix.conf`). + + ```bash + experimental-features = nix-command flakes + ``` + + - You may need to restart the Nix daemon with, for example, + `sudo systemctl restart nix-daemon.service`. + + - Alternatively, you can enable flakes on a per-command basis with the + following additional flags to `nix` and `home-manager`: + + ```sh + $ nix --extra-experimental-features "nix-command flakes" + ``` diff --git a/docs/manual/installation/modules/home-manager.md b/docs/manual/installation/modules/home-manager.md index 34f2757e..37d35e2b 100644 --- a/docs/manual/installation/modules/home-manager.md +++ b/docs/manual/installation/modules/home-manager.md @@ -5,9 +5,18 @@ inside the home-manager configuration without having to call for the wrapper yourself. It is the recommended way to use **nvf** alongside the NixOS module depending on your needs. -To use it, we first add the input flake. +## With Flakes {#sec-hm-flakes} + +```{=include=} +flakes.md +``` + +### Usage {#sec-hm-flakes-usage} + +To use **nvf** with flakes, we first need to add the input to our `flake.nix`. ```nix +# flake.nix { inputs = { # Optional, if you intend to follow nvf's obsidian-nvim input @@ -16,7 +25,7 @@ To use it, we first add the input flake. # Required, nvf works best and only directly supports flakes nvf = { - url = "github:notashelf/nvf"; + url = "github:NotAShelf/nvf"; # 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. @@ -25,6 +34,8 @@ To use it, we first add the input flake. # for example: inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- this will use the obsidian-nvim from your inputs }; + + # ... }; } ``` @@ -39,7 +50,7 @@ Followed by importing the home-manager module somewhere in your configuration. } ``` -## Example Installation {#sec-example-installation-hm} +### Example Installation {#sec-example-installation-hm} ```nix { @@ -49,13 +60,10 @@ 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"; - pkgs = nixpkgs.legacyPackages.${system}; - 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 { - inherit pkgs; + 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, `programs.nvf.*` may be defined here @@ -69,7 +77,8 @@ Once the module is properly imported by your host, you will be able to use the `programs.nvf` module option anywhere in your configuration in order to configure **nvf**. -```nix{ +```nix +{ programs.nvf = { enable = true; # your settings need to go into the settings attribute set @@ -92,3 +101,45 @@ installation sections of the manual. You may find all available options in the [appendix](https://notashelf.github.io/nvf/options) ::: + +## Without Flakes {#sec-hm-flakeless} + +As of v0.8, it is possible to install **nvf** on a system if you are not using +flakes. This is possible thanks to the flake-compat project. + +To get started, you must fetch the repository using `builtins.fetchTarball` or a +similar mechanism. + +```nix +# home.nix +let + nvf = import (builtins.fetchTarball { + url = "https://github.com/notashelf/nvf/archive/.tar.gz"; + # Optionally, you can add 'sha256' for verification and caching + # sha256 = ""; + }); +in { + imports = [ + # Import the NixOS module from your fetched input + nvf.homeManagerModules.nvf + ]; + + # Once the module is imported, you may use `programs.nvf` as exposed by the + # NixOS module. + programs.nvf.enable = true; +} +``` + +[npins]: https://github.com/andir/npins +[niv]: https://github.com/nmattia/niv + +::: {.tip} + +Nix2 does not have a builtin lockfile mechanism like flakes. As such you must +manually update the URL and hash for your input. This is annoying to deal with, +and most users choose to defer this task to projects such as [npins] or [niv]. +If you are new to NixOS, I encourage you to look into Flakes and see if they fit +your use case. Alternatively, look into the aforementioned projects for more +convenient dependency management mechanisms. + +::: diff --git a/docs/manual/installation/modules/nixos.md b/docs/manual/installation/modules/nixos.md index bcf7472b..946905c1 100644 --- a/docs/manual/installation/modules/nixos.md +++ b/docs/manual/installation/modules/nixos.md @@ -5,9 +5,18 @@ the NixOS configuration without having to call for the wrapper yourself. It is the recommended way to use **nvf** alongside the home-manager module depending on your needs. -To use it, we first add the input flake. +## With Flakes {#sec-nixos-flakes} + +```{=include=} +flakes.md +``` + +### Usage {#sec-nixos-flakes-usage} + +To use **nvf** with flakes, we first need to add the input to our `flake.nix`. ```nix +# flake.nix { inputs = { # Optional, if you intend to follow nvf's obsidian-nvim input @@ -16,7 +25,7 @@ To use it, we first add the input flake. # Required, nvf works best and only directly supports flakes nvf = { - url = "github:notashelf/nvf"; + url = "github:NotAShelf/nvf"; # 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. @@ -25,6 +34,8 @@ To use it, we first add the input flake. # for example: inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- this will use the obsidian-nvim from your inputs }; + + # ... }; } ``` @@ -39,7 +50,7 @@ Followed by importing the NixOS module somewhere in your configuration. } ``` -## Example Installation {#sec-example-installation-nixos} +### Example Installation {#sec-example-installation-nixos} ```nix { @@ -64,10 +75,12 @@ Once the module is properly imported by your host, you will be able to use the `programs.nvf` module option anywhere in your configuration in order to configure **nvf**. -```nix{ +```nix +{ programs.nvf = { enable = true; - # your settings need to go into the settings attribute set + + # Your settings need to go into the settings attribute set # most settings are documented in the appendix settings = { vim.viAlias = false; @@ -87,3 +100,45 @@ installation sections of the manual. You may find all available options in the [appendix](https://notashelf.github.io/nvf/options) ::: + +## Without Flakes {#sec-nixos-flakeless} + +As of v0.8, it is possible to install **nvf** on a system if you are not using +flakes. This is possible thanks to the flake-compat project. + +To get started, you must fetch the repository using `builtins.fetchTarball` or a +similar mechanism. + +```nix +# configuration.nix +let + nvf = import (builtins.fetchTarball { + url = "https://github.com/notashelf/nvf/archive/.tar.gz"; + # Optionally, you can add 'sha256' for verification and caching + # sha256 = ""; + }); +in { + imports = [ + # Import the NixOS module from your fetched input + nvf.nixosModules.nvf + ]; + + # Once the module is imported, you may use `programs.nvf` as exposed by the + # NixOS module. + programs.nvf.enable = true; +} +``` + +[npins]: https://github.com/andir/npins +[niv]: https://github.com/nmattia/niv + +::: {.tip} + +Nix2 does not have a builtin lockfile mechanism like flakes. As such you must +manually update the URL and hash for your input. This is annoying to deal with, +and most users choose to defer this task to projects such as [npins] or [niv]. +If you are new to NixOS, I encourage you to look into Flakes and see if they fit +your use case. Alternatively, look into the aforementioned projects for more +convenient dependency management mechanisms. + +::: diff --git a/docs/manual/installation/standalone/nixos.md b/docs/manual/installation/standalone/nixos.md index a78c8dee..65dc9205 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,7 +49,11 @@ 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 your own + # 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 fd225766..18932896 100644 --- a/docs/manual/manual.md +++ b/docs/manual/manual.md @@ -8,7 +8,6 @@ try-it-out.md ``` ```{=include=} parts -default-configs.md installation.md configuring.md tips.md diff --git a/docs/manual/options.md b/docs/manual/options.md index 3b70484f..beab4f16 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 let us know if you believe any of +the options below are missing useful examples. +