From d68d212ad43efd6f65a8523e4cb6e70f6bbe9ba6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ph=E1=BA=A1m=20B=C3=ACnh=20An?= <111893501+brianhuster@users.noreply.github.com> Date: Sun, 27 Apr 2025 22:11:02 +0700 Subject: [PATCH] docs: provide example_init.lua #33524 Problem: There are some "boilerplate" steps for new users. Although we are constantly improving defaults and lifting patterns into core, users eventually want to know how to start their own config, add plugins, etc. Solution: Add `runtime/example_init.lua` and refer to it from docs. (cherry picked from commit 86b34ad073797da791348b97393d5d7b7ceca2e3) --- runtime/doc/lua-guide.txt | 7 +- runtime/doc/nvim.txt | 10 +++ runtime/example_init.lua | 88 ++++++++++++++++++++++++++ runtime/tutor/en/vim-01-beginner.tutor | 4 ++ test/functional/plugin/tutor_spec.lua | 2 +- 5 files changed, 106 insertions(+), 5 deletions(-) create mode 100644 runtime/example_init.lua diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt index d0d148f689..fbe159066e 100644 --- a/runtime/doc/lua-guide.txt +++ b/runtime/doc/lua-guide.txt @@ -93,10 +93,9 @@ Finally, you can include Lua code in a Vimscript file by putting it inside a Using Lua files on startup *lua-guide-config* Nvim supports using `init.vim` or `init.lua` as the configuration file, but -not both at the same time. This should be placed in your |config| directory, -which is typically `~/.config/nvim` for Linux, BSD, or macOS, and -`~/AppData/Local/nvim/` for Windows. Note that you can use Lua in `init.vim` -and Vimscript in `init.lua`, which will be covered below. +not both at the same time. This should be placed in your |config| directory +(run `:echo stdpath('config')` to see where it is). Note that you can also use +Lua in `init.vim` and Vimscript in `init.lua`, which will be covered below. If you'd like to run any other Lua script on |startup| automatically, then you can simply put it in `plugin/` in your |'runtimepath'|. diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index 8593511dbc..8189cad7c1 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -75,6 +75,16 @@ the same Nvim configuration on all of your machines, by creating ============================================================================== What next? *nvim-quickstart* +If you want to use Lua to configure Nvim, you can copy an example +configuration to your |init.lua| +>vim + :exe 'edit' stdpath('config') .. '/init.lua' + :read $VIMRUNTIME/example_init.lua +< +See |lua-guide| for practical notes on using Lua to configure Nvim. + +"IDE" features in Nvim are provided by Language Server Protocol. See |lsp| + If you are just trying out Nvim for a few minutes, and want to see the extremes of what it can do, try one of these popular "extension packs" or "distributions" (Note: Nvim is not affiliated with these projects, and does diff --git a/runtime/example_init.lua b/runtime/example_init.lua new file mode 100644 index 0000000000..5a55ea8346 --- /dev/null +++ b/runtime/example_init.lua @@ -0,0 +1,88 @@ +-- Set as the leader key +-- See `:help mapleader` +-- NOTE: Must happen before plugins are loaded (otherwise wrong leader will be used) +vim.g.mapleader = ' ' + +-- [[ Setting options ]] See `:h vim.o` +-- NOTE: You can change these options as you wish! +-- For more options, you can see `:help option-list` +-- To see documentation for an option, you can use `:h 'optionname'`, for example `:h 'number'` +-- (Note the single quotes) + +-- Print the line number in front of each line +vim.o.number = true + +-- Use relative line numbers, so that it is easier to jump with j, k. This will affect the 'number' +-- option above, see `:h number_relativenumber` +vim.o.relativenumber = true + +-- Sync clipboard between OS and Neovim. Schedule the setting after `UiEnter` because it can +-- increase startup-time. Remove this option if you want your OS clipboard to remain independent. +-- See `:help 'clipboard'` +vim.api.nvim_create_autocmd('UIEnter', { + callback = function() + vim.o.clipboard = 'unnamedplus' + end, +}) + +-- Case-insensitive searching UNLESS \C or one or more capital letters in the search term +vim.o.ignorecase = true +vim.o.smartcase = true + +-- Highlight the line where the cursor is on +vim.o.cursorline = true + +-- Minimal number of screen lines to keep above and below the cursor. +vim.o.scrolloff = 10 + +-- Show and trailing spaces +vim.o.list = true + +-- if performing an operation that would fail due to unsaved changes in the buffer (like `:q`), +-- instead raise a dialog asking if you wish to save the current file(s) See `:help 'confirm'` +vim.o.confirm = true + +-- [[ Set up keymaps ]] See `:h vim.keymap.set()`, `:h mapping`, `:h keycodes` + +-- Use to exit terminal mode +vim.keymap.set('t', '', '') + +-- Map , , , to navigate between windows in any modes +vim.keymap.set({ 't', 'i' }, '', 'h') +vim.keymap.set({ 't', 'i' }, '', 'j') +vim.keymap.set({ 't', 'i' }, '', 'k') +vim.keymap.set({ 't', 'i' }, '', 'l') +vim.keymap.set({ 'n' }, '', 'h') +vim.keymap.set({ 'n' }, '', 'j') +vim.keymap.set({ 'n' }, '', 'k') +vim.keymap.set({ 'n' }, '', 'l') + +-- [[ Basic Autocommands ]]. +-- See `:h lua-guide-autocommands`, `:h autocmd`, `:h nvim_create_autocmd()` + +-- Highlight when yanking (copying) text. +-- Try it with `yap` in normal mode. See `:h vim.hl.on_yank()` +vim.api.nvim_create_autocmd('TextYankPost', { + desc = 'Highlight when yanking (copying) text', + callback = function() + vim.hl.on_yank() + end, +}) + +-- [[ Create user commands ]] +-- See `:h nvim_create_user_command()` and `:h user-commands` + +-- Create a command `:GitBlameLine` that print the git blame for the current line +vim.api.nvim_create_user_command('GitBlameLine', function() + local line_number = vim.fn.line('.') -- Get the current line number. See `:h line()` + local filename = vim.api.nvim_buf_get_name(0) + print(vim.fn.system({ 'git', 'blame', '-L', line_number .. ',+1', filename })) +end, { desc = 'Print the git blame for the current line' }) + +-- [[ Add optional packages ]] +-- Nvim comes bundled with a set of packages that are not enabled by +-- default. You can enable any of them by using the `:packadd` command. + +-- For example, to add the "nohlsearch" package to automatically turn off search highlighting after +-- 'updatetime' and when going to insert mode +vim.cmd('packadd! nohlsearch') diff --git a/runtime/tutor/en/vim-01-beginner.tutor b/runtime/tutor/en/vim-01-beginner.tutor index b2d17e1713..18be5ce9a0 100644 --- a/runtime/tutor/en/vim-01-beginner.tutor +++ b/runtime/tutor/en/vim-01-beginner.tutor @@ -967,6 +967,10 @@ NOTE: Completion works for many commands. It is especially useful for `:help`{vi 6. While in command mode, press ``{normal} to see possible completions. Press ``{normal} to use the completion menu and select a match. +# What's next? + +Run `:help nvim-quickstart`{vim} to get started with configuring or extending Nvim. + # CONCLUSION This was intended to give a brief overview of the Neovim editor, just enough to diff --git a/test/functional/plugin/tutor_spec.lua b/test/functional/plugin/tutor_spec.lua index fd229c53ec..2a05bed4d4 100644 --- a/test/functional/plugin/tutor_spec.lua +++ b/test/functional/plugin/tutor_spec.lua @@ -131,7 +131,7 @@ describe(':Tutor', function() {0: }University. E-mail: {2:bware@mines.colorado.edu}. | ]] - feed(':969zt') + feed(':973zt') screen:expect(expected) end) end)