DEV Community: Elves Sousa

Taking Neovim to the Moon - part II

Elves Sousa — Tue, 10 Jan 2023 14:13:03 +0000

Hello again! In this article, I continue with the Neovim configuration using Lua. If you missed it, click here to see the previous article. Without reading it, it will not be possible to understand the text that follows.

Minor substitutions

Shortly after publishing the previous article, I was informed (thanks, Sérgio Araújo!) that the extension used to ease language server's setup, Neovim LSP Installer, has been retired. Its successor is Mason, which basically has the same tools. Command names change, but the transition is smooth: on the surface, just the name and a better UI presentation. What really changes is the internal part, where, according to the developer, it's easier to create new features and test.

To make the switch, just change the lines where the LSP Installer is quoted:

packer.startup(function()
  -- use("williamboman/nvim-lsp-installer")
  use("williamboman/mason.nvim")
end)

-- LSP Installer
require("mason").setup()

After that, run the :PackerSync command and restart Neovim to apply the changes.

Modules

Splitting the config file into modules

I purposely did all the configuration in just one Lua file in the previous article. This was done to make it easier to understand how different parts work together. You can keep it that way if you like, but if you need to use a lot of extensions, working on a single file will become cumbersome.

The file structure I use is as follows:

lua
├── configs
│  ├── completion.lua
│  ├── diagnostics.lua
│  ├── formatting.lua
│  ├── highlighting.lua
│  ├── keymaps.lua
│  ├── languages.lua
│  ├── options.lua
│  ├── plugins.lua
│  └── theming.lua
└── init.lua

Basically, it's a folder called configs/, with several *.lua files inside. They were named according to their respective roles. All theme settings are in theming.lua and editor options in options.lua, for example. My categorization was pretty simple. Feel free to make your own.

To split the single file into modules, it's no big deal. In my case, I just used the comments that I had placed as separators in the file as guides. Each comment like that, a new file.

To make it clearer, here's an example:

---------------------------------
-- Options
---------------------------------
local set = vim.opt

set.background = "dark"
set.clipboard = "unnamedplus"

---------------------------------
-- Plugins
---------------------------------
local packer = require("packer")
vim.cmd([[packadd packer.nvim]])

packer.startup(function()
    use("hrsh7th/cmp-buffer")
    use("hrsh7th/cmp-cmdline")
  ...
end)

Using the structure above, what follows after the -- Options comment will be placed in the configs/options.lua file; what follows after the -- Plugins comment in the configs/plugins.lua file, and so on.

Index file

The Lua language uses init.lua files as an index, similar to index.html in HTML or main.rs in Rust. Our init.lua, which previously contained all the configuration, will now only refer to the files. To import them in the file, just use the require() function passing the argument in the format <directory>.<filename>:

require("configs.options")
require("configs.plugins")
require("configs.highlighting")
require("configs.theming")
require("configs.completion")
require("configs.diagnostics")
require("configs.languages")
require("configs.formatting")
require("configs.keymaps")

Where to place these files

For these files to take effect, simply place them in the ~/.config/nvim folder. If there are no errors, everything will work fine when restarting Neovim. But if you're like me, and prefer to leave everything versioned in a GIT repository, I recommend creating symlinks to the init.lua file and the lua directory inside the ~/.config/nvim folder. To create them, just issue these commands in the terminal:

$ cd ~/.config/nvim/
$ ln -sf ~/.dotfiles/editors/nvim/init.lua .
$ ln -sf ~/.dotfiles/editors/nvim/lua .

If you list the directory contents using the ls -l command, you will see something like this:

lrwxrwxrwx 48 user 22 out 18:50 init.lua -> /home/user/.dotfiles/editors/nvim/init.lua
lrwxrwxrwx 43 user 20 out 20:21 lua -> /home/user/.dotfiles/editors/nvim/lua

Note that .dotfiles/editors/nvim is just where I keep my files, so this may be different in your case. With this, you don't need to repeat all the setup from scratch again, and you can use the same files on other machines.

I believe that with these adjustments, you will have a good structure to configure your Neovim and extend it to suit your needs.

If you want to see the complete code, with all the changes I made, I've left the link to my .dotfiles repository below. This repo also includes the old init.lua made in the previous article, just in case. It has been renamed to init.lua.old.

See you later!

Links

If this article helped you in some way, consider donating. This will help me to create more content like this!

Taking Neovim to the Moon

Elves Sousa — Sun, 14 Aug 2022 19:00:00 +0000

I've been using Neovim as my main code editor for a while now, and so far, I haven't changed my mind. I wrote some articles about this editor, and one of them was about creating a simple configuration file that works for both Neovim and Vim. This one still works perfectly, but like everything else in the computer world, there is always another way to achieve the same goals. One of these ways is to configure Neovim using Lua language.

I received a few requests to create a Lua configuration, but I procrastinated until I actually needed to configure Neovim from scratch again. The opportunity came recently, as I needed to set up a Ryzentosh (Hackintosh with a Ryzen processor) for work, and there was a clean Neovim to configure. Before getting into the guide itself, I will comment about a few things.

The Lua language

Sample code in Lua

Lua is a programming language created by Brazilians Roberto Ierusalimschy, Waldemar Celes and Luiz Henrique de Figueiredo at PUC/RJ. It is a high-level, multi-paradigm, lightweight language with dynamic typing and automatic garbage collection.

It was made to automate and extend more complex applications, such as Petrobras projects, game engines, embedded systems, and other applications such as Neovim.

As being a satellite language has always been one of its goals, "Lua" (Moon in Portuguese) is quite an appropriate name. Its ease of learning and considerable speed have been positive points in its adoption.

This article will not make you a master of the language, nor is that the purpose. But you will know enough to configure Neovim.

About the config file

Neovim

In the init.vim I made in another article, it was possible to create a single file that contains everything needed to have a comfortable experience with Neovim. With the init.lua that will be created here, this is also possible, and that's what I propose. On another occasion, we will separate it into several files, as it seems to be the standard way.

If you're new to Neovim, don't try to follow this guide. Start with the VimScript configuration file created in the other article, and once you're more comfortable with the environment, come back!

Config file

To get started, create an init.lua file in the .config/nvim directory, located in your user folder:



$ cd ~/.config/nvim/
$ touch init.lua

Setting options

The goal is basically to translate the init.vim I already have into Lua language.

In VimScript, each option is set with the keyword set. In Lua, you use vim.opt.[option-name], which, let's face it, is not very readable if repeated several times. So, I decided to allocate vim.opt in a local variable called set (wow!). This makes everything more familiar and readable.

Here are the options I use:



---------------------------------
-- Opções
---------------------------------
local set = vim.opt

set.background = "dark"
set.clipboard = "unnamedplus"
set.completeopt = "noinsert,menuone,noselect"
set.cursorline = true
set.expandtab = true
set.foldexpr = "nvim_treesitter#foldexpr()"
set.foldmethod = "manual"
set.hidden = true
set.inccommand = "split"
set.mouse = "a"
set.number = true
set.relativenumber = true
set.shiftwidth = 2
set.smarttab = true
set.splitbelow = true
set.splitright = true
set.swapfile = false
set.tabstop = 2
set.termguicolors = true
set.title = true
set.ttimeoutlen = 0
set.updatetime = 250
set.wildmenu = true
set.wrap = true

If you've used Neovim, you're probably already familiar with several of these options, but if you're not, here's an explanation of each one:

background=dark: apply the color set to dark screens. Not just the background of the screen, as it may seem.
clipboard=unnamedplus: enables the clipboard between Neovim and other system programs.
completeopt: modifies the behavior of the auto-complete menu to behave more like an IDE.
cursorline: highlights the current line in the editor.
expandtab: turns tabs into spaces.
foldexpr and foldmethod: these options were added to improve the code folding behavior in TreeSitter.
hidden: hide unused buffers.
inccommand=split: show replacements in a split window, before applying to the file.
mouse=a: allows the use of the mouse.
number: shows the line numbers.
relativenumber: shows lines numbers starting from the current one. Useful to assist in commands that use more lines.
shiftwidth=2: number of spaces when indenting the text.
splitbelow and splitright: change the behavior of splitting the screen with the command :split (split the screen horizontally) and :vsplit (vertically). In this case, the screens will always split below the current screen and to the right.
swapfile = false: inhibit the creation of Vim .swp files.
tabstop=2: number of spaces for tabs.
termguicolors: expands the number of usable colors, if the terminal emulator supports it.
title: shows the title of the file.
ttimeoutlen=0: time in milliseconds to accept commands.
updatetime: time in milliseconds that language servers use to check for errors.
wildmenu: shows a more advanced menu for autocomplete suggestions.

To see them in action, just quit Neovim and run it again (you know how to do that, don't you?), or go into shift + : command mode and type luafile %. This will read the init.lua file and apply the options to the current instance.

Syntax

To add automatic syntax detection support for open files:



vim.cmd([[
  filetype plugin indent on
  syntax on
]])

Note the vim.cmd: it makes possible to use VimScript in a .lua file. In this case, it's a very practical way to write less code.

Plugins

Plugin manager

Packer: Extension manager for Neovim written in Lua

To install plugins, you need to install a manager first. Packer will be used for this, as it is made in Lua and obviously supports configuration in this language.

If you are using macOS or Linux, just run this command in the terminal:



$ git clone --depth 1 https://github.com/wbthomason/packer.nvim\
 ~/.local/share/nvim/site/pack/packer/start/packer.nvim

After restarting Neovim, you will have a series of commands that will make installing, updating and removing plugins much easier.

To add it to our configuration file, just add the following lines:



---------------------------------
-- Plugins
---------------------------------
local packer = require("packer")

-- Include packer.nvim
vim.cmd([[packadd packer.nvim]])

packer.startup(function()
  -- Plugins are listed here
end)

Note the require("packer"): this is the way to import files in Lua. For anyone who has used NodeJS, this is very familiar. Following that, a command in VimScript is added so that Neovim recognizes the existence of the Packer package.

To add plugins to be installed, simply include use("user-in-github/repository"), in the anonymous function in packer.startup(). The first plugin to be added will be Packer itself:



packer.startup(function()
  -- Plugin manager
  use("wbthomason/packer.nvim")
end)

This way we can update Packer as well as other plugins.

Plugins used in this setup

Here is the plugins list:



packer.startup(function()
  -- Completion
  use("hrsh7th/cmp-buffer")
  use("hrsh7th/cmp-cmdline")
  use("hrsh7th/cmp-nvim-lsp")
  use("hrsh7th/cmp-path")
  use("hrsh7th/nvim-cmp")
  -- Motor de snippets
  use("L3MON4D3/LuaSnip")
  use("saadparwaiz1/cmp_luasnip")
  -- Formatting
  use("jose-elias-alvarez/null-ls.nvim")
  -- Language server
  use("neovim/nvim-lspconfig")
  use("williamboman/nvim-lsp-installer")
  -- Syntax parser
  use("nvim-treesitter/nvim-treesitter")
  -- Plugin manager
  use("wbthomason/packer.nvim")
  -- Utilities
  use("windwp/nvim-autopairs")
  use("norcalli/nvim-colorizer.lua")
  use("lewis6991/gitsigns.nvim")
  -- Dependencies
  use("nvim-lua/plenary.nvim")
  use("kyazdani42/nvim-web-devicons")
  use("MunifTanjim/nui.nvim")
  -- File browser
  use("nvim-telescope/telescope.nvim")
  -- Interface
  use("akinsho/bufferline.nvim")
  use({ "nvim-neo-tree/neo-tree.nvim", branch = "v2.x" })
  use("nvim-lualine/lualine.nvim")
  -- Color scheme
  use("elvessousa/sobrio")
end)

A brief explanation of the function of each of them:

Autocomplete

Neovim CMP: engine for autocomplete.
CMP Buffer: adds autocomplete based on the text typed in the open files (buffers).
CMP CmdLine: command line autocomplete.
CMP nvim-lsp: autocomplete using language server.
CMP Path: directory paths autocomplete.

Snippets engine

LuaSnip e Cmp LuaSnip: snippet engine needed for Neovim CMP

Formatting

Null LS: provides several tools, such as diagnostics and code formatting.

Language server

Neovim LSP Config: language servers support for Neovim.
Neovim LSP Installer: installs language servers from a popup window.

Syntax parser

Treesitter: syntax highlighting.

Utilities

Neovim Autopairs: automatically closes parentheses, square brackets and braces.
Neovim Colorizer: displays HEX, RGB or HSL colors in the editor.
Neovim GitSigns: shows git changes on the side

Dependencies

Plenary: Lua plugin framework for Neovim. Required for some extensions to work.
Neovim Web Devicons: enables the use of icon fonts in plugins. Detail: you need to have a "Nerd Font" installed on the system and applied in your terminal emulator.
NUI: UI library, used by some plugins.

File management

Telescope: fuzzy file search.

Interface

Bufferline: tab bar
Neo Tree: file/folder tree. Alternative to NetRW.
Lualine: status bar, similar to Airline.

Theme

Sobrio: theme made by me and that I use daily. Now with TreeSitter support.

Installing the extensions

To install, as we did the other time with VimPlug, it is necessary to use a command to install. However, unlike VimPlug, a single Packer command is responsible for removing, adding or updating the extensions: :PackerSync.

When using this command, a side split will appear and show the changes that Packer has made to your Neovim installation. Remember to always use this command when adding or removing plugins from your list.

Plugin startup

In addition to installing the files with Packer, you need to initialize the plugins so that they can be used in Neovim. Some of them work without options, others need more settings. To see some extensions working, we'll add the simplest ones first:



---------------------------------
-- Misc plugins
---------------------------------
-- Autopairs
require("nvim-autopairs").setup({
    disable_filetype = { "TelescopePrompt" },
})

-- Colorizer
require("colorizer").setup()

-- Git signs
require("gitsigns").setup()

-- Bufferline
require("bufferline").setup()

-- Lualine
require("lualine").setup()

This is a pattern. Plugins are usually initialized with require("plugin-name").setup().

Note that in the Autopairs plugin, I put an option to disable it from working in the Telescope window, to avoid unwanted behavior.

Neo Tree

Neo Tree: Directory tree

Neo Tree is a NetRW replacement. By default, it already works fine, but I recommend adding the options below:



-- Neo tree
require("neo-tree").setup({
  close_if_last_window = false,
  enable_diagnostics = true,
  enable_git_status = true,
  popup_border_style = "rounded",
  sort_case_insensitive = false,
  filesystem = {
    filtered_items = {
      hide_dotfiles = false,
      hide_gitignored = false,
    },
  },
  window = { width = 30 },
})

Explanation of the options:

close_if_last_window = false: keeps Neo Tree visible if there are no more files open.
enable_diagnostics = true: displays errors or warnings in the file, depending on the language server.
enable_git_status = true: displays Git change information.
popup_border_style = "rounded": rounds dialog borders.
sort_case_insensitive = false: ignores case when sorting files.
hide_dotfiles=false: show hidden files.
hide_gitignored = false: show files ignored by the version control.
window = { width = 30 }: defines the width of the Neo Tree split to 30% of the screen.

Color scheme

Sobrio: The theme I made and use

Depending on the theme you use, the configuration will vary. If the theme you chose has configuration available in Lua, the process is very similar to plugins. In the case of my theme, Sobrio, I just added it to the vim.cmd I mentioned at the beginning of this article:



---------------------------------
-- Color scheme and syntax
---------------------------------
vim.cmd([[
  filetype plugin indent on
  syntax on
  colorscheme sobrio
]])

Variations

Sobrio Ghost: variant of the Sobrio theme, with transparent background

This theme I made has other variants, such as a light version (Sobrio Light), one with alternative colors (Sobrio Verde) and one with a transparent background (Sobrio Ghost).

Syntax parser configuration

TreeSitter is an extension responsible for the syntax highlighting presented on the screen. The result is usually much better than the default parser in Neovim.

Below is a sample configuration compatible with my workflow:



---------------------------------
-- Syntax highlighting
---------------------------------
require("nvim-treesitter.configs").setup({
  ensure_installed = {
    "bash",
    "c",
    "cpp",
    "css",
    "elixir",
    "fish",
    "graphql",
    "html",
    "javascript",
    "json",
    "lua",
    "markdown",
    "markdown_inline",
    "php",
    "python",
    "regex",
    "ruby",
    "rust",
    "scss",
    "sql",
    "toml",
    "tsx",
    "typescript",
    "vim",
    "yaml",
  },
  highlight = { enable = true },
  indent = { enable = true },
  autotag = {
  enable = true,
  filetypes = {
    "html",
    "javascript",
    "javascriptreact",
    "svelte",
    "typescript",
    "typescriptreact",
    "vue",
    "xml",
  },
  },
})

Brief explanation of the options:

ensure_installed: list of languages to be installed in TreeSitter. If you wish, just use the all option and TreeSitter will use all the languages it supports, even the ones you never use or will ever use.
highlight: enables TreeSitter colorization.
indent: enables code indentation.
autotag: interprets XML or HTML tags in the languages listed in filetypes.

Code completion

nvim-cmp

Neovim CMP or nvim-cmp is an extension that enables code completion in Neovim. For it to work, several other related extensions need to be present.



---------------------------------
-- Completion
---------------------------------
local cmp = require("cmp")

cmp.setup({
  snippet = {
    expand = function(args)
      require("luasnip").lsp_expand(args.body)
    end,
  },
  mapping = cmp.mapping.preset.insert({
    ["<C-b>"] = cmp.mapping.scroll_docs(-4),
    ["<C-f>"] = cmp.mapping.scroll_docs(4),
    ["<C-Space>"] = cmp.mapping.complete(),
    ["<C-e>"] = cmp.mapping.abort(),
    ["<CR>"] = cmp.mapping.confirm({ select = true }),
  }),
  sources = cmp.config.sources({
    { name = "nvim_lsp" },
    { name = "luasnip" },
    { name = "buffer" },
    { name = "path" },
  }),
})

-- File types specifics
cmp.setup.filetype("gitcommit", {
  sources = cmp.config.sources({
    { name = "cmp_git" },
  }, {
    { name = "buffer" },
  }),
})

-- Command line completion
cmp.setup.cmdline("/", {
  mapping = cmp.mapping.preset.cmdline(),
  sources = { { name = "buffer" } },
})

cmp.setup.cmdline(":", {
  mapping = cmp.mapping.preset.cmdline(),
  sources = cmp.config.sources({
    { name = "path" },
  }, {
    { name = "cmdline" },
  }),
})

Most of this code I inserted according to the suggestions available in the author's repository. The only thing I did was adapting it for use with the LuaSnip suggestion engine.

In the snippet option, you configure which suggestion engine will be used. In mapping, keyboard shortcuts to CMP commands are added. The sources option lets you sort the suggestion sources by priority. The code above sets the following the priorities:

Language server suggestions
LuaSnip pre-made codes
Words written in the current file
Directory paths on your computer

The cmp.setup.filetypes block allows you to configure the behavior of Neovim CMP for a given file type. In this case, rules for using cmp_git in Git-related operations.

cmp.setup.cmdline configures options for Neovim's command mode. The fact that there are two blocks is because commands can start with the characters / or : and in each case the priorities of suggestions change.

Code formatting

NullLS is an extension that provides various tools based on the language server. One such tool is code formatting.

By default, nothing is done. You need to add some settings for NullLS to kick in. Below is sample setup for those who use Python, Rust, PHP, JavaScript/TypeScript, HTML, CSS/SCSS and Lua.



---------------------------------
-- Formatting
---------------------------------
local diagnostics = require("null-ls").builtins.diagnostics
local formatting = require("null-ls").builtins.formatting
local augroup = vim.api.nvim_create_augroup("LspFormatting", {})

require("null-ls").setup({
  sources = {
    formatting.black,
    formatting.rustfmt,
    formatting.phpcsfixer,
    formatting.prettier,
    formatting.stylua,
  },
  on_attach = function(client, bufnr)
    if client.name == "tsserver" or client.name == "rust_analyzer" or client.name == "pyright" then
      client.resolved_capabilities.document_formatting = false
    end

    if client.supports_method("textDocument/formatting") then
      vim.api.nvim_clear_autocmds({ group = augroup, buffer = bufnr })
      vim.api.nvim_create_autocmd("BufWritePre", {
        group = augroup,
        callback = function()
          vim.lsp.buf.formatting_sync()
        end,
    })
    end
  end,
})

---------------------------------
-- Auto commands
---------------------------------
vim.cmd([[ autocmd BufWritePre <buffer> lua vim.lsp.buf.formatting_sync() ]])

In the sources option, you list the code formatting sources that will be used. The list of supported formatters is in the project repository. Note that it is not enough to just add to the list, the executable of each one must be installed on the machine to work.

The function in on_attach has two uses:

Disables formatting on some servers, to prevent NullLS from asking which font to use every time it applies formatting, or from having strange behaviors.
Create an autocmd to apply formatting on save, if the current file is supported.

Formatters installation

Each formatter has its own way of installing, but in general, they are available in three ways:

Package manager for the programming language: Cargo for Rust, PIP for Python, NPM or Yarn for JavaScript/TypeScript.
System package manager: Homebrew on macOS; Pacman, APT, DNF, etc. for Linux distributions.
Compiling directly from source code. If you are not a Gentoo Linux user or want to contribute to the language server development, I do not recommend this option.

Installation examples

The formatters used in this setup were Black (Python), Rustfmt (Rust), PHP CS Fixer (PHP), Prettier (JavaScript and derivatives, HTML, CSS and derivatives) and Stylua (Lua).

To install Stylua, Prettier, PHP CS Fixer and Black using their respective package managers:



$ cargo install stylua
$ pip install black
$ (sudo) npm i -g prettier
$ composer global require friendsofphp/php-cs-fixer

To install Stylua with Pacman on Arch Linux:



$ sudo pacman -S stylua

Using Homebrew, you can install PHP CS Fixer as follows:



$ brew install php-cs-fixer

By the way, Homebrew is not just for macOs. It's available for Linux and Windows, too.

Language servers

Neovim has a built-in language detector. It can be configured from scratch, but to help in this process, the Neovim team made the Neovim LSP Config extension. With it, just start lspconfig mentioning the name of the language server you want to activate in Neovim. Here's an example below:



---------------------------------
-- Language servers
---------------------------------
local lspconfig = require("lspconfig")
local caps = vim.lsp.protocol.make_client_capabilities()
local no_format = function(client, bufnr)
  client.resolved_capabilities.document_formatting = false
end

-- Capabilities
caps.textDocument.completion.completionItem.snippetSupport = true

-- Python
lspconfig.pyright.setup({
  capabilities = caps,
  on_attach = no_format
})

-- PHP
lspconfig.phpactor.setup({ capabilities = caps })

-- JavaScript/Typescript
lspconfig.tsserver.setup({
  capabilities = caps,
  on_attach = no_format
})

-- Rust
lspconfig.rust_analyzer.setup({
  capabilities = snip_caps,
  on_attach = no_format
})

-- Emmet
lspconfig.emmet_ls.setup({
  capabilities = snip_caps,
  filetypes = {
    "css",
    "html",
    "javascriptreact",
    "less",
    "sass",
    "scss",
    "typescriptreact",
  },
})

The capabilities option was used to add snippets and code suggestions based on the programming language. The servers setup above were Pyright for Python, PhpActor for PHP, TSServer for Javascript/TypeScript, Rust Analyzer for Rust and Emmet to make HTML and CSS/Sass authoring more supportable.

Language servers must also have their executables present on the machine to work. Fortunately, the Neovim LSP Installer extension helps with this. Just run the command :LSPInstallInfo and a list of several servers will appear.

LSP Installer dialog

To install, just press i on the desired server name.
To update, press u. For uninstalling, press x. Everything is very visual, and if you get lost, just press ? to access help.

Why not CoC?

Despite being very useful and much simpler to configure, it is slower. Before writing this article I used it daily, and Neovim with LSP configured in Lua proved to be much snappier.

Probably, the fact that CoC is done in TypeScript and VimScript, languages slower than Lua, are the cause of this.

Keyboard shortcuts

Nothing new here. In the same way I did with the options at the beginning of the article, I placed the functions with less readable names in local variables with names similar to those used in VimScript.



---------------------------------
-- Key bindings
---------------------------------
local map = vim.api.nvim_set_keymap
local kmap = vim.keymap.set
local opts = { noremap = true, silent = true }

-- Leader
vim.g.mapleader = " "

-- Vim
map("n", "<F5>", ":Neotree toggle<CR>", opts)
map("n", "<C-q>", ":q!<CR>", opts)
map("n", "<F4>", ":bd<CR>", opts)
map("n", "<F6>", ":sp<CR>:terminal<CR>", opts)
map("n", "<S-Tab>", "gT", opts)
map("n", "<Tab>", "gt", opts)
map("n", "<silent> <Tab>", ":tabnew<CR>", opts)
map("n", "<C-p>", ':lua require("telescope.builtin").find_files()<CR>', opts)

-- Diagnostics
kmap("n", "<space>e", vim.diagnostic.open_float, opts)
kmap("n", "[d", vim.diagnostic.goto_prev, opts)
kmap("n", "]d", vim.diagnostic.goto_next, opts)
kmap("n", "<space>q", vim.diagnostic.setloclist, opts)

local on_attach = function(client, bufnr)
  -- Enable completion triggered by <c-x><c-o>
  vim.api.nvim_buf_set_option(bufnr, "omnifunc", "v:lua.vim.lsp.omnifunc")

  -- Mappings.
  local bufopts = { noremap = true, silent = true, buffer = bufnr }
  kmap("n", "gD", vim.lsp.buf.declaration, bufopts)
  kmap("n", "gd", vim.lsp.buf.definition, bufopts)
  kmap("n", "K", vim.lsp.buf.hover, bufopts)
  kmap("n", "gi", vim.lsp.buf.implementation, bufopts)
  kmap("n", "<C-k>", vim.lsp.buf.signature_help, bufopts)
  kmap("n", "<space>wa", vim.lsp.buf.add_workspace_folder, bufopts)
  kmap("n", "<space>wr", vim.lsp.buf.remove_workspace_folder, bufopts)
  kmap("n", "<space>wl", function()
    print(vim.inspect(vim.lsp.buf.list_workspace_folders()))
  end, bufopts)
  kmap("n", "<space>D", vim.lsp.buf.type_definition, bufopts)
  kmap("n", "<space>rn", vim.lsp.buf.rename, bufopts)
  kmap("n", "<space>ca", vim.lsp.buf.code_action, bufopts)
  kmap("n", "gr", vim.lsp.buf.references, bufopts)
  kmap("n", "<space>f", vim.lsp.buf.formatting, bufopts)
end

Final details

One thing I hated as soon as I started using this setup was errors in virtual text on the same line. The error message is never concise enough to fit on the screen, and in the case of multiple occurrences, the readability is greatly affected.

Errors in virtual text

With the code below, errors appear in floating boxes when holding the cursor over the error.



---------------------------------
-- Floating diagnostics message
---------------------------------
vim.diagnostic.config({
  float = { source = "always", border = border },
  virtual_text = false,
  signs = true,
})

---------------------------------
-- Auto commands
---------------------------------
vim.cmd([[ autocmd! CursorHold,CursorHoldI * lua vim.diagnostic.open_float(nil, {focus=false})]])

Floating box error

If this doesn't bother you, just ignore this part.

Wrap up

Done! These lines are enough to have a working Neovim with a configuration file in Lua.

If you followed exactly what was shown so far, your init.lua ended up with about 380 lines, much more than the VimScript version (154 lines, adding init.vim and coc-settings.json).

To be honest, I thought it would be more than 500 lines, but I managed to reduce it a lot. The fact that I did it in a single file contributed to this, encouraging me to keep only the essentials. I did it that way too, because until the moment where I write these lines, I haven't found a tutorial that uses only one file. Usually, folders and folders with several Lua files are created in the process, which cause a lot of confusion in the beginning.

For the more experienced, obviously this configuration does not suit everything, but in my case, I was very satisfied with the result. In the next article, this file will be splitted into "modules", to improve the extensibility of this configuration.

If you want to check out the complete code, there's a link to my .dotfiles repository below.

See you!

Links

If this article helped you in some way, consider donating. This will help me to create more content like this!

Styling scrollbars with CSS

Elves Sousa — Tue, 05 Apr 2022 22:12:26 +0000

CSS Scrollbars is something highly overlooked in CSS. Usually, they are not even present in layouts for approval, and if they do, they will probably only be noticed when they are very eccentric. After all, a good scrollbar is one that is not noticed.

However, customizing them can give a small gain in the experience of your website or app, especially if you have some content that is bigger than the element it contains. Standard browser or operating system scrollbars are not always going to be aesthetically pleasing.

In this article, I give a little tip on how to implement custom scrollbars on any website, using only CSS.

Browser engines and limitations

There is not a standard way to style the scrollbars yet, as browsers have not reached a consensus on the best way to achieve this goal. Currently, there are only three HTML engines on the market: Webkit, Blink and Gecko.

Webkit e Blink engines

Since Blink is a derivative of Webkit, the method used to style the scrollbars is the same. Safari, Gnome Web, and other lesser-known browsers use Webkit; Google Chrome and its derivatives Brave, Opera, Vivaldi and Edge all use Blink. This means that by using this method, you will cover more than 90% of the users.

This method uses CSS pseudo-elements to represent the different parts. They are not present in standard CSS specification, so -webkit- browser prefixes are required.

Here are elements:

::-webkit-scrollbar: represents the "body" of the bar, usually used to define general aspects such as width and height.
::-webkit-scrollbar-track: the scrollbar track.
::-webkit-scrollbar-thumb: the handle itself.

There are others pseudoelements besides these, but their use is very specific and generally unnecessary. Below is an example of the code, for a very discreet scrollbar.

.element::-webkit-scrollbar {
  width: 3px;
  height: 3px; /* The height is only seen on horizontal scrolling */
}

.element::-webkit-scrollbar-track {
  background: transparent;
  padding: 2px;
}

.element::-webkit-scrollbar-thumb {
  background-color: #000;
}

Although customization with this method is quite powerful, W3C, the institution responsible for internet standards, abandoned this specification. In the future, it will be discontinued.

Gecko

Gecko is the rendering engine used by Firefox and its derivatives Librewolf, TOR Browser, SeaMonkey, Waterfox and IceCat. Unlike Webkit and Blink based browsers, Gecko follows the W3C specifications. Instead of using pseudo-elements, normal CSS rules are used for this purpose.

Here are the rules:

scrollbar-width: well... width or height of the scrollbar.
scrollbar-color: colors of the scrollbar thumb (first one) and track (second one).

.element {
  scrollbar-width: thin;
  scrollbar-color: black transparent;
}

This method is much more elegant, but less powerful. It is important to note that no browser fully implements this specification. If you wish to use these rules in Webkit-based browsers, the prefix -webkit- must be used.

Wrap up

While the specification doesn't mature, your CSS styling should incorporate both methods. With that, the final code will look like this:

.element {
  scrollbar-width: thin;
  scrollbar-color: black transparent;
}

.element::-webkit-scrollbar {
  width: 3px;
  height: 3px; /* The height is only seen on horizontal scrolling */
}

.element::-webkit-scrollbar-track {
  background: transparent;
  padding: 2px;
}

.element::-webkit-scrollbar-thumb {
  background-color: #000;
}

Remember that to see the scrollbar in elements, the overflow[-x/-y]: scroll rule must be set.

See you in the next article!

Links

If this article helped you in some way, consider donating. This will help me to create more content like this!

My basic Neovim setup

Elves Sousa — Tue, 09 Nov 2021 19:24:01 +0000

In the last few articles, I commented on why I adopted Neovim as my main editor and went through the basics for using the program. However, it does not come with plugins or nice looks by default. Here, I show you how I set up my Neovim.

The programming languages I use in my daily life are JavaScript (JSX and TypeScript), CSS, Sass and lately I'm studying Python, too. Therefore, my configuration supports these technologies.

Neovim as is on first launch

About my choices for the configuration

As you can imagine, Neovim is configured by text files.

There are two ways to configure it: using the Lua language, or VimScript, created for Vim. Here I will use the last one, as it works for both Vim and Neovim. So I kill two birds with one stone.

I have no experience with Lua, and at the moment I have no plans on learning the language just to configure the application. I'm aware that there are more modern ways to do this, but I prefer to keep my settings concise.

At the end of this guide, you will not have a tangle of files and directories, as you may have seen elsewhere, but rather a single file, just enough for comfortable use.

Setting options

As with most software, there is a way to edit options and preferences. These can be tested with the command :set <option-name>. Try opening an instance of Vim/Neovim now and type :set number, you'll notice that the line numbers will appear on the side. The problem with this is that these commands will have to be repeated each time you reopen the program.

Saving settings

To keep these settings saved, just write these commands in a file in your user folder. The name and location will vary depending on whether you use Vim or Neovim:

Vim: <username>/.vimrc
Neovim: <username>/.config/nvim/init.vim

If these files/directories do not exist in your home folder, just create them manually. Remember that files starting with "." are hidden by default on Unix systems (Linux, BSDs and macOS). Make sure you are showing hidden files in your file manager or terminal.

Basic options in the configuration file

Before we get into more complex things like extensions and their settings, let's stick to the basics. There are many options to tinker with, however, the ones I put below are the ones I currently use. Note that in the file will have the commands that would have to be typed every time the editor opened.



" Options
set background=dark
set clipboard=unnamedplus
set completeopt=noinsert,menuone,noselect
set cursorline
set hidden
set inccommand=split
set mouse=a
set number
set relativenumber
set splitbelow splitright
set title
set ttimeoutlen=0
set wildmenu

" Tabs size
set expandtab
set shiftwidth=2
set tabstop=2

Here is the explanation of each command above:

background=dark: apply the color set for dark screens. Not just the background of the screen, as it might look.
clipboard=unnamedplus: enables the clipboard between Vim/Neovim and other applications.
cursorline: highlights the current line in the editor.
completeopt: modifies the auto-complete menu to behave more like an IDE.
hidden: hide unused buffers¹.
inccommand=split: show replacements in a split screen, before applying to the file.
mouse=a: allows the use of the mouse in the editor.
number: shows line numbers.
relativenumber: show line numbers starting from the current one. Useful for using multiline commands.
splitbelow splitright: changes split screen behavior with the command :split (split horizontally) and :vsplit (vertically). In this case, the screens will always split below the current screen and to the right.
title: show the file title
ttimeoutlen=0: time in milliseconds to run commands.
wildmenu: shows a more advanced menu for auto-completion suggestions.
expandtab: transforms tabs into spaces.
shiftwidth=2: number of spaces for indentation.
tabstop=2: number of spaces for tabs.

Syntax

To add automatic syntax support for open files:



filetype plugin indent on
syntax on

Color support

To enable 256 colors on the terminal:



set t_Co=256

Below is a logic I made for Vim to detect if the system supports a greater number of colors. Note that I made a conditional to detect if the terminal emulator is Apple's one. For some reason the colors behave differently in the versions I used.



" True color if available
let term_program=$TERM_PROGRAM

" Check for conflicts with Apple Terminal app
if term_program !=? 'Apple_Terminal'
    set termguicolors
else
    if $TERM !=? 'xterm-256color'
        set termguicolors
    endif
endif

If you don't use the Apple terminal, ignore that part and just add the code inside the else.

Support for true italics

If you're like me and like fonts with true italic support, add these lines:



" Italics
let &t_ZH="\e[3m"
let &t_ZR="\e[23m"

Don't ask me what these codes there mean. All I know is that a terminal with italic support will recognize them as italic.

NetRW: Vim's default file manager

Notice: If you already know a little about Vim and are not interested in NetRW, skip this part.

NetRW as it is

If you've ever used an IDE in your life, you might have noticed that there's always a tree on the side with the project files. Vim/Neovim use NetRW by default, which brings this same function.

When opening Vim or Neovim using the [n]vim . command to open the project directory, the file listing will appear inside it. It can also be opened using the :Ex ,:Vex or :Sex commands.

You can use it with the default settings, but personally, some things bother me, so I used the following settings:



" File browser
let g:netrw_banner=0
let g:netrw_liststyle=0
let g:netrw_browse_split=4
let g:netrw_altv=1
let g:netrw_winsize=25
let g:netrw_keepdir=0
let g:netrw_localcopydircmd='cp -r'

Here's the explanation:

g:netrw_banner=0: hides the top banner that appears by default.
g:netrw_liststyle=0: change the display of files.
- 0 shows only one directory at a time.
- 1 shows file data.
- 2 shows files in columns.
- 3 shows as a tree where open directories are expanded.
g:netrw_browse_split=4: changes how files are opened.
- 1 opens files in a horizontal split.
- 2 opens in a vertical split.
- 3 opens in a new tab.
- 4 opens in a previous window, avoiding the creation of more divisions.
g:netrw_altv=1: switches the NetRW display to the left.
g:netrw_winsize=25: limits window size to 25% of available screen space.
g:netrw_keepdir=0: keeps the directory you accessed previously.
g:netrw_localcopydircmd: modifies the command used to copy files. By default, NetRW just copies empty folders. To change this, I set the default command to cp -r so that the copy occurs recursively.

To make creating files easier, I've added more settings:



" Create file without opening buffer
function! CreateInPreview()
  let l:filename = input('please enter filename: ')
  execute 'silent !touch ' . b:netrw_curdir.'/'.l:filename
  redraw!
endfunction

" Netrw: create file using touch instead of opening a buffer
function! Netrw_mappings()
  noremap <buffer>% :call CreateInPreview()<cr>
endfunction

augroup auto_commands
    autocmd filetype netrw call Netrw_mappings()
augroup END

This prevents NetRW from opening an empty screen just to create a file.

If you want to use NetRW, I believe this is the minimum needed to use it comfortably.

NetRW and its problems

There are several criticisms of NetRW for the way it causes a buffer mess. From what I've researched, it seems that using g:netrw_liststyle=3 tree mode tends to make this behavior worse. Errors are random, making fixing it a difficult process, and updating only NetRW is more complex than it should be.

That's why there are several alternatives to NetRW, and the most famous one is NERDTree, which I use in my main configuration.

Plugins

Neovim using the tweaks we made so far

Plugin manager setup

Finally, it's time to configure the plugins. Unlike VS Code or other editors, there are several options for extension installers: Neobundle, Vundle, Vim-Plug, etc. Here I will use the last one, which seems to be the most used nowadays. To install it, open a terminal and run the following command:

For Vim:



$ curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
    https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

For Neovim:



$ sh -c 'curl -fLo "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/autoload/plug.vim --create-dirs \
       https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim'

These commands above do all the necessary to have Vim-Plug available in your editor.

Installing plugins

Vim-Plug reads a part of your configuration file to find the extension in Github and install it in the editor. This part is delimited by the following structure:



call plug#begin()
    Plug '<github-user>/<repo-name>'
call plug#end()

You can add multiple extensions at once, just add multiple Plug as desired. There is a website that catalogs these plugins for easy discovery, if you want to visit. It's called Vim Awesome. The link is at the end of the article.

Plugins I use

Here's what I use on my Vim/Neovim:



call plug#begin()
    " Appearance
    Plug 'vim-airline/vim-airline'
    Plug 'ryanoasis/vim-devicons'

    " Utilities
    Plug 'sheerun/vim-polyglot'
    Plug 'jiangmiao/auto-pairs'
    Plug 'ap/vim-css-color'
    Plug 'preservim/nerdtree'

    " Completion / linters / formatters
    Plug 'neoclide/coc.nvim',  {'branch': 'master', 'do': 'yarn install'}
    Plug 'plasticboy/vim-markdown'

    " Git
    Plug 'airblade/vim-gitgutter'
call plug#end()

Vim Airline: modifies the status bar to make it more pleasant than the default one.
Vim Devicons: shows icons in the interface, based on icon fonts².
Vim Polyglot: syntax highlighting for several programming languages.
Auto Pairs: automatically closes parentheses, square brackets and braces when typing.
Vim CSS Color: shows colors (hex, RGB, HSL) directly in the code.
NERDTree: sidebar to access project files. Replaces the NetRW I mentioned earlier.
CoC (Conquer of Completion): provides auto-completion, very similar to what is available in VS Code. I'll go into details about it later.
Vim Markdown: better support for Markdown file syntax.
Vim GitGutter: Shows Git changes in open files.

Writing these lines with addresses is not enough to install extensions. First, you must save the configuration file and restart Vim in order for the editor to comply with the newly added settings. After that, run the :PlugInstall command.

Vim Plug

A window will open and show the installation process for each extension. After installation, you will have to restart Vim one more time to use the new extensions.

To uninstall, remove the line of the plugin you want to get rid of from the configuration file and after restarting the editor, run the command :PlugClean.

Color schemes

If there's something critical to a good development experience, it's a good color scheme. These are installed in the same way as extensions.

First, add the line with the path to the theme's Github repository:



call plug#begin()
    Plug 'morhetz/gruvbox'
call plug#end()

To use the theme, add the command colorscheme gruvbox in the configuration file. This will be enough to get rid of that black screen and stark colors that come by default.

Color scheme I use

Sobrio: the theme I use in my daily life

Despite setting the example with the GruvBox theme, this is not the theme I use. Color schemes are very subjective things and as I used this theme, I ended up getting a little bored with it. The same happened with others. Since I couldn't find one I liked, I made my own. It's called Sobrio. If you want to test it, just follow the same recipe above, changing only the repository:



call plug#begin()
    Plug 'elvessousa/sobrio'
call plug#end()

Then just add colorscheme sobrio and restart the editor. Please feel free to leave your comment and suggestion about it. I would like to know your opinion. If you want to know more about it, the link for the website is at the end of the article.

Plugins configuration

Devicons

Devicons is an extension that adds icons to Vim's interface. In order to work, it is necessary to have fonts with icon support installed on the system.

Look for "NERD Fonts" on the internet, and you'll find plenty of them. The way to install fonts on the system varies a lot depending on the operating system, and I won't go into details here. Download it, install and apply the font for your terminal emulator. Other than that, no other configuration is required.

Airline

Little to set up here. Basically it's saying which theme to use and if you want to use "Powerline" mode, which are these lines with arrow shapes.



let g:airline_theme='sobrio'
let g:airline_powerline_fonts = 1
let g:airline#extensions#tabline#enabled = 1

The last option above shows enables Airline for the tab bar.

NERDTree

NERDTree is the replacement for NetRW. By default, it works fine. I just added a line to show hidden files by default.



" File browser
let NERDTreeShowHidden=1

You know, I like to see .env or .gitignore files without having to type I first.

Neovim com as configurações até agora

CTRLP

This plugin enables file search in your project's folder. It is activated by the same keyboard shortcut that gives its name. If you've ever used VS Code, you will get used to it very quickly. The only setting I made was this one:



let g:ctrlp_user_command = ['.git/', 'git --git-dir=%s/.git ls-files -oc --exclude-standard']

Putting the line above into plain English: CTRLP will ignore every file or directory mentioned inside your project's .gitignore file.

Vim Markdown

If you don't use Markdown, skip this part.

As I use the Markdown format a lot to write on my blog, I installed this extension to improve the display of this type of file on my Neovim.



" Disable math tex conceal feature
let g:tex_conceal = ''
let g:vim_markdown_math = 1

" Markdown
let g:vim_markdown_folding_disabled = 1
let g:vim_markdown_frontmatter = 1
let g:vim_markdown_conceal = 0
let g:vim_markdown_fenced_languages = ['tsx=typescriptreact']

I use YAML headers (Frontmatter) at the top so that Gatsby does its magic. Without this plugin the frontmatter and code blocks syntax is not recognized.

Coc: Conquer of Completion

This is the plugin that requires the most configuration. Conquer of Completion works as a server that provides auto-completion and code correction tools, working similar to VS Code. It supports extensions too, and these are responsible for adding support for the desired programming languages.

The weakness of CoC is that it is based on NodeJS, so the dependencies of installed packages will take up a certain amount of disk space, like all Node projects. Of the ones I've tested so far, it has met my expectations the most, with the least configuration.

Installing extensions is simple: just run the command :CocInstall <extension-name> and the features will be available for you to use.

Here are the extensions I use:

coc-tsserver: support for JavaScript, TypeScript and React.
coc-css: support for CSS, Sass and SCSS.
coc-eslint: lints JavaScript and TypeScript files.
coc-emmet: adds shortcuts to write less in HTML, CSS, Sass, SCSS and extended JavaScript files (JSX,TSX)
coc-pyright: Python support.
coc-prettier: formats the code according to well accepted standards in the community.

To install them all at once, just run the command:



:CocInstall coc-tsserver coc-css coc-eslint coc-emmet coc-pyright coc-prettier

Prettier with coc-prettier



" Language server stuff
command! -nargs=0 Prettier :call CocAction('runCommand', 'prettier.formatFile')

The command above will run Prettier and format the file whenever you save the file. This helps a lot, as I spend less time pressing Tab to indent code.

Coc settings in JSON

Apart from the init.vim or .vimrc we've used so far, I also use a separate file called coc-settings.json. With it it is possible to modify the behavior of your extensions.



{
  "coc.preferences.formatOnSaveFiletypes": [
    "css",
    "sass",
    "scss",
    "markdown",
    "html",
    "json",
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "python"
  ],
  "python.formatting.provider": "black",
  "python.formatting.blackPath": "~/.local/bin/black",
  "prettier.singleQuote": true,
  "javascript.autoClosingTags": true,
  "typescript.autoClosingTags": true,
  "emmet.includeLanguages": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "html"
  ],
  "codeLens.enable": false
}

Here is the explanation of the settings above:

Configure CoC to format some file types when saving.
Configure Prettier to prefer single quotes in formatting.
Inform which code formatter for python, "black" in this case, and passed the path to black on my system.
Enable auto-close for extended JavaScript tags (JSX)
Enable Emmet for more file formats.
Disable Code Lens, as it crashed occasionally.

Note that if you don't use Python, just ignore the settings for it. For the Python formatter to work, it must be installed on the system:



$ pip install black

Keyboard shortcuts

As with other programs, there is a way to configure keyboard shortcuts. This can be done for each editor mode. The possibilities are many. To add a keyboard shortcut in Vim, just add the expression:



[first-letter-of-target-mode]noremap <key-or-letters> :Command

The strange word noremap comes from "Non Recursive Mapping", "Non-Recursive Mapping". This means that the created shortcut will not overwrite another similar shortcut, avoiding conflicts.

As I'm a bit minimalist, I didn't add many shortcuts.



" Normal mode remappings
nnoremap <C-q> :q!<CR>
nnoremap <F4> :bd<CR>
nnoremap <F5> :NERDTreeToggle<CR>
nnoremap <F6> :sp<CR>:terminal<CR>

" Tabs
nnoremap <S-Tab> gT
nnoremap <Tab> gt
nnoremap <silent> <S-t> :tabnew<CR>

Here is the explanation of the above mappings:

Ctrl+q: closes the open screen.
F4: closes the open file.
F5: shows or hides NERDTree.
F6: opens a terminal in a lower split window.
Shift+Tab: switch to the previous tab.
Shift+t: creates a tab.
Tab: switch to the next open tab.

Note that there are several <CR>. These represent all the times you would have to press Enter in command mode. CR is the abbreviation for "Carriage Return": a term from the time when typewriters were used. Today, we understand it as the Enter or Return key.

All shortcuts I used are for normal mode, so nnoremap is on every line. If it was for insert mode it would be inoremap, vnoremap for visual mode and so on.

Automatic commands

To automate some things, Vim makes it possible to define what it calls autocmd: automatic commands performed on certain events.



" Auto Commands
augroup auto_commands
    autocmd BufWrite *.py call CocAction('format')
    autocmd FileType scss setlocal iskeyword+=@-@
augroup END

Above, I defined two actions: one to format the Python code when saving the file, and another to resolve an inconsistency I had with SCSS files.

Wrap up

Without a doubt, this was the longest article I've made so far, but if you followed the instructions, you have a very functional editor now. There are other plugins, but as you get used to it and build confidence, you will test out others better suitable for your needs.

Ideally, try to keep the init file simple. Too much extensions can affect performance. I use other settings that I haven't detailed in this article, as they are not important for most cases. I'm providing the link to my dotfiles repository for you to check at the end of this article if you want.

See you in the next article!

Vim basics for beginners

Elves Sousa — Tue, 12 Oct 2021 20:53:17 +0000

In the first part of this series, I told why I've switched from VS Code to Neovim, but I didn't go deep into how differently Vim works. In this article I write more about these aspects.

How Vim edits texts

In other editors, you just click and start writing. To save a file, just choose "save" on the menu or using the corresponding keyboard shortcut for the action.

This is completely different in Vim: the program begins in a quick edits mode, which does not enable writing text. This mode accepts navigation and commands to change text. To do this, commands are used, which can be simple as a shortcut key, or compound, where more keys are used to achieve a certain action.

For those who have never used it, this sounds very difficult and intimidating, but it is not. With practice, you get used to it and see the advantages.

Normal mode

This is the editor's default mode. To access it, always use the ESC key.

Navigation through text

Navigation works as in most editors, arrow keys to move the cursor on the screen, Pageup orPagedown to move between "pages", Home or End to go to the beginning or end of a line. Beside these shortcuts, there are others made just pressing normal keys like letters and symbols. Here are some of them:

Simple commands:

g: moves the cursor to the end of the file.
L: moves the cursor to the end of the screen. L comes from the word Low.
M: moves the cursor to the middle of the screen. M comes from the word Middle.
H: moves the cursor to the beginning of the screen. Note that this is not necessarily the beginning of the file. H comes from the word High.
0: moves the cursor to the beginning of the line.
w: moves the cursor to the beginning of the next word.
b: moves the cursor to the beginning of the previous word.
e: moves the cursor to the end of the next word.
J: joins lines.
%: shows the corresponding scope, inside parentheses, brackets or keys.
.: repeats any operation done earlier.

Compound commands:

gg: moves the cursor at the beginning of the file.
number + g: goes to a specific line. Ex.: 23g goes to line 23 of the document.
f + character: moves the cursor to the next occurrence of the chosen character. Ex: f( moves cursor to the next (.
Number + w,b or e: move the cursor to the beginning/final of the nth word after the current position. Ex: 2w moves the cursor to the beginning of the second word.

Text editing

Simple editing can be made in this mode.

Simple commands:

x or delete: clears the character under the cursor.
u: undoes latest changes.
r: replaces the character under the cursor by the next that will be typed.

Compound commands: removing content

To delete content, use the d key; it works likes cutting in other editors. The way it will be deleted/cut will depend on the next letter typed:

d: delete "the entire line. dd equals Ctrl + X in VS Code.
Number + d: remove multiple lines. 2134dd will erase 2134 lines.
w: clears until the end of the word.
Number + w: deletes certain number of words. Ex.: d2w erases two words.
i + character: removes the content delimited by a character. Ex.: di{ removes content between keys. An easy way to understand this is to remember the phrase "delete inside {".
i + w: clears the whole word.
i + t: removes everything inside an HTML tag.
t + character: removes content till a particular character. Ex.: dt. removes content to the next full stop. Remember the expression "delete till .".
$: clears from where the cursor is up till the end of the line. The D shortcut has the same effect.

Compound commands: copying

Copy works basically in the same way as removal. The command used for copying is y, which comes from the word yank. The same key combinations used for deleting work here, but applied to copy content:

y: Copies the entire line. yy is equivalent to Ctrl + C in VS Code.
Number + y: Copies several lines. Ex.: 1873yy copies 1873 lines.

And so on, you got the idea.

Pasting content

To paste the content, use the p key. It is worth mentioning that all deleted content is in the clipboard. Using p, will paste after the cursor and using P it will paste before the cursor.

Insert mode

In this mode everything is quite familiar as it is like every other editor. There are several ways to access the mode to write text:

i: opens insertion mode and moves the cursor before the current character.
a: opens insertion mode and moves the cursor after current character.
s: opens insertion mode and erases the character under the cursor.
i: moves the cursor at the beginning of the line to insert content.
A: moves the cursor at the end of the line to add content.
o: adds a line below the cursor and enter the insert mode.
O: adds a line above the cursor and enter the insert mode.

Compound commands: changing content

Another way to enter the insertion mode is to use the c command, for change. This follows the same pattern of previously described for removal and copy commands. It clips the content and opens the mode for insertion, very practical. For example, imagine that we have the following HTML markup:

<p class="random-latin-text">
  Lorem ipsum dolor sit amet, consectetur <strong>adipiscing elit</strong>.
  Quisque eget lobortis velit. Maecenas nec molestie eros, eu efficitur erat.
  Nunc nec congue justo, et commodo dolor. Aliquam <em>facilisis</em> urna eget
  massa pulvinar, in bibendum ante convallis.
</p>

Just position the cursor in the markup and type cit. The result will be like this:

<p class="random-latin-text">|</p>

The "|" above represents where the cursor will be, ready to enter new text.

Replace mode

This mode is basically the same as pressing the Insert key: the typed text overwrites the previous one. It is accessed by the R shortcut.

Visual mode

This mode enables text selection. It's activated by the v key. To select the text, just use the arrow keys. Clicking with the right mouse button also activates the mode, in case it is configured.

Commands made after visual mode will only affect the selected area.

Command mode

This mode is one of the most used, because it is the equivalent of a toolbar. With it we can save the file a file, for example. It is activated by the key :. From there just write the command desired and press Enter. Below are some examples:

w orwrite: saves the current file.
q orquit: closes the file. Add ! to force quit if it complains of changes not saved.
x or wq: saves and closes the file.
h orhelp: shows the help screen.
s: enter find/replace mode from the current line. Ex.: s/rong/right 'will replace the word "rong" for "right". s/rong/right/g does the same thing, in all occurrences on the line. s/rong/right/g 8 make replaces the words in all occurrences for the next 8 lines.

Curiosities

Arrow keys

Despite being able to use the directional normally, Vim encourages the use of the h, j,k and l keys to move the cursor to the left, low, up and right, respectively. This is due to the fact that the computer used at the time by the Vi developer used a keyboard in which the directional were on that keys.

ADM 3A Keyboard

Some aficionados abhor the use of arrow keys. In fact, if you get used to it, you can be very productive, because the keys are closer. Personally, I don't use this.

ESC key

On the same keyboard above, the Esc was almost in the same position as the Caps Lock key. Upon knowing of this, you see the choice was not so strange, as the position of the Caps Lock key is much more comfortable than that of the current Esc. You can configure the editor to do that. I didn't do it myself.

Here I end this article! I can't teach everything, unfortunately: I don't know everything about it and a blog article is not enough for this purpose. Despite this, I believe this is the basics for you to start using this "scary" editor.

I suggest that as homework, use the "Vim Tutor": it is a command available at the terminal as soon as Vim is installed on the system. When writing vimtutor in the terminal, an instance of Vim opens without any plugins loaded, with a nice text that teaches more deeply every command I quoted here, with practical exercises.

In the next article, I will teach you how to make Vim more useful and beautiful. Because let's get real, it is really ugly and empty at first.

See you later!

Links

If this article helped you in some way, consider donating. This will help me to create more content like this!

Creating a link with an active state in Next.js

Elves Sousa — Fri, 01 Oct 2021 20:52:19 +0000

There is something that, at the moment I write these lines, still lacks in Next.js: a component <Link /> showing a different class while the page is being visited.

Why use the link if you can use normal anchors?

Before continuing, a small pause, to see why using <Link /> instead of an <a>.

Basically, every time you use a normal anchor, the page makes a full refresh. The <Link /> component changes this behavior by loading only what changes on the screen, avoiding unnecessary rendering and making the experience faster and smoother. This is just for internal links; for the external ones, the anchor is enough.

React and Gatsby projects

In a React (CRA) project, this already comes by default with the React Router DOM library: just import a component <Link /> that comes with it, and add the activeClassName attribute, informing a CSS class for the active state of that anchor.

import { Link } from "react-router-dom"

export function Nav() {
  return (
    <nav>
      <Link to="/" activeClassName="active">
        Home
      </Link>
      <Link to="/blog" activeClassName="active">
        Blog
      </Link>
      <Link to="/about" activeClassName="active">
        About
      </Link>
    </nav>
  )
}

In Gatsby, another framework for creating static pages in React, the same can be achieved through the Gatsby library.

import { Link } from "gatsby"

export function Nav() {
  return (
    <nav>
      <Link to="/" activeClassName="active">
        Home
      </Link>
      <Link to="/blog" activeClassName="active">
        Blog
      </Link>
      <Link to="/about" activeClassName="active">
        About
      </Link>
    </nav>
  )
}

However, in Next.js, for some reason I don't know yet, the implementation of the <Link /> component is quite different: a child element is required and there are no to and activeClassName properties.

import Link from "next/link"

export function Nav() {
  return (
    <nav>
      <Link href="/">
        <a>Home</a>
      </Link>
      <Link href="/blog">
        <a>Blog</a>
      </Link>
      <Link href="/about">
        <a>About</a>
      </Link>
    </nav>
  )
}

It is a good implementation, meets multiple needs, but still lacks support for a class for the active state, as seen in previous examples.

How to bring activeClassName support to Next.js

Let's now create the <ActiveLink />: a component which will have the active class support. Here, the code is in typescript, but if your project uses JavaScript, the code works as well: just remove the typing. The component has only the required code for this feature to work.

First, we create the basic structure:

import { useRouter } from "next/router"
import Link from "next/link"

export function ActiveLink() {
  const { asPath } = useRouter()

  return <Link>...</Link>
}

The "hook" function useRouter is imported from Next.js, so that our component has information for the current route. This hook has the asPath property, which informs the current path of the page.

After this, let's create the properties of our component:

import { ReactElement } from "react"
import { useRouter } from "next/router"
import Link, { LinkProps } from "next/link"

type ActiveLinkProps = {
  children: ReactElement
  activeClassName: string
}

export function ActiveLink({ children, activeClassName }: ActiveLinkProps) {
  const { asPath } = useRouter()

  return <Link>{children}</Link>
}

Here, I use the ActiveLinkProps type to inform the properties that the component will accept:

children: It is a ReactElement type, that is, accepts a single React element as a parameter. If a ReactNode or JSX.Element type is used, it works as well, but as we will only have one element as child, is better to ReactElement.
activeClassName: With the 'string' type, as a simple text is enough to enter the name of a valid CSS class.

The problem is that at this time, the component doesn't have access to the properties of a normal <Link />. To do this, you need to extend the ActiveLinkProps type. Without these properties, the component will not work as a real replacement to the Next.js default link. Thus, it is necessary to import the Linkprops definition that comes with next/link:

import Link, { LinkProps } from "next/link"

After this, we make ActiveLinkProps aware of LinkProps type properties.

...

type ActiveLinkProps = LinkProps & {
  children: ReactElement
  activeClassName: string
}

...

Inside the component, an argument is then added to the function with the spread operator¹, so that all the native properties of the Next.js link can be accessed and passed on to the returned component in the function.

import { ReactElement } from "react"
import { useRouter } from "next/router"
import Link, { LinkProps } from "next/link"

type ActiveLinkProps = LinkProps & {
  children: ReactElement
  activeClassName: string
}

export function ActiveLink({
  children,
  activeClassName,
  ...rest
}: ActiveLinkProps) {
  const { asPath } = useRouter()

  // The "...rest" represents all properties coming from LinkProps
  return <Link {...rest}>...</Link>
}

Now just make a conditional that verifies if the current route is the same as the "href" of the component.

const className = asPath === rest.href ? activeClassName : ""

If true, the class informed in activeClassName will be used.

Applying className in children components

Next.js' default implementation of <Link /> doesn't accept a className property. This should be passed on to a child element, otherwise it will not work:

<Link href="/">
  <a className="meuLink">Home</a>
</Link>

Therefore, to pass the property the correct way, we need to use the React.cloneElement()² method to clone the child element, and passing className to it.

The final code will look like this:

import { cloneElement, ReactElement } from "react"
import { useRouter } from "next/router"
import Link, { LinkProps } from "next/link"

type ActiveLinkProps = LinkProps & {
  children: ReactElement
  activeClassName: string
}

export function ActiveLink({
  children,
  activeClassName,
  ...rest
}: ActiveLinkProps) {
  const { asPath } = useRouter()
  const className = asPath === rest.href ? activeClassName : ""

  return <Link {...rest}>{cloneElement(children, { className })}</Link>
}

One more thing...

If you're not like me, maybe you noticed I forgot something: the className in the child element gets replaced by activeClassName when the route is active (thanks Lyrod for your insights). In many cases it will work properly, but if you need to have two classes in the same element like "mylink active", then this will not be enough.

To solve this little issue, we need to get the current child element's className first. This can be achieved by using children.props.className. After that, we merge it with activeClassName:

const childClassName = children.props.className
const newClassName = `${childClassName} ${activeClassName}`

The code above will print an undefined if children.props.className is not present. The same will happen with activeClassName. To get rid of these, we use the nullish coalescing operator ??³ to save a couple of "ifs".

const childClassName = children.props.className ?? ""
const newClassName = `${childClassName} ${activeClassName ?? ""}`

Now we just have to update the conditional to include this newClassName variable I came up with:

const className = asPath === rest.href ? newClassName.trim() : ""

The trim() part will eliminate spaces left when one of the classes is not available.

So, the real final code looks like this now:

import { cloneElement, ReactElement } from "react"
import { useRouter } from "next/router"
import Link, { LinkProps } from "next/link"

type ActiveLinkProps = LinkProps & {
  children: ReactElement
  activeClassName: string
}

export function ActiveLink({
  children,
  activeClassName,
  ...rest
}: ActiveLinkProps) {
  const { asPath } = useRouter()
  const childClassName = children.props.className ?? ""
  const newClassName = `${childClassName} ${activeClassName ?? ""}`
  const className = asPath === rest.href ? newClassName.trim() : ""

  return <Link {...rest}>{cloneElement(children, { className })}</Link>
}

That's all folks!

Why I switched from VSCode to Neovim

Elves Sousa — Mon, 20 Sep 2021 19:59:18 +0000

Long time no see, but I'm back. I had a lot of things to deal with, that prevented me from writing here in the frequency I'd like. But without further ado, let's talk about the theme: Vim/Neovim and the VSCode.

There is a certain bad fame that surrounds Vim or its more modern variant, Neovim. For being an old program that runs at the terminal, one who sees it and compares with the most beloved editor of the moment - VS Code - soon thinks: "How can someone with some self-love would want to deal with this stuff? It is ugly and hard to use, and when I tried to quit it I failed!"

On the other hand, those who use it does not want to switch to other IDEs¹. I wonder why. They must have a reason, because I can't see how such bad piece of software could last so long. Before dealing about the differences between the editors, let's first understand what is Vim.

What is Vim?

Vim is just a text editor that runs directly on the terminal or with a visual interface, based on modes and commands. To understand it better, let's get to know a little about its history.

Vi - Visual editor

Vi is a text editor created by Bill Joy in 1976, for a Unix derivative system, called BSD ². This BSD is the basis for the system used in Macs nowadays.

Vi was based on another editor called Ex, very useful for editing configuration files with the limitations of the computers of the time. It works with commands inserted in a line at the bottom of the screen. When typing visual or your abbreviation vi in the editor, a "visual mode" opens and enables an easier way for editing: with a cursor on the screen, similar to what we are familiar with. The name "vi" comes from the command used to enter the Ex visual mode.

Vi differs from others because it is a modal editor, i.e., keys can contain different functions depending on the mode. I will talk about how these modes work later.

Vim - Vim Improved

Vim is an editor created by Moolenaar, based on the Stevie editor, which was a vi version for the Atari ST.

It is very similar to the original Vi, but with many additions, making it more modern and easier to use. You can configure mouse usage and install extensions, for example.

Neovim

Although Vim came to be a good enough editor, all updates are approved by Bram Moolenaar himself to be applied in the new versions. As the open source world requires speed and less centralization, and in addition, the Vim code has already become quite hard to maintain and extend, Neovim was born: yet another VIM clone, focused on extensibility and usability. Part of this new code is written in Lua³.

Modes

As promised, now I will explain what the modes are and how they work.
At some point in time, you used some app that has its UI organized in steps. Modes work similarly: each one has its way of interacting with the content. It makes you have a specific focus when editing.

Affinity Designer is an example of an application that uses modes nowadays. You have a drawing mode, a painting mode and another one for export assets. In this app, modes are nicely called "personas".

In the same way, Vim/Neovim treats the text editing. Namely, the modes are:

Normal: Doesn't allow inclusion of text, but quick changes to it, such as replacing letters, deleting content, copy or paste lines. It is the mode the editor opens by default. It is enabled with the Esc button.
Visual: Allows the selection of text. Activated by shortcut v
Insertion: This mode allows you to write text. Enabled with the i button.
Command: Allows the user to write commands in the status bar, such as saving the file or split the screen. Enabled by the :.
Replacement: Works like the insert button on the keyboard. When typing, characters are replaced. Activated with R.

In the end, what makes Vim look more complicated is the presence of the modes. They are responsible for the phrase "I can't quit Vim", because to quit it, you first need to enter the command mode and enter the keyword or abbreviation.

In practice, this means typing :q and hitting ENTER, being : to access command mode and "q" for "quit", to exit the program.

What seems very difficult at first, becomes natural with time, believe me. I can't count how many times I caught myself doing the command to save :w in other text editors, hahah...

Comparing with VS Code

Don't get me wrong, I love VS Code. It is really an awesome code editor, and be aware that I'm not a Microsoft fanboy. Despite using Electron as a base, VS Code got a certain "lightness" that other competing editors using the same technology failed: Atom is an example of this.

VS Code: Electron in all its glory

The problem is, as some may know, Electron is not a native application, so it will never be fast like one. I had various crashes using it, and that's really boring. And when you know this is due to Electron, it is even more annoying, because the solution is to upgrade your system, which is not cheap at all. Add extensions and background processes to it, the things get even more troublesome.

Neovim: When it's well configured, it doesn't look like a terminal program

Another thing that a terminal editor can make and VS Code can't: enable direct editing on the command line. When you access a server via SSH, it will not be possible to run VS Code directly there. So even if you don't use Vim on a daily basis, know its basics will help you a lot in these occasions, as it will probably be available on the system by default.

Wrap up

As I don't depend exclusively on VS Code to do my job, I decided to switch to Neovim, which is a native and lightweight application. Besides that, you learn a new way to edit code that is quite efficient and amusing when you master it. You can even configure it in such a way that it resembles a lot VS Code, including support for equivalent extensions.

This is what I will address in the next articles. See you!

Links

If this article helped you in some way, consider donating. This will help me to create more content like this!

IDE: Integrated Development Environment, IDE is a developper-friendly text editor, with tools to easy code creation. ↩
BSD: Berkeley Software Distribution, was a Operating System based on UNIX, with a very permissive open source license. Today it is a term to include all OS based on in, like OpenBSD, FreeBSD and Darwin, that is used in MacOs. ↩
Lua: It is a programming language originally designed for extending applications and systems, created by the Brazilians Roberto Ierusalimschy, Luiz Henrique de Figueiredo, and Waldemar Celes, members of the Computer Graphics Technology Group (Tecgraf) at the Pontifical Catholic University of Rio de Janeiro, in Brazil. Today it is a multi-paradigm language used in many areas. ↩

10 VSCode themes you probably never heard of

Elves Sousa — Sat, 08 May 2021 15:17:45 +0000

Every blog focused on development or technology, at one time or another, will possibly have an article commenting on the 10 best themes for VSCode for the current year.

This list is usually composed of the same 10 themes or some variant of them: Dracula, Material, SynthWave '84, Nord, Gruvbox, Night Owl, Monokai Pro, One Dark Pro, Palenight or Shades of Purple. Okay, now that you know what to find in 80% of these articles, stay here for a while and see some other themes that you may never have heard of. Here, I focus on dark themes.

Lucy

Perhaps the most downloaded of this list, Lucy is a theme with no description. The author is quite direct like that. It looks like One Dark, but with more focus on pastel colors.

Celestial

Celestial is a darker version of the Horizon theme.

Umbra

A theme inspired by Bear, a markdown notes app, in its dark version. I used this theme for quite a while.

Orion Dark

No colors to call cold. None at all.

Spirited Away

This is a theme inspired by the colors of scenes of the anime with same name.

Contrast

It was inspired by the theme 1337, and originally created for Sublime Text. The colors are almost pure, but they don't cry for attention too much.

Crayon

This theme is for those who don't like very saturated colors.

Twilight

Twilight is the iconic theme from the Textmate text editor. This theme was a transcription of the theme for VSCode. I used it for a long time, for its simplicity and discretion.

Framer Dark

The Framer Dark theme emulates the Framer application syntax and interface theme.

Sobrio

This theme I am sure you probably never heard of, and the reason is very simple: I made it!

This is the color scheme that I use today and developed by me, first for NeoVim, which is the editor I use now, and later adapted for VSCode. The result was very pleasant in my opinion and I invite you to test it as soon as you finish reading this article!

That's it for this article, folks. If you like any of the themes, install it and give the creator a good rating to support their work. See you!

Links

If this article helped you in some way, consider donating. This will help me to create more content like this!

Making a multilingual site with Next.js - Part 3

Elves Sousa — Mon, 05 Apr 2021 21:56:44 +0000

If you ended up here for this third part and did not see the first nor the second, I highly suggest you take a look at those first. In the previous section, we dealt with the creation and listing of content for the languages and ended the project there.

However, some commented that it would be interesting to add translated slugs, for example: in English the "about" page open at site.com/en/about and its corresponding Portuguese version open at site.com/pt/sobre. In this article, I show you how we can create such functionality. Let's start!

But first...

In the previous articles, the function for changing languages was implemented. But when the page was refreshed, it returned to the default language, which caused a certain annoyance. This behavior is not the best, so it is important to solve this issue. Fortunately, it is not difficult at all to implement, with just a few lines of code.

Local Storage

Local Storage is a way that JavaScript provides us to save information in the user's browser, so that it will be available on a next visit. Many use it to make simple authentication or to save options, such as light and dark modes, for example.

The logic used here does not differ from that of a theme change, the change is that language will be saved instead. Small modifications to only two files are needed. The files are: the Header component and theLanguageProvider language context. If you fell from another dimension and did not see the two previous articles and nothing makes sense to you until now, I warned you at the beginning of the article! Go there and check the previous articles, and then come back here!

Here is the code for the Header component:

import { useContext } from "react"
import { useRouter } from "next/router"

import Navigation from "../Navigation"
import Logo from "../Logo"
import { LanguageContext, locales } from "../../intl/LanguageProvider"

interface Props {
  className?: string
  children?: React.ReactNode
}

const Header: React.FC<Props> = ({ className, children }) => {
  const headerClass = className || "header"
  const [locale, setLocale] = useContext(LanguageContext)
  const router = useRouter()

  function handleLocaleChange(language: string) {
    if (!window) {
      return
    }

    const regex = new RegExp(`^/(${locales.join("|")})`)
    localStorage.setItem("lang", language) // This line saves the language option!
    setLocale(language)

    router.push(router.pathname, router.asPath.replace(regex, `/${language}`))
  }

  return (
    <header className={headerClass}>
      <Logo link={`/`} />
      <Navigation />
      {children}
      <div className="lang">
        <button onClick={() => handleLocaleChange("en")}>EN</button>
        <button onClick={() => handleLocaleChange("pt")}>PT</button>
      </div>
    </header>
  )
}

export default Header

In Header, the method localStorage.setItem ('lang', language) was used to save the language choice by clicking on the corresponding button. What this method does is basically add a 'lang' key with the acronym of the chosen language. You can check this in the Application area of your browser's inspector, in the Local Storage section.

The LanguageProvider is as follows:

import { createContext, useEffect, useState } from "react"

export const defaultLocale = "pt"
export const locales = ["pt", "en"]
export const LanguageContext = createContext([])

export const LanguageProvider: React.FC = ({ children }) => {
  const [locale, setLocale] = useState("pt")

  useEffect(() => {
    if (!window) {
      return
    }
    // Captures the language information saved by the Header component
    const language = localStorage.getItem("lang") || locale
    setLocale(language)
  }, [locale])

  return (
    <LanguageContext.Provider value={[locale, setLocale]}>
      {children}
    </LanguageContext.Provider>
  )
}

Here the localStorage.getItem ('lang') method captures the saved information from the language choice, and applies it if it exists. Now when updating the page, the language you selected stays there.

Finally... Let's create the translated slugs...

Nothing prevents you from creating files in the /pages folder, with the desired title, such as /kontakt.tsx for a contact page in German. It will work perfectly, but let's be honest: it is not the best way to do the job. We should be able to provide a way for pages to be created dynamically, with a standard template, changing the content and slug according to the language.

If you think about it, a similar thing is done with our posts area in this project. To achieve this, just modify the library we created for the posts (/lib/posts.ts) to include our new translated pages. But avoid duplicate code, instead of creating a /lib/pages.ts file with practically the same content as /lib/posts, I decided to unify everything in a single library that I called lib/files.ts.

The content of this file is as follows:

import fs from "fs"
import path from "path"
import matter, { GrayMatterFile } from "gray-matter"
import remark from "remark"
import html from "remark-html"

const postsDirectory = path.resolve(process.cwd(), "content", "posts")
const pagesDirectory = path.resolve(process.cwd(), "content", "pages")

// Collects all file names in the folders specified with the sctructure ['en/filename.md']
export function getAllFileNames(directoryPath: string, filesList = []) {
  const files = fs.readdirSync(directoryPath)

  files.forEach((file) => {
    if (fs.statSync(`${directoryPath}/${file}`).isDirectory()) {
      filesList = getAllFileNames(`${directoryPath}/${file}`, filesList)
    } else {
      filesList.push(path.join(path.basename(directoryPath), "/", file))
    }
  })

  const filteredList = filesList.filter((file) => file.includes(".md"))
  return filteredList
}

// Sorts posts by date
export function getSortedPostData() {
  const fileNames = getAllFileNames(postsDirectory)

  const allPostsData = fileNames.map((fileName) => {
    const id = fileName.split("/")[1].replace(/\.md$/, "")
    const fullPath = path.join(postsDirectory, fileName)
    const fileContents = fs.readFileSync(fullPath, "utf-8")
    const frontMatter: GrayMatterFile<string> = matter(fileContents)

    return {
      id,
      ...(frontMatter.data as {
        lang: string
        date: string
        category: string
      }),
    }
  })

  return allPostsData.sort((a, b) => {
    if (a.date < b.date) {
      return 1
    } else {
      return -1
    }
  })
}

// IDs for posts or pages
export function getAllIds(type = "post") {
  const dir = type === "page" ? pagesDirectory : postsDirectory
  const fileNames = getAllFileNames(dir)

  return fileNames.map((fileName) => ({
    params: {
      id: fileName.split("/")[1].replace(/\.md$/, ""),
      lang: fileName.split("/")[0],
    },
  }))
}

// Collects data from the markdown file and makes it available
export async function getContentData(id: string, type = "post") {
  const dir = type === "page" ? pagesDirectory : postsDirectory
  const fullPath = path.join(dir, `${id}.md`)
  const fileContents = fs.readFileSync(fullPath, "utf-8")
  const frontMatter = matter(fileContents)

  const processedContent = await remark().use(html).process(frontMatter.content)

  const contentHtml = processedContent.toString()

  return {
    id,
    ...(frontMatter.data as { date: string; title: string }),
    contentHtml,
  }
}

I created a type argument in some of the functions that will be used by both posts and pages. This because this argument identifies the directory in which the files will be read. By default, I left it configured to always search for posts. Since the file name has changed and so have the functions, it is necessary to update the imports in the files that use the new library.

Template for the dynamic page

Here is another page with a special name, to create a dynamic route. In this the parameter will be the 'id' of the file, which is captured by the function getAllIds() of the file lib/files. The file will be called [lang]/[id].tsx. Below is the complete code of the file.

import { GetStaticProps, GetStaticPaths, NextPage } from "next"

import { getAllIds, getContentData } from "../../lib/files"
import Layout from "../../components/Layout"

interface PageProps {
  locale: string
  pageData: {
    lang: string
    title: string
    slug: string
    date: string
    category?: string
    contentHtml: string
  }
}

const SitePage: NextPage<PageProps> = ({ pageData }) => {
  const { title, contentHtml } = pageData

  return (
    <Layout title={title}>
      <article className="post-content">
        <h1>{title}</h1>
        <div
          className="post-text"
          dangerouslySetInnerHTML={{ __html: contentHtml }}
        />
      </article>
    </Layout>
  )
}

export const getStaticProps: GetStaticProps = async ({ params }) => {
  // Here is the argument to informa "page" as type,
  // so Next.js can search for page files, ignoring posts.
  const pageData = await getContentData(`/${params.lang}/${params.id}`, "page")

  return {
    props: {
      locale: params?.lang || "pt",
      pageData,
    },
  }
}

export const getStaticPaths: GetStaticPaths = async () => {
  // Here is the argument to informa "page" as type,
  // so Next.js can search for page files, ignoring posts.
  const paths = getAllIds("page")

  return {
    paths,
    fallback: false,
  }
}

export default SitePage

With this file, it is already possible to support pages created through Markdown. The markdown files use the following structure:

---
lang: pt
title: "Sobre"
---

Site made to showcase the creation of a bilingual website using Next.js. The tutorial is in an article on my blog. Feel free to view the source code, fork it, or even use it in your projects.

To better organize the files, I created a directory called /content in the root of the project, and in it another two: posts and pages. These will receive the markdown files in the directories for each language supported on the website. With the code presented here, the creation of the pages is fully automated and based on this structure.

Wrapping it up

I believe that now we already have a very functional example of a multilingual website using Next.js. You can create content for many languages and let the user choose one to use in your site.

Comments, suggestions and questions are welcome, leave it below. I also provided the link to the complete project repo on GitHub, in case you want to see the complete code. If you encounter an error, you can leave your issue there too.

See you!

Links

If this article helped you in some way, consider donating. This will help me to create more content like this!

CSS Form Validation with pseudo-classes

Elves Sousa — Thu, 05 Nov 2020 00:06:40 +0000

Everyone has come across that "boring" form that forces you to fill in a field and marks it with a bright red to show what was missing, or that the filling is wrong. "Wrong!"

It is boring, but it is increasingly necessary. You can no longer receive data that is invalid. This ends up involving high costs, mainly with the advance of e-commerce and virtual services.

There are now several tools to ease validation and include classes in forms to show errors visually. Several frameworks and libraries have this functionality, in several programming languages. However, I see little mention of the native way CSS offers to address the most common needs.

Believe it or not, CSS has pseudo-classes available only for the visual validation of forms. If you have well-crafted HTML code, using pseudo-classes to your advantage will be quite simple.

How does it work?

There are attributes in HTML that identify the data type a given field accepts, as well as its status and mandatory filling. Based on these it is possible to treat their appearance.

<!-- Required text field -->
<input id="name" type="text" name="nome" value="" required />

For this to work, it is good to remember that there are not only buttons, checkboxes, radios and text fields. There are also other fields, each with its own characteristics and validation, even though they appear the same as a text field.

Below is a list to remember these fields.

<!-- Campos -->
<input type="text" />
<input type="color" />
<input type="checkbox" />
<input type="date" />
<input type="email" />
<input type="file" />
<input type="month" />
<input type="number" />
<input type="password" />
<input type="radio" />
<input type="reset" />
<input type="search" />
<input type="tel" />
<input type="time" />
<input type="url" />
<input type="week" />

In the list above I did not include buttons, image, hidden and range, as they are not useful for this example. Let's go straight to the pseudo-classes that can be used for the visual validation of the fields.

:required

It will affect a field that is mandatory, that is, that has the required attribute. As an example, imagine the following HTML.

<input id="password" type="password" required />
<label for="password">Password</label>

To add a required warning text, just make a style like the one below:

input:required ~ label::after {
  content: " (required)";
  font-size: 0.8em;
  color: #000;
}

Done. Any label after a required field will have a (required) in its text. In the example above, I didn't use classes, just the name of the markup in the CSS, for the sake of simplicity. The others will follow the same style.

:valid and :invalid

Each field, as previously mentioned, has a validation made by the browser itself, according to its type.

<input id="email" type="email" required />
<label for="email">E-mail address</label>

Above, an "email" type field is used for an e-mail registration, instead of a normal text field. As we used the right type for the data to be informed, we are free to use its standard validation to change its appearance according to the data filled in:

/* Campo com dados válidos */
input:valid {
  border-color: #090;
}

/* Campo com dados inválidos */
input:invalid {
  border-color: #900;
}

With the styles above, the border of the element will be green if the data is valid and red if it is not. Remember that if it is empty and mandatory, it will be considered invalid.

:optional

input:optional {
  border: 1px dashed #ccc;
}

If the field is optional, the pseudo-class :optional can be used to show this to the user visually.

Conclusion

Here's a sample of what you can achieve with just a little CSS:

See the Pen Campos by Elves Sousa
(@elvessousa) on CodePen.

Perhaps you were unaware of these pseudo-classes or just never used them. The fact is that they have their use cases. Of course, this is just the visual part of the form validation. CSS will not check data before sending it. And if that happens one day, I will be worried!

There are limitations if the data to be sent is very specific, such as number of documents or cards, for example. Therefore, use the validation tool of your choice: the good thing is that you will use it only where you really need it, removing unnecessary logic from your project.

The focus will be more on checking data and information messages than on appearance.

Links

If this article helped you in some way, consider donating. This will help me to create more content like this!

Making a multilingual site with Next.js - Part 2

Elves Sousa — Mon, 10 Aug 2020 20:43:00 +0000

This article was originally posted here.

If you missed the first part of this article, I suggest you take a look at it before continuing reading this one. In order not to make the article too long, I chose to split it into two parts. In the previous part we saw how to translate the words on screen. Now, we will deal with the creation and listing of content for each language. Without further ado, here we go!

Markdown content for each language

The file structure follows the example below:

---
lang: pt
title: "Artigo em português"
slug: artigo
date: "2020-07-12"
category: post
description: "Lorem ipsum dolor sit amet consectetuer adispiscing elit"
---

## Lorem

Lorem ipsum dolor sit amet consectetuer adispiscing elit.

If you don't know Markdown, this header between --- is called "frontmatter". With it, we pass information that will be used for the listing and display of the content. Below is a brief description of what each field does:

lang: ISO of the language used in the content.
title: title of the article.
date: date of the article, in YYYY-MM-DD format. Note that it is enclosed in quotation marks, otherwise Next.js throws an error.
description: summary of the article on the article listing page.
category: category of the article.

You have freedom to create your own fields in this header, like tags and stuff. For the example cited here, this is enough.

Library to read Markdown files

As you can already know, Markdown files are the basis of our content. To read these files and convert them to HTML, three packages need to be installed: Remark and Remark-HTML and Gray Matter. The latter reads the * .md file frontmatter.

In order to install it:

yarn add remark remark-html gray-matter

npm install --save remark remark-html gray-matter

This part was easy, however, creating the post loop is not that simple. First I followed the tutorial¹ that the folks at Next.js did, but I had to make some adjustments to add the possibility of saving the files in different folders, by language. Below is the commented code.

import fs from "fs"
import path from "path"
import matter, { GrayMatterFile } from "gray-matter"
import remark from "remark"
import html from "remark-html"

// Directory used to read markdown files
const postsDirectory = path.resolve(process.cwd(), "posts")

// Returns a list of files in the directories and
// subdirectories in the formal ['en/filename.md']
function getAllPostFileNames(directoryPath, filesList = []) {
  const files = fs.readdirSync(directoryPath)

  files.forEach((file) => {
    if (fs.statSync(`${directoryPath}/${file}`).isDirectory()) {
      filesList = getAllPostFileNames(`${directoryPath}/${file}`, filesList)
    } else {
      filesList.push(path.join(path.basename(directoryPath), "/", file))
    }
  })

  // Filter to include only * .md files
  // If you don't use this, even .DS_Stores are included
  const filteredList = filesList.filter((file) => file.includes(".md"))
  return filteredList
}

// Collects information from files and sorts them by date
export function getSortedPostData() {
  // Get the list of * .md files in the posts directory
  const fileNames = getAllPostFileNames(postsDirectory)

  // Uses gray-matter to collect information from the file
  const allPostsData = fileNames.map((fileName) => {
    const id = fileName.split("/")[1].replace(/\.md$/, "")
    const fullPath = path.join(postsDirectory, fileName)
    const fileContents = fs.readFileSync(fullPath, "utf-8")
    const frontMatter: GrayMatterFile<string> = matter(fileContents)

    return {
      id,
      ...(frontMatter.data as {
        lang: string
        date: string
        category: string
      }),
    }
  })

  // Sorts collected information by date
  return allPostsData.sort((a, b) => {
    if (a.date < b.date) {
      return 1
    } else {
      return -1
    }
  })
}

// Separates the file name and language
export function getAllPostIds() {
  // Get the list of * .md files in the posts directory
  const fileNames = getAllPostFileNames(postsDirectory)

  // Splits the "en" and "filename" parts of ['en/filename.md']
  // and return them as parameters for later use in Next
  return fileNames.map((fileName) => ({
    params: {
      id: fileName.split("/")[1].replace(/\.md$/, ""),
      lang: fileName.split("/")[0],
    },
  }))
}

// Make the data available for the informed post.
export async function getPostData(id) {
  const fullPath = path.join(postsDirectory, `${id}.md`)
  const fileContents = fs.readFileSync(fullPath, "utf-8")
  const frontMatter = matter(fileContents)

  const processedContent = await remark().use(html).process(frontMatter.content)

  const contentHtml = processedContent.toString()

  return {
    id,
    ...(frontMatter.data as { date: string; title: string }),
    contentHtml,
  }
}

For those who have used Gatsby, this file is the equivalent of the gatsby-node.js file. It makes file data available for viewing in Next.js.

Listing posts

Next.js uses its own way of routing. Unlike Gatsby, where you define the routes of the listing pages in the gatsby-node.js file, you use the folder structure itself.

To have a site.com/language/post/article URL, simply create the directories following this structure, inside the /pages folder that we already used to create the other pages.

If we just did something like suggested above, we would have the same result visually, but using React components instead of the .md files. In the end we would have several *.tsx files and a folder for each language. This is not the best way approach, though.

It makes a lot more sense to leave the content files in Markdown and use something dynamic to read this content and generate the static pages. Next.js can use the folder and file names to express a dynamic part of the route, using square brackets.

On the right, the way Next.js organizes dynamic routes

Instead of making the structure on the left, we will use the leaner version on the right. In this example, the file for listing files is articles.tsx. It is inside the /[lang] folder which will tell Next.js that the variable "lang" will be used at the URL: site.com/[lang]/articles. This [lang] will be replaced by pt oren according to the language to be displayed. Here is the code for the file:

import { useState } from "react"
import { NextPage, GetStaticProps, GetStaticPaths } from "next"
import Link from "next/link"

import Layout from "../../components/Layout"
// Import function that lists articles by date
import { getSortedPostData } from "../../lib/posts"
import useTranslation from "../../intl/useTranslation"

interface Props {
  locale: string
  allPostsData: {
    date: string
    title: string
    lang: string
    description: string
    id: any
  }[]
}

const Post: NextPage<Props> = ({ locale, allPostsData }) => {
  const { t } = useTranslation()

  // Articles filtered by language
  const postsData = allPostsData.filter((post) => post.lang === locale)

  // Pagination
  const postsPerPage = 10
  const numPages = Math.ceil(postsData.length / postsPerPage)
  const [currentPage, setCurrentPage] = useState(1)
  const pagedPosts = postsData.slice(
    (currentPage - 1) * postsPerPage,
    currentPage * postsPerPage
  )

  // Date display options
  const dateOptions = {
    year: "numeric",
    month: "long",
    day: "numeric",
  }

  return (
    <Layout className="posts" title={t("articles")}>
      <section className="page-content">
        <h1>{t("articles")}</h1>
        {/* List of articles */}
        {pagedPosts.map((post) => (
          <article key={post.id} className="post">
            <Link href={`/[lang]/post/[id]`} as={`/${locale}/post/${post.id}`}>
              <a>
                <h3>{post.title}</h3>
              </a>
            </Link>
            <time>
              {new Date(post.date).toLocaleDateString(locale, dateOptions)}
            </time>
            {post.description && <p>{post.description}</p>}
          </article>
        ))}

        {/* Paging */}
        {numPages > 1 && (
          <div className="pagination">
            {Array.from({ length: numPages }, (_, i) => (
              <button
                key={`pagination-number${i + 1}`}
                onClick={() => setCurrentPage(i + 1)}
                className={currentPage === i + 1 ? "active" : ""}
              >
                {i + 1}
              </button>
            ))}
          </div>
        )}
      </section>
    </Layout>
  )
}

// Captures the information needed for the static page
export const getStaticProps: GetStaticProps = async (ctx) => {
  // All site articles
  const allPostsData = getSortedPostData()

  // Returns the properties used in the main component: the page
  return {
    props: {
      locale: ctx.params?.lang || "pt", // Captures the language of [lang] route
      allPostsData,
    },
  }
}

// Generates static files on export
export const getStaticPaths: GetStaticPaths = async () => {
  // All supported languages must be listed in 'paths'.
  // If not informed, the static page will not be generated.
  return {
    paths: [{ params: { lang: "en" } }, { params: { lang: "pt" } }],
    fallback: false,
  }
}

export default Post

As the intention is to generate static files, I used the getStaticProps() function to capture the information and getStaticPaths to inform the system the path where the pages will be exported.

Post page

Another page with the special file name, to inform a dynamic route. This time the parameter will be the file id, which is captured by the getAllPostIds() function of the lib/posts file, so the name of this component will be[lang]/posts/[id].tsx. Below, its contents:

import { GetStaticProps, GetStaticPaths, NextPage } from "next"

/* - getAllPostIds: Gets the file id, that is, the file name
     markdown without the * .md extension
   - getPostData: Collects information from a single article by the given id.
*/
import { getAllPostIds, getPostData } from "../../../lib/posts"
import Layout from "../../../components/Layout"

interface Props {
  locale: string
  postData: {
    lang: string
    title: string
    slug: string
    date: string
    category: string
    contentHtml: string
  }
}

const Post: NextPage<Props> = ({ postData, locale }) => {
  const { title, contentHtml } = postData

  return (
    <Layout title={title}>
      <article className="post-content">
        <h1>{title}</h1>
        <div
          className="post-text"
          dangerouslySetInnerHTML={{ __html: contentHtml }}
        />
      </article>
    </Layout>
  )
}

// As in the list page, passes the captured information to the page properties
export const getStaticProps: GetStaticProps = async ({ params }) => {
  // Collect data from the post "en/filename"
  const postData = await getPostData(`/${params.lang}/${params.id}`)

  return {
    props: {
      locale: params?.lang || "pt", // Captures [lang] from URL
      postData,
    },
  }
}

// Use getAllPostIds to inform which pages to generate when exporting static files.
export const getStaticPaths: GetStaticPaths = async () => {
  const paths = await getAllPostIds()

  return {
    paths,
    fallback: false,
  }
}

export default Post

This is enough for a simple blog page.

Wrapping it up

To write these two articles, I used the reference I left below. It was the closest one to what I wanted to achieve. However, there are certain things that were not so useful to me, or caused unwanted complexity for the size of the project. Note that there is no need for external libraries for the translations, which is quite interesting. If you have any questions or suggestions leave a comment. I will be grad to get your feedback!

Below, I left a link to this project repository on Github, in case you want to see the complete source code.

Making a multilingual site with Next.js - Part 1

Elves Sousa — Thu, 30 Jul 2020 15:08:34 +0000

See the original article here.

In the last article I showed you how to make a simple multilingual website in Gatsby. This time, I decided to try the same with Next.js. As with Gatsby, it was not easy to find information on how to create a website with multiple languages as well. As I did that time, I'll also describe here the process I used to achieve this goal.

Initial setup

To set up the project in Next.js just use this command in the terminal:

yarn create next-app next-intl

If you are using NPM, use this other one.

npx create-next-app next-intl

In this code, I am using TypeScript. If you don't want to use it, just skip these next steps.

Configuring TypeScript

Next.js already provides support for TypeScript from the factory. Just create an empty tsconfig.json file at the root of the project. When starting the development environment using the command yarn dev ornpm run dev, the file tsconfig.json will be detected and if it does not find the typing dependencies for development, it will show a message telling which dependencies need be installed and giving the command for you to copy and paste to add them. It will probably be something as shown below.

yarn add typescript @types/node @types/react -D

Or:

npm install --save-dev typescript @types/node @types/react

Ready. The setup is complete.

Project structure

Directories

I leave the following suggestion for the project's directory and file structure:

components: React components.
intl: here will be the files for the translation of the website content
lib: in this directory will be the script to read the *.md files and which makes the information available for use on the pages.
pages: Next.js uses this folder as the directions for the application. The file teste.tsx is available ashttp://localhost: 3000/teste
posts: Markdown files that containing article texts.
styles: styles for the page.
public: this folder is used by default by Next.js for public files: images, icons, etc.

Feel free to use the structure that makes the most sense for you.

Structure of the pages (routes)

Any JavaScript file (.js,.jsx, or .tsx in my case) placed inside the /pages folder will be converted into an accessible route automatically. In this example, there are the files index.tsx for the home page andabout.tsx for an about page.

I am not going to describe these files in detail here, just what is needed for the translation. Anyway, I'll show examples later and the code will be available in the repository linked at the end of this article.

The page for listing articles and viewing the content of each article will be arranged differently. I'll explain it later.

Content structure (posts)

Within the /posts folder, two more directories will be created: /en and /pt for files in English and Portuguese. Feel free to use the language that suits you. Markdown files with content in the respective languages will be placed inside them.

Dictionary: terms for translation

For the translation, the first file that we are going to create is the one that has the terms to be translated on the website. Think of this file as if it were a kind of dictionary: just look for a definition to get the meaning. That's the mechanics.

export const LangStrings = {
  en: {
    about: "About",
    articles: "Articles",
    home: "Home",
    slogan: "An example site showcasing a bilingual site with GatsbyJS.",
  },
  pt: {
    about: "Sobre",
    articles: "Artigos",
    home: "Início",
    slogan: "Um site bilíngue de exemplo feito com GatsbyJS.",
  },
}

That simple. I saved this file as Strings.ts in the/intl directory mentioned earlier. If your project grows a lot, I recommend breaking it into different files.

Language context

In React there is a thing called context, which is state information available to the entire application. Without it, all information has to be passed via property to each component using it, which can hinder development if there are many levels of hierarchy.

Ideally, the language should be available for the entire project, globally. For that, a context must be created. Below, the code I used to create it:

import { createContext, useState } from "react"

export const defaultLocale = "en"
export const locales = ["pt", "en"]
export const LanguageContext = createContext([])

export const LanguageProvider: React.FC = ({ children }) => {
  const [locale, setLocale] = useState("pt")

  return (
    <LanguageContext.Provider value={[locale, setLocale]}>
      {children}
    </LanguageContext.Provider>
  )
}

The code is quite simple, but enough for the example in this article. The defaultLocale defines the website's default language, English in this case. locales lists available languages on the site. To add more, just add another ISO abbreviation to the list and provide the terms for translation in the file Strings.ts.

To make the context available in the application, a file called _app.tsx is created inside the /pages folder with the following code:

import { AppPropsType } from "next/dist/next-server/lib/utils"
import { LanguageProvider } from "../intl/LanguageProvider"

import "./styles/layout.css"

export default function App({ Component, pageProps, router }: AppPropsType) {
  return (
    <LanguageProvider>
      <Component {...pageProps} key={router.route} />
    </LanguageProvider>
  )
}

This file is a special one, as it does not turn into a page, but affects the entire site. Next understands it as the entry point for the React application and things done here are available globally.

We add in it the created context of languages, importing the component <LanguageProvider /> and involving the main component of the application with it. From now on the context will be available for other pages and components.

Customized translation hook

As no translation library is being used for this project, to ease the use of the translated terms, a "hook" was created, a custom function called useTranslation. In React, the word "use" is added as a prefix in a hook function name, it is a convention. Here is the code:

import { useContext } from "react"

import { LanguageContext, defaultLocale } from "./LanguageProvider"
import { LangStrings } from "./Strings"

export default function useTranslation() {
  const [locale] = useContext(LanguageContext)

  function t(key: string) {
    if (!LangStrings[locale][key]) {
      console.warn(`No string '${key}' for locale '${locale}'`)
    }

    return LangStrings[locale][key] || LangStrings[defaultLocale][key] || ""
  }

  return { t, locale }
}

Essentially, this hook reads the "dictionary" created, using the current page language, informed by the context I mentioned before. Several translation libraries use this same method, each one in its own way. What the code above does is to import the LangStrings dictionary and theLangContext context and with this information, return the translation according to the current language, or with the default language informed through the constant defaultLocale.

Translating page content

My final index.tsx looks like this:

import { NextPage } from "next"
import Link from "next/link"

import Layout from "../components/Layout"
import useTranslation from "../intl/useTranslation"

const Home: NextPage = () => {
  const { t } = useTranslation()

  return (
    <Layout title={t("home")} className="home">
      <section className="hero">
        <div className="message">
          <h1>Next INTL</h1>
          <p>{t("slogan")}</p>
          <Link href="/about">
            <a className="button">{t("about")}</a>
          </Link>
        </div>
      </section>
    </Layout>
  )
}

export default Home

Notice that in all areas where it is good to have a translation, use the function t("term") that comes from the created hook.

From now on, just do this in every component you want to translate: import the useTranslation hook, make the t() function available for use with const {t} = useTranslation () and use the t() function with an existing definition in the dictionary.

Translating dates

For dates, I used the .toLocaleDateString method. Below is an example for article dates:

<span>{new Date(post.date).toLocaleDateString(locale, dateOptions)}</span>

Being post.date the text with the date, locale the acronym of the ISO language dateOptions the options for displaying the date.

const dateOptions = {
  year: "numeric",
  month: "long",
  day: "numeric",
}

In the example above, dateOption makes the date appear like this: July 21, 2020. More information about these options can be found in the MDN¹.

This article is getting big, so that's it for now! In the next few days I will post the second part of this article, with the creation of content in Markdown and listing of articles. See you later!