From e51af265f799826ec901f0b325d1088938b7c8e6 Mon Sep 17 00:00:00 2001 From: vyfor Date: Tue, 10 Dec 2024 18:20:30 +0500 Subject: [PATCH] docs: create a configuration guide --- wiki/CONFIGURATION.md | 235 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 wiki/CONFIGURATION.md diff --git a/wiki/CONFIGURATION.md b/wiki/CONFIGURATION.md new file mode 100644 index 00000000..6a3390c3 --- /dev/null +++ b/wiki/CONFIGURATION.md @@ -0,0 +1,235 @@ +# ⚡ Cord Configuration + +A comprehensive guide to configuring the Cord plugin to your liking. All options are set through the `setup()` function: + +```lua +require('cord').setup { + -- your options here +} +``` + +## 🔧 Core Options + +| Option | Type | Default | Description | +| ----------- | --------- | ---------------------- | ------------------------------------------------------------ | +| `usercmds` | `boolean` | `true` | Enable [user commands](#user-commands) for managing presence | +| `log_level` | `number` | `vim.log.levels.ERROR` | Set logging verbosity using Neovim's log levels | + +## ⏰ Timestamp + +| Option | Type | Default | Description | +| --------------------------- | --------- | ------- | ---------------------------------------- | +| `timestamp.enabled` | `boolean` | `true` | Show elapsed time in presence | +| `timestamp.reset_on_idle` | `boolean` | `false` | Reset timestamp when entering idle state | +| `timestamp.reset_on_change` | `boolean` | `false` | Reset timestamp when presence changes | + +## 🎨 Editor + +| Option | Type | Default | Description | +| ---------------- | --------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `editor.client` | `string` | `'neovim'` | Client identifier. Can be `'vim'`, `'neovim'`, `'lunarvim'`, `'nvchad'`, `'astronvim'`, or a custom Discord application ID | +| `editor.tooltip` | `string` | `'The Superior Text Editor'` | Tooltip shown when hovering over editor icon | +| `editor.icon` | `string \| nil` | `nil` | Custom icon URL or asset ID when using custom client ID | + +## 📊 Display + +| Option | Type | Default | Description | +| --------------------- | --------- | ------- | ----------------------------------- | +| `display.swap_fields` | `boolean` | `false` | Show workspace name before filename | +| `display.swap_icons` | `boolean` | `false` | Use editor icon as large image | + +## 💤 Idle + +| Option | Type | Default | Description | +| ------------------- | -------------------------- | ---------- | ------------------------------------------------------------- | +| `idle.enabled` | `boolean` | `true` | Enable idle status detection | +| `idle.timeout` | `number` | `300000` | Milliseconds before marking the session as idle | +| `idle.show_status` | `boolean` | `true` | Show idle status in presence, or hide the presence if `false` | +| `idle.ignore_focus` | `boolean` | `true` | Show idle when Neovim is focused | +| `idle.smart_idle` | `boolean` | `true` | Enable [smart idle](#smart-idle) feature | +| `idle.details` | `string \| function(opts)` | `'Idling'` | Details shown when idle | +| `idle.state` | `string \| function(opts)` | `nil` | State shown when idle | +| `idle.tooltip` | `string \| function(opts)` | `'💤'` | Tooltip shown when hovering over idle icon | +| `idle.icon` | `string \| function(opts)` | `nil` | Custom icon URL or asset ID | + +## 📝 Text & Assets + +| Option | Type | Default | Description | +| --------- | -------------- | --------------------------------- | --------------------------------------------- | +| `text` | `table` | See [Text Options](#text-options) | Customize displayed text for different states | +| `buttons` | `table \| nil` | `nil` | Configure [presence buttons](#buttons) | +| `assets` | `table \| nil` | `nil` | Custom [file icons](#assets) configuration | + +## 🪝 Hooks + +| Option | Type | Description | +| --------------------------- | -------------------------- | ---------------------------------------------------------------------------- | +| `hooks.on_ready` | `function` | Called when connected to the server and ready for communication with Discord | +| `hooks.on_update` | `function(opts)` | Called before building activity | +| `hooks.on_activity` | `function(opts, activity)` | Called before sending activity | +| `hooks.on_idle` | `function(opts)` | Called when idle state changes | +| `hooks.on_workspace_change` | `function(opts)` | Called when workspace changes | +| `hooks.on_disconnect` | `function` | Called when server disconnects | + +## ⚙️ Advanced + +| Option | Type | Default | Description | +| --------------------------------- | --------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | +| `advanced.server.pipe_path` | `string \| nil` | `nil` | Custom IPC pipe path | +| `advanced.server.executable_path` | `string \| nil` | `nil` | Custom server executable path | +| `advanced.server.timeout` | `number` | `60000` | Server shutdown timeout (ms) | +| `advanced.cursor_update_mode` | `string` | `'on_move'` | When to update cursor position: `'on_move'`, `'on_hold'`, or `'none'`. See [Cursor Update Mode](#cursor-update-mode) | + +--- + +### Text Options + +The `text` table supports both static strings and functions for dynamic content: + +```lua +text = { + editing = function(opts) + return string.format('Editing %s', opts.filename) + end, + viewing = 'Viewing %s', -- Simple string with filename placeholder + docs = 'Reading docs', -- Shown in help buffers + dashboard = 'Home', -- Shown in dashboard buffers + file_browser = 'Browsing files', -- Shown in file explorer + plugin_manager = 'Managing plugins', -- Shown in plugin manager + lsp_manager = 'Configuring LSP', -- Shown in LSP manager + vcs = 'Managing Git', -- Shown in VCS related filetypes +} +``` + +### Buttons + +Buttons can have static or dynamic labels and URLs: + +```lua +buttons = { + { + label = function(opts) + return opts.git_url and 'View Repository' or 'Website' + end, + url = function(opts) + return opts.git_url or 'https://example.com' + end + } +} +``` + +### Assets + +Override icons and text for specific filetypes or filenames. Most of the options also support functions. + +```lua +assets = { + ['.rs'] = { + icon = 'rust', -- Asset name or URL + tooltip = 'Rust', -- Hover text + text = 'Writing in Rust' -- Override entire text + }, + netrw = { + name = 'Netrw', -- Override icon name only + icon = 'default', -- Use default icon + type = 'file_browser' -- Set icon type + } +} +``` + +> [!TIP] +> A detailed guide can be found in the [Wiki](https://github.com/vyfor/cord.nvim/wiki/Add-or-change-file-icons). + +### Smart Idle + +Smart idle ensures that: +- When an instance goes idle, it switches to show the most recent active one +- You're only shown as idle when all instances are actually idle + +### User Commands + +- `:CordTogglePresence` - Toggle presence visibility +- `:CordShowPresence` - Show presence +- `:CordHidePresence` - Hide presence +- `:CordToggleIdle` - Toggle idle status +- `:CordIdle` - Show idle status +- `:CordUnidle` - Hide idle status +- `:CordClearPresence` - Clear current session's presence +- `:CordClearPresence!` - Clear the rich presence for all sessions + +### Cursor Update Mode + +The `advanced.cursor_update_mode` option controls how cursor position updates are handled: +- `'on_move'` - Uses `CursorMoved[I]` autocmd, updating on every cursor movement. Most accurate but triggered very often +- `'on_hold'` - Uses `CursorHold[I]` autocmd, updating only after the cursor has been stationary for `'updatetime'` milliseconds. Better performance but less accurate +- `'none'` - Disables cursor position updates entirely + +### Activity Options + +The `opts` parameter passed to all functions and hooks contains the following information: + +```lua +{ + manager = ActivityManager, -- Reference to the ActivityManager instance + + -- File Information + filename = string, -- Current buffer's filename + filetype = string, -- Current buffer's filetype + is_read_only = boolean, -- Whether the current buffer is read-only + + -- Cursor Information + cursor_line = number, -- Current cursor line number + cursor_char = number, -- Current cursor character number + + -- Timestamp Information + timestamp = number, -- Timestamp passed to the Rich Presence in milliseconds + + -- Workspace Information + workspace_dir = string, -- Current workspace directory + workspace_name = string, -- Current workspace name + git_url = string, -- Current Git repository URL, if any + + -- Editor Information + is_focused = boolean, -- Whether Neovim is focused + is_idle = boolean, -- Whether the session is idle + buttons = table, -- List of configured presence buttons + + -- Asset Information + type = string, -- Which category the asset belongs to + name = string, -- Asset name, if any + icon = string, -- Asset icon URL or name, if any + tooltip = string, -- Hover text for the asset, if any + text = string, -- Custom text to display, if any +} +``` + +The `ActivityManager` contains useful methods: + +### ActivityManager Methods + +| Method | Description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| `queue_update(force_update)` | Schedules an update to the activity. If `force_update` is true, it bypasses checks and updates immediately. | +| `pause()` | Pauses all events and stops the idle timer. | +| `resume()` | Resumes events and restarts the idle timer. | +| `pause_events()` | Disables event handling without affecting the idle timer. | +| `resume_events()` | Enables event handling and queues an immediate update. | +| `skip_update()` | Skips the next update once. | +| `hide()` | Pauses events and clears the current activity. | +| `toggle()` | Toggles between pausing and resuming the activity updates. | +| `force_idle()` | Forcibly sets the session to idle. | +| `unforce_idle()` | Clears the idle state and resumes normal activity. | +| `toggle_idle()` | Toggles between idle and normal activity. | +| `set_activity(activity)` | Sets the rich presence to the provided [activity](#activity-options), offering complete control over the presence. | +| `clear_activity(force)` | Clears the current activity from the Discord presence. If `force` is true, it completely clears the presence. | + +### `set_activity` Parameters + +| Parameter | Type | Description | +| ------------ | -------- | ---------------------------------------------------------------------------------------------------- | +| `type` | `number` | One of 'playing', 'listening', 'watching' | +| `state` | `string` | The user's current state (e.g., "Editing a file"). | +| `details` | `string` | Detailed information about what the user is doing. | +| `timestamps` | `object` | Contains `start` and `end` timestamps for the activity. | +| `assets` | `object` | Defines images and tooltips, including `large_image`, `large_text`, `small_image`, and `small_text`. | +| `buttons` | `array` | Array of objects, each with `label` and `url`, defining interactive buttons in the presence. |