diff --git a/doc/tags b/doc/tags index 4675a6bb6..d2e3e255c 100644 --- a/doc/tags +++ b/doc/tags @@ -1,42 +1,3 @@ -neorg neorg.norg /* The `.norg` File Format -neorg-advanced-markup neorg.norg /** Advanced Markup -neorg-anchors neorg.norg /*** Anchors -neorg-basic-markup neorg.norg /** Basic Markup -neorg-breaking-changes breaking-changes.norg /*NOTE: -neorg-carryover-tags neorg.norg /*** Carryover -neorg-code-blocks neorg.norg /*** Code Blocks -neorg-data-tags neorg.norg /** Data Tags -neorg-definitions neorg.norg /** Definitions -neorg-footnotes neorg.norg /** Footnotes -neorg-headings neorg.norg /*** Headings -neorg-indentation-reversal neorg.norg /***** Indentation reversion -neorg-link-descriptions neorg.norg /*** Custom link text -neorg-link-examples neorg.norg /*** Examples -neorg-link-locations neorg.norg /*** Pure link location -neorg-link-modifier neorg.norg /*** The Link modifier -neorg-link-targets neorg.norg /*** Link Targets -neorg-links neorg.norg /** Links -neorg-math neorg.norg /*** Math -neorg-media neorg.norg /*** Media -neorg-name-tag neorg.norg /*** Name -neorg-nested-markup neorg.norg /*** Nested markup -neorg-ordered-lists neorg.norg /*** Ordered lists -neorg-quotes neorg.norg /*** Quotes -neorg-tasks neorg.norg /*** Tasks -neorg-unordered-lists neorg.norg /*** Unordered lists -neorg-variables neorg.norg /*** Variables - -neorg-cheatsheet cheatsheet.norg /* Your Quick Neorg Guide -neorg-cheatsheet-headings cheatsheet.norg /** Headings -neorg-cheatsheet-reverse-headings cheatsheet.norg /** Reverse Headings -neorg-cheatsheet-lists cheatsheet.norg /** Lists -neorg-cheatsheet-code-blocks cheatsheet.norg /** Code Blocks -neorg-cheatsheet-styling cheatsheet.norg /** Styling -neorg-cheatsheet-links-urls cheatsheet.norg /*** Links to URLs -neorg-cheatsheet-links-objects cheatsheet.norg /*** Links to Objects -neorg-cheatsheet-links-non-norg cheatsheet.norg /*** Links to non-norg Files -neorg-cheatsheet-links-descriptions cheatsheet.norg /*** Links with Descriptions -neorg-cheatsheet-links-anything cheatsheet.norg /*** Links to Anything -neorg-cheatsheet-links-files cheatsheet.norg /*** Links across Files -neorg-cheatsheet-anchors cheatsheet.norg /** Anchors -neorg-cheatsheet-tasks cheatsheet.norg /* Tasks +neorg-wiki wiki/Home.norg 1 +norg neorg.norg /* The `.norg` File Format +norg-cheatsheet cheatsheet.norg /* Your Quick Neorg Guide diff --git a/doc/wiki/Autocommands.norg b/doc/wiki/Autocommands.norg new file mode 100644 index 000000000..90402629c --- /dev/null +++ b/doc/wiki/Autocommands.norg @@ -0,0 +1,56 @@ + +* `core.autocommands` + + *** + + Handles the creation and management of Neovim’s autocommands. + +* Overview + + This internal module exposes functionality for subscribing to autocommands and performing actions based on those autocommands. + +****** NOTE: This module will be soon deprecated, and it’s favourable to use the `vim.api*` functions instead. + + In your `module.setup()`, make sure to require `core.autocommands` (`requires = { "core.autocommands" }`) + Afterwards in a function of your choice that gets called /after/ core.autocommmands gets intialized (e.g. `load()`): + + @code lua + module.load = function() + module.required["core.autocommands"].enable_autocommand("VimLeavePre") -- Substitute VimLeavePre for any valid neovim autocommand + end + @end + + Afterwards, be sure to subscribe to the event: + + @code lua + module.events.subscribed = { + ["core.autocommands"] = { + vimleavepre = true + } + } + @end + + Upon receiving an event, it will come in this format: + + @code lua + { + type = "core.autocommands.events.", + broadcast = true + } + @end + +* Configuration + + This module provides no configuration options! + +* Required By + + - {https://github.com/nvim-neorg/neorg/wiki/Concealer}[`core.concealer`] - Enhances the basic Neorg experience by using icons instead of text. + - {https://github.com/nvim-neorg/neorg/wiki/Dirman}[`core.dirman`] - This module is be responsible for managing directories full of .norg files. + - {https://github.com/nvim-neorg/neorg/wiki/Indent}[`core.esupports.indent`] - A set of instructions for Neovim to indent Neorg documents. + - {https://github.com/nvim-neorg/neorg/wiki/Metagen}[`core.esupports.metagen`] - A Neorg module for generating document metadata automatically. + - {https://github.com/nvim-neorg/neorg/wiki/Core-Highlights}[`core.highlights`] - Manages your highlight groups with this module. + - {https://github.com/nvim-neorg/neorg/wiki/Core-Latex-Renderer}[`core.latex.renderer`] - An experimental module for rendering latex images inline. + - {https://github.com/nvim-neorg/neorg/wiki/Storage}[`core.storage`] - Deals with storing persistent data across Neorg sessions. + - {https://github.com/nvim-neorg/neorg/wiki/Syntax}[`core.syntax`] - Handles interaction for syntax files for code blocks. + diff --git a/doc/wiki/Calendar.norg b/doc/wiki/Calendar.norg new file mode 100644 index 000000000..117a8ac1a --- /dev/null +++ b/doc/wiki/Calendar.norg @@ -0,0 +1,22 @@ + +* `core.ui.calendar` + +*** Frictionless Dates + + The calendar module provides a range of functionality for different date-related tasks. + +* Overview + + The calendar is most often invoked with the intent of selecting a date, but may + also be launched in standalone mode, select date range mode and others. + + To view keybinds and help, press `?` in the calendar view. + +* Configuration + + This module provides no configuration options! + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Core-UI}[`core.ui`] - A set of public functions to help developers create and manage UI (selection popups, prompts…) in their modules. + diff --git a/doc/wiki/Clipboard-Code-Blocks.norg b/doc/wiki/Clipboard-Code-Blocks.norg new file mode 100644 index 000000000..7657e119d --- /dev/null +++ b/doc/wiki/Clipboard-Code-Blocks.norg @@ -0,0 +1,20 @@ + +* `core.clipboard.code-blocks` + +*** Comfortable Code Copying in Neorg + +* Overview + + The `code-blocks` module removes leading whitespace when copying from an `@code` tag, allowing + for easy pasting into external applications. + + To use it, simply highlight some code within an `@code` block and paste it elsewhere! + This functionality will *only* work if the selection is inside the `@code` section, + excluding the `@code` and `@end` portion itself. + + If the conditions are not met, the content is copied normally, preserving all indentation. + +* Configuration + + This module provides no configuration options! + diff --git a/doc/wiki/Clipboard.norg b/doc/wiki/Clipboard.norg new file mode 100644 index 000000000..a5aa1458c --- /dev/null +++ b/doc/wiki/Clipboard.norg @@ -0,0 +1,18 @@ + +* `core.clipboard` + +*** Quality of Life Features for the Clipboard + +* Overview + + The clipboard module is a minimal and generic module allowing to overwrite or add special behaviour to the + `y` (yank) keybind in Neovim. + +* Configuration + + This module provides no configuration options! + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Completion.norg b/doc/wiki/Completion.norg new file mode 100644 index 000000000..9a499c36c --- /dev/null +++ b/doc/wiki/Completion.norg @@ -0,0 +1,43 @@ + +* `core.completion` + +*** Get completions in Neorg files + +* Overview + + This module is an intermediary between Neorg and the completion engine of your choice. After setting up this + module (this usually just involves setting the `engine` field in the {# configuration} section), + please read the corresponding wiki page for the engine you selected ({https://github.com/nvim-neorg/neorg/wiki/Nvim-Cmp}[`nvim-cmp`] + {@core.integrations.coq_nvim}[`coq_nvim`] or {https://github.com/nvim-neorg/neorg/wiki/Nvim-Compe}[`nvim-compe`]) to complete setup. + + Completions are provided in the following cases (examples in (), `|||` represents the cursor location): + - TODO items (`|- (||`) + - @ tags (`|@||`) + - # tags (`|#||`) + - file path links (`|{:||`) provides workspace relative paths (`:$/workspace/relative/path:`) + - header links (`|{*||`) + - fuzzy header links (`|{#||`) + - footnotes (`|{^||`) + - file path + header links (`|{:path:*||`) + - file path + fuzzy header links (`|{:path:#||`) + - file path + footnotes (`|{:path:^||`) + - anchor names (`|[||`) + - link names (`|{}[||`) + + Header completions will show only valid headers at the current level in the current or specified file. All + link completions are smart about closing `:` and `}`. + +* Configuration + +** name (string) + + The identifier for the Neorg source. + + default: `"[Neorg]"` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Dirman}[`core.dirman`] - This module is be responsible for managing directories full of .norg files. + - {https://github.com/nvim-neorg/neorg/wiki/Dirman-Utils}[`core.dirman.utils`] - A set of utilities for the `core.dirman` module. + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Concealer.norg b/doc/wiki/Concealer.norg new file mode 100644 index 000000000..e85e35b0a --- /dev/null +++ b/doc/wiki/Concealer.norg @@ -0,0 +1,568 @@ + +* `core.concealer` + +*** Display Markup as Icons, not Text + + The concealer module converts verbose markup elements into beautified icons for your viewing pleasure. + +* Overview + + "Concealing" is the process of hiding away from plain sight. When writing raw Norg, long strings like + `***** Hello` or `$$ Definition` can be distracting and sometimes unpleasant when sifting through large notes. + + To reduce the amount of cognitive load required to "parse" Norg documents with your own eyes, this module + masks, or sometimes completely hides many categories of markup. + + The concealer depends on {https://github.com/ryanoasis/nerd-fonts/releases/latest}[Nerd Fonts >=v3.0.1] to be + installed on your system. + + This module respects `:h conceallevel` and `:h concealcursor`. Setting the wrong values for these options can + make it look like this module isn’t working. + +* Configuration + +** folds (boolean) + + If true, Neorg will enable folding by default for `.norg` documents. + You may use the inbuilt Neovim folding options like `foldnestmax`, + `foldlevelstart` and others to then tune the behaviour to your liking. + + Set to `false` if you do not want Neorg setting anything. + + default: `true` + +** icon_preset (string) + + Which icon preset to use. + + The currently available icon presets are: + + - "basic" - use a mixture of icons (includes cute flower icons!) + - "diamond" - use diamond shapes for headings + - "varied" - use a mix of round and diamond shapes for headings; no cute flower icons though :( + + default: `"basic"` + +** icons (table) + + Configuration for icons. + + This table contains the full configuration set for each icon, including + its query (where to be placed), render functions (how to be placed) and + characters to use. + + For most use cases, the only values that you should be changing is the `icon`/`icons` field. + `icon` is a string, while `icons` is a table of strings for multilevel elements like + headings, lists, and quotes. + + To disable part of the config, replace the table with `false`, or prepend `false and` to it. + For example: `done = false` or `done = false and { ... }`. + +*** code_block (table) + + Options that control the behaviour of code block dimming + (placing a darker background behind `@code` tags). + +**** conceal (boolean) + + If `true` will conceal (hide) the `@code` and `@end` portion of the code + block. + + default: `false` + +**** content_only (boolean) + + If true will only dim the content of the code block (without the + `@code` and `@end` lines), not the entirety of the code block itself. + + default: `true` + +**** highlight (string) + + default: `"@neorg.tags.ranged_verbatim.code_block"` + +**** insert_enabled (boolean) + + default: `true` + +**** nodes (list) + + - \(string) default: `"ranged_verbatim_tag"` + +**** padding (table) + + Additional padding to apply to either the left or the right. Making + these values negative is considered undefined behaviour (it is + likely to work, but it’s not officially supported). + +***** left (number) + + default: `0` + +***** right (number) + + default: `0` + +**** render (function) + + default: `module.public.icon_renderers.render_code_block` + +**** spell_check (boolean) + + If `false` will disable spell check on code blocks when 'spell' option is switched on. + + default: `true` + +**** width (string) + + The width to use for code block backgrounds. + + When set to `fullwidth` (the default), will create a background + that spans the width of the buffer. + + When set to `content`, will only span as far as the longest line + within the code block. + + default: `"fullwidth"` + +*** definition (table) + +**** multi_prefix (table) + +***** icon (string) + + default: `"⋙ "` + +***** nodes (list) + + - \(string) default: `"multi_definition_prefix"` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +**** multi_suffix (table) + +***** icon (string) + + default: `"⋘ "` + +***** nodes (list) + + - \(string) default: `"multi_definition_suffix"` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +**** single (table) + +***** icon (string) + + default: `"≡"` + +***** nodes (table) + + - \(string) default: `"single_definition_prefix"` + - concealed (list) + -- \(string) default: `"link_target_definition"` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +*** delimiter (table) + +**** horizontal_line (table) + +***** highlight (string) + + default: `"@neorg.delimiters.horizontal_line"` + +***** icon (string) + + default: `"─"` + +***** left (string) + The starting position of horizontal lines: + + - "window": the horizontal line starts from the first column, reaching the left of the window + - "here": the horizontal line starts from the node column + + default: `"here"` + +***** nodes (list) + + - \(string) default: `"horizontal_line"` + +***** render (function) + + default: `module.public.icon_renderers.render_horizontal_line` + +***** right (string) + The ending position of horizontal lines: + + - "window": the horizontal line ends at the last column, reaching the right of the window + - "textwidth": the horizontal line ends at column `textwidth` or 79 when it’s set to zero + + default: `"window"` + +**** strong (table) + +***** highlight (string) + + default: `"@neorg.delimiters.strong"` + +***** icon (string) + + default: `"⟪"` + +***** nodes (list) + + - \(string) default: `"strong_paragraph_delimiter"` + +***** render (function) + + default: `module.public.icon_renderers.fill_text` + +**** weak (table) + +***** highlight (string) + + default: `"@neorg.delimiters.weak"` + +***** icon (string) + + default: `"⟨"` + +***** nodes (list) + + - \(string) default: `"weak_paragraph_delimiter"` + +***** render (function) + + default: `module.public.icon_renderers.fill_text` + +*** footnote (table) + +**** multi_prefix (table) + +***** icon (string) + + default: `"⁑ "` + +***** nodes (list) + + - \(string) default: `"multi_footnote_prefix"` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +**** multi_suffix (table) + +***** icon (string) + + default: `"⁑ "` + +***** nodes (list) + + - \(string) default: `"multi_footnote_suffix"` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +**** single (table) + +***** icon (string) + + default: `"⁎"` + +***** nodes (table) + + - \(string) default: `"single_footnote_prefix"` + - concealed (list) + -- \(string) default: `"link_target_footnote"` + +***** numeric_superscript (boolean) + + When set to true, footnote link with numeric title will be + concealed to superscripts. + + default: `true` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +***** render_concealed (function) + + default: `module.public.icon_renderers.footnote_concealed` + +***** title_highlight (string) + + default: `"@neorg.footnotes.title"` + +*** heading (table) + +**** highlights (list) + + - \(string) default: `"@neorg.headings.1.prefix"` + - \(string) default: `"@neorg.headings.2.prefix"` + - \(string) default: `"@neorg.headings.3.prefix"` + - \(string) default: `"@neorg.headings.4.prefix"` + - \(string) default: `"@neorg.headings.5.prefix"` + - \(string) default: `"@neorg.headings.6.prefix"` + +**** icons (list) + + - \(string) default: `"◉"` + - \(string) default: `"◎"` + - \(string) default: `"○"` + - \(string) default: `"✺"` + - \(string) default: `"▶"` + - \(string) default: `"⤷"` + +**** nodes (table) + + - \(string) default: `"heading1_prefix"` + - \(string) default: `"heading2_prefix"` + - \(string) default: `"heading3_prefix"` + - \(string) default: `"heading4_prefix"` + - \(string) default: `"heading5_prefix"` + - \(string) default: `"heading6_prefix"` + - concealed (list) + -- \(string) default: `"link_target_heading1"` + -- \(string) default: `"link_target_heading2"` + -- \(string) default: `"link_target_heading3"` + -- \(string) default: `"link_target_heading4"` + -- \(string) default: `"link_target_heading5"` + -- \(string) default: `"link_target_heading6"` + +**** render (function) + + default: `module.public.icon_renderers.multilevel_on_right(false)` + +*** list (table) + +**** icons (list) + + - \(string) default: `"•"` + +**** nodes (list) + + - \(string) default: `"unordered_list1_prefix"` + - \(string) default: `"unordered_list2_prefix"` + - \(string) default: `"unordered_list3_prefix"` + - \(string) default: `"unordered_list4_prefix"` + - \(string) default: `"unordered_list5_prefix"` + - \(string) default: `"unordered_list6_prefix"` + +**** render (function) + + default: `module.public.icon_renderers.multilevel_on_right(false)` + +*** markup (table) + +**** spoiler (table) + +***** highlight (string) + + default: `"@neorg.markup.spoiler"` + +***** icon (string) + + default: `"•"` + +***** nodes (list) + + - \(string) default: `"spoiler"` + +***** render (function) + + default: `module.public.icon_renderers.fill_multiline_chop2` + +*** ordered (table) + +**** icons (list) + + - \(string) default: `"1."` + - \(string) default: `"A."` + - \(string) default: `"a."` + - \(string) default: `"(1)"` + - \(string) default: `"I."` + - \(string) default: `"i."` + +**** nodes (list) + + - \(string) default: `"ordered_list1_prefix"` + - \(string) default: `"ordered_list2_prefix"` + - \(string) default: `"ordered_list3_prefix"` + - \(string) default: `"ordered_list4_prefix"` + - \(string) default: `"ordered_list5_prefix"` + - \(string) default: `"ordered_list6_prefix"` + +**** render (function) + + default: `module.public.icon_renderers.multilevel_on_right(true)` + +*** quote (table) + +**** clear (function) + + default: `module.public.icon_removers.quote` + +**** highlights (list) + + - \(string) default: `"@neorg.quotes.1.prefix"` + - \(string) default: `"@neorg.quotes.2.prefix"` + - \(string) default: `"@neorg.quotes.3.prefix"` + - \(string) default: `"@neorg.quotes.4.prefix"` + - \(string) default: `"@neorg.quotes.5.prefix"` + - \(string) default: `"@neorg.quotes.6.prefix"` + +**** icons (list) + + - \(string) default: `"│"` + +**** nodes (list) + + - \(string) default: `"quote1"` + - \(string) default: `"quote2"` + - \(string) default: `"quote3"` + - \(string) default: `"quote4"` + - \(string) default: `"quote5"` + - \(string) default: `"quote6"` + +**** render (function) + + default: `module.public.icon_renderers.quote_concealed` + +*** todo (table) + +**** cancelled (table) + +***** icon (string) + + default: `""` + +***** nodes (list) + + - \(string) default: `"todo_item_cancelled"` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +**** done (table) + +***** icon (string) + + default: `"󰄬"` + +***** nodes (list) + + - \(string) default: `"todo_item_done"` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +**** on_hold (table) + +***** icon (string) + + default: `""` + +***** nodes (list) + + - \(string) default: `"todo_item_on_hold"` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +**** pending (table) + +***** icon (string) + + default: `"󰥔"` + +***** nodes (list) + + - \(string) default: `"todo_item_pending"` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +**** recurring (table) + +***** icon (string) + + default: `"↺"` + +***** nodes (list) + + - \(string) default: `"todo_item_recurring"` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +**** uncertain (table) + +***** icon (string) + + default: `""` + +***** nodes (list) + + - \(string) default: `"todo_item_uncertain"` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +**** undone (table) + +***** icon (string) + + default: `"×"` + +***** nodes (list) + + - \(string) default: `"todo_item_undone"` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +**** urgent (table) + +***** icon (string) + + default: `"⚠"` + +***** nodes (list) + + - \(string) default: `"todo_item_urgent"` + +***** render (function) + + default: `module.public.icon_renderers.on_left` + +** init_open_folds (string) + + When set to `auto`, Neorg will open all folds when opening new documents if `foldlevel` is 0. + When set to `always`, Neorg will always open all folds when opening new documents. + When set to `never`, Neorg will not do anything. + + default: `"auto"` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Autocommands}[`core.autocommands`] - Handles the creation and management of Neovim’s autocommands. + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Cookbook.norg b/doc/wiki/Cookbook.norg new file mode 100644 index 000000000..d242cb2c6 --- /dev/null +++ b/doc/wiki/Cookbook.norg @@ -0,0 +1,58 @@ + +* Neorg Cookbook + + This document details a bunch of snippets and prebuilt configurations for individual modules + for a just works experience. + + > [!TIP] + If you’re looking for a quickstart setup to get you started with Neorg, check out the {https://github.com/nvim-neorg/neorg/wiki/Kickstart}[kickstart page] instead. + +** Completion with `nvim-cmp` + +*** Requirements + + - {https://github.com/hrsh7th/nvim-cmp}[`nvim-cmp`] + +*** Steps + + ~ In your Neorg configuration: + @code lua + load = { + ["core.defaults"] = {}, + ["core.completion"] = { + config = { + engine = "nvim-cmp", + } + }, + ["core.integrations.nvim-cmp"] = {}, + } + @end + + ~ In your `nvim-cmp` configuration: + @code lua + sources = cmp.config.sources({ + -- ... your other sources here + { name = "neorg" }, + }) + @end + +** Latex Rendering + +*** Requirements + + - A terminal with kitty graphics protocol support (kitty/ghostty) + - {https://github.com/3rd/image.nvim}[`image.nvim`] installed and set up + +*** Steps + + ~ In your Neorg configuration: + @code lua + load = { + ["core.integrations.image"] = {}, + ["core.latex.renderer"] = {}, + } + @end + + ~ Place some maths within maths blocks (`$| ... |$`): default: `$|Hello, \LaTeX|$` + ~ Run `:Neorg render-latex`. + diff --git a/doc/wiki/Coq_nvim.norg b/doc/wiki/Coq_nvim.norg new file mode 100644 index 000000000..0d38ac2ae --- /dev/null +++ b/doc/wiki/Coq_nvim.norg @@ -0,0 +1,15 @@ + +* `core.integrations.coq_nvim` + +*** Integrating Neorg with `coq_nvim` + +* Overview + + This module works with the {https://github.com/nvim-neorg/neorg/wiki/Completion}[`core.completion`] module to attempt to provide + intelligent completions. Note that integrations like this are second-class citizens and may not work in 100% + of scenarios. If they don’t then please file a bug report! + +* Configuration + + This module provides no configuration options! + diff --git a/doc/wiki/Core-Highlights.norg b/doc/wiki/Core-Highlights.norg new file mode 100644 index 000000000..b90ea5613 --- /dev/null +++ b/doc/wiki/Core-Highlights.norg @@ -0,0 +1,716 @@ + +* `core.highlights` + +*** No Colour Means no Productivity + +* Overview + + `core.highlights` maps all possible highlight groups available throughout + Neorg under a single tree of highlights: `@neorg.*`. + +* Configuration + +** dim (table) + + Handles the dimming of certain highlight groups. + + It sometimes is favourable to use an existing highlight group, + but to dim or brighten it a little bit. + + To do so, you may use this table, which, similarly to the `highlights` table, + will concatenate nested trees to form a highlight group name. + + The difference is, however, that the leaves of the tree are a table, not a single string. + This table has three possible fields: + + - `reference` - which highlight to use as reference for the dimming. + - `percentage` - by how much to darken the reference highlight. This value may be between + `-100` and `100`, where negative percentages brighten the reference highlight, whereas + positive values dim the highlight by the given percentage. + +*** markup (table) + +**** inline_comment (table) + +***** percentage (number) + + default: `40` + +***** reference (string) + + default: `"Normal"` + +**** verbatim (table) + +***** percentage (number) + + default: `20` + +***** reference (string) + + default: `"Normal"` + +*** tags (table) + +**** ranged_verbatim (table) + +***** code_block (table) + +****** affect (string) + + default: `"background"` + +****** percentage (number) + + default: `15` + +****** reference (string) + + default: `"Normal"` + +** highlights (table) + + The TS highlights for each Neorg type. + + The `highlights` table is a large collection of nested trees. At the leaves of each of these + trees is the final highlight to apply to that tree. For example: `"+@comment"` tells Neorg to + link to an existing highlight group `@comment` (denoted by the `+` prefix). When no prefix is + found, the string is treated as arguments passed to `:highlight`, for example: `gui=bold fg=#000000`. + + Nested trees concatenate, thus: + + @code lua + tags = { + ranged_verbatim = { + begin = "+@comment", + }, + } + @end + + matches the highlight group: + + default: `@neorg.tags.ranged_verbatim.begin` + + and converts into the following command: + + default: `highlight! link @neorg.tags.ranged_verbatim.begin @comment` + +*** anchors (table) + + Highlights for the anchor syntax: `[name]{location}`. + +**** declaration (table) + +***** delimiter (string) + + default: `"+NonText"` + +**** definition (table) + +***** delimiter (string) + + default: `"+NonText"` + +*** definitions (table) + + Highlights for definitions (`$ Definition`). + +**** content (string) + + default: `"+@markup.italic"` + +**** prefix (string) + + default: `"+@punctuation.delimiter"` + +**** suffix (string) + + default: `"+@punctuation.delimiter"` + +**** title (string) + + default: `"+@markup.strong"` + +*** delimiters (table) + Highlights for all the delimiter types. These include: + + - `---` - the weak delimiter + - `===` - the strong delimiter + - `___` - the horizontal rule + +**** horizontal_line (string) + + default: `"+@punctuation.delimiter"` + +**** strong (string) + + default: `"+@punctuation.delimiter"` + +**** weak (string) + + default: `"+@punctuation.delimiter"` + +*** error (string) + + In case of errors in the syntax tree, use the following highlight. + + default: `"+Error"` + +*** footnotes (table) + + Highlights for footnotes (`^ My Footnote`). + +**** content (string) + + default: `"+@markup.italic"` + +**** prefix (string) + + default: `"+@punctuation.delimiter"` + +**** suffix (string) + + default: `"+@punctuation.delimiter"` + +**** title (string) + + default: `"+@markup.strong"` + +*** headings (table) + + Highlights for each individual heading level. + +**** 1 (table) + +***** prefix (string) + + default: `"+@attribute"` + +***** title (string) + + default: `"+@attribute"` + +**** 2 (table) + +***** prefix (string) + + default: `"+@label"` + +***** title (string) + + default: `"+@label"` + +**** 3 (table) + +***** prefix (string) + + default: `"+@constant"` + +***** title (string) + + default: `"+@constant"` + +**** 4 (table) + +***** prefix (string) + + default: `"+@string"` + +***** title (string) + + default: `"+@string"` + +**** 5 (table) + +***** prefix (string) + + default: `"+@label"` + +***** title (string) + + default: `"+@label"` + +**** 6 (table) + +***** prefix (string) + + default: `"+@constructor"` + +***** title (string) + + default: `"+@constructor"` + +*** links (table) + +**** description (table) + +***** delimiter (string) + + default: `"+NonText"` + +**** file (table) + +***** delimiter (string) + + default: `"+NonText"` + +**** location (table) + +***** definition (table) + +****** prefix (string) + + default: `"+@neorg.definitions.prefix"` + +***** delimiter (string) + + default: `"+NonText"` + +***** external_file (table) + +****** prefix (string) + + default: `"+@label"` + +***** footnote (table) + +****** prefix (string) + + default: `"+@neorg.footnotes.prefix"` + +***** generic (table) + +****** prefix (string) + + default: `"+@type"` + +***** heading (table) + +****** 1 (table) + +******* prefix (string) + + default: `"+@neorg.headings.1.prefix"` + +****** 2 (table) + +******* prefix (string) + + default: `"+@neorg.headings.2.prefix"` + +****** 3 (table) + +******* prefix (string) + + default: `"+@neorg.headings.3.prefix"` + +****** 4 (table) + +******* prefix (string) + + default: `"+@neorg.headings.4.prefix"` + +****** 5 (table) + +******* prefix (string) + + default: `"+@neorg.headings.5.prefix"` + +****** 6 (table) + +******* prefix (string) + + default: `"+@neorg.headings.6.prefix"` + +***** marker (table) + +****** prefix (string) + + default: `"+@neorg.markers.prefix"` + +***** url (string) + + default: `"+@markup.link.url"` + +*** lists (table) + + Highlights for all the possible levels of ordered and unordered lists. + +**** ordered (table) + +***** prefix (string) + + default: `"+@keyword.repeat"` + +**** unordered (table) + +***** prefix (string) + + default: `"+@markup.list"` + +*** markup (table) + + Highlights for inline markup. + + This is all the highlights like `bold`, `italic` and so on. + +**** bold (table) + +***** delimiter (string) + + default: `"+NonText"` + +**** free_form_delimiter (string) + + default: `"+NonText"` + +**** inline_comment (table) + +***** delimiter (string) + + default: `"+NonText"` + +**** inline_math (table) + +***** delimiter (string) + + default: `"+NonText"` + +**** italic (table) + +***** delimiter (string) + + default: `"+NonText"` + +**** spoiler (table) + +***** delimiter (string) + + default: `"+NonText"` + +**** strikethrough (table) + +***** delimiter (string) + + default: `"+NonText"` + +**** subscript (table) + +***** delimiter (string) + + default: `"+NonText"` + +**** superscript (table) + +***** delimiter (string) + + default: `"+NonText"` + +**** underline (table) + +***** delimiter (string) + + default: `"+NonText"` + +**** variable (table) + +***** delimiter (string) + + default: `"+NonText"` + +**** verbatim (table) + +***** delimiter (string) + + default: `"+NonText"` + +*** modifiers (table) + + Inline modifiers. + + This includes: + + - `~` - the trailing modifier + - All link characters (`{`, `}`, `[`, `]`, `<`, `>`) + - The escape character (`\`) + +**** escape (string) + + default: `"+@type"` + +**** link (string) + + default: `"+NonText"` + +*** quotes (table) + + Highlights for all the possible levels of quotes. + +**** 1 (table) + +***** content (string) + + default: `"+@punctuation.delimiter"` + +***** prefix (string) + + default: `"+@punctuation.delimiter"` + +**** 2 (table) + +***** content (string) + + default: `"+Blue"` + +***** prefix (string) + + default: `"+Blue"` + +**** 3 (table) + +***** content (string) + + default: `"+Yellow"` + +***** prefix (string) + + default: `"+Yellow"` + +**** 4 (table) + +***** content (string) + + default: `"+Red"` + +***** prefix (string) + + default: `"+Red"` + +**** 5 (table) + +***** content (string) + + default: `"+Green"` + +***** prefix (string) + + default: `"+Green"` + +**** 6 (table) + +***** content (string) + + default: `"+Brown"` + +***** prefix (string) + + default: `"+Brown"` + +*** rendered (table) + + Rendered Latex, this will dictate the foreground color of latex images rendered via + core.latex.renderer + +**** latex (string) + + default: `"+Normal"` + +*** selection_window (table) + + Highlights displayed in Neorg selection window popups. + +**** arrow (string) + + default: `"+@none"` + +**** heading (string) + + default: `"+@annotation"` + +**** key (string) + + default: `"+@module"` + +**** keyname (string) + + default: `"+@constant"` + +**** nestedkeyname (string) + + default: `"+@string"` + +*** tags (table) + + Highlights displayed in all sorts of tag types. + + These include: `@`, `.`, `|||`, `#`, `+` and `=`. + +**** carryover (table) + + Highlights for the carryover (`#`, `+`) tags. + +***** begin (string) + + default: `"+@label"` + +***** name (table) + +****** delimiter (string) + + default: `"+@none"` + +****** word (string) + + default: `"+@label"` + +***** parameters (string) + + default: `"+@string"` + +**** comment (table) + + Highlights for the content of any tag named `comment`. + + Most prominent use case is for the `#comment` carryover tag. + +***** content (string) + + default: `"+@comment"` + +**** ranged_verbatim (table) + + Highlights for the `@` verbatim tags. + +***** begin (string) + + default: `"+@keyword"` + +***** document_meta (table) + +****** array (table) + +******* bracket (string) + + default: `"+@punctuation.bracket"` + +******* value (string) + + default: `"+@none"` + +****** authors (string) + + default: `"+@annotation"` + +****** categories (string) + + default: `"+@keyword"` + +****** created (string) + + default: `"+@number.float"` + +****** description (string) + + default: `"+@label"` + +****** key (string) + + default: `"+@variable.member"` + +****** number (string) + + default: `"+@number"` + +****** object (table) + +******* bracket (string) + + default: `"+@punctuation.bracket"` + +****** title (string) + + default: `"+@markup.heading"` + +****** trailing (string) + + default: `"+@keyword.repeat"` + +****** updated (string) + + default: `"+@number.float"` + +****** value (string) + + default: `"+@string"` + +****** version (string) + + default: `"+@number.float"` + +***** end (string) + + default: `"+@keyword"` + +***** name (table) + +****** delimiter (string) + + default: `"+@none"` + +****** word (string) + + default: `"+@keyword"` + +***** parameters (string) + + default: `"+@type"` + +*** todo_items (table) + + Highlights for TODO items. + + This strictly covers the `( )` component of any detached modifier. In other words, these + highlights only bother with highlighting the brackets and the content within, but not the + object containing the TODO item itself. + +**** cancelled (string) + + default: `"+NonText"` + +**** done (string) + + default: `"+@string"` + +**** on_hold (string) + + default: `"+@comment.note"` + +**** pending (string) + + default: `"+@module"` + +**** recurring (string) + + default: `"+@keyword.repeat"` + +**** uncertain (string) + + default: `"+@boolean"` + +**** undone (string) + + default: `"+@punctuation.delimiter"` + +**** urgent (string) + + default: `"+@comment.error"` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Autocommands}[`core.autocommands`] - Handles the creation and management of Neovim’s autocommands. + +* Required By + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + - {https://github.com/nvim-neorg/neorg/wiki/Core-Latex-Renderer}[`core.latex.renderer`] - An experimental module for rendering latex images inline. + diff --git a/doc/wiki/Core-Latex-Renderer.norg b/doc/wiki/Core-Latex-Renderer.norg new file mode 100644 index 000000000..20b7c3f89 --- /dev/null +++ b/doc/wiki/Core-Latex-Renderer.norg @@ -0,0 +1,81 @@ + +* `core.latex.renderer` + +*** Rendering LaTeX with image.nvim + +* Overview + + This is an experimental module that requires nvim 0.10+. It renders LaTeX snippets as images + making use of the image.nvim plugin. By default, images are only rendered after running the + command: `:Neorg render-latex`. Rendering can be disabled with `:Neorg render-latex disable` + + Requires: + - The {https://github.com/3rd/image.nvim}[image.nvim] neovim plugin. + - `latex` executable in path with the following packages: + - standalone + - amsmath + - amssymb + - graphicx + - `dvipng` executable in path (normally comes with LaTeX) + + There’s a highlight group that controls the foreground color of the rendered latex: + `@norg.rendered.latex`, configurable in `core.highlights` + +* Configuration + +** conceal (boolean) + + When true, images of rendered LaTeX will cover the source LaTeX they were produced from. + Setting this value to false creates more lag, and can be buggy with large numbers of images. + + default: `true` + +** debounce_ms (number) + + Don’t re-render anything until 200ms after the buffer has stopped changing. Lowering will + lead to a more seamless experience but will cause more temporary images to be created + + default: `200` + +** dpi (number) + + "Dots Per Inch" increasing this value will result in crisper images at the expense of + performance + + default: `350` + +** min_length (number) + + Only render latex snippets that are longer than this many chars. Escaped chars are removed + spaces are counted, `$` and `|$||`/`||$|` are not (ie. `$\\int$` counts as 4 chars) + + default: `3` + +** render_on_enter (boolean) + + When true, images will render when a `.norg` buffer is entered + + default: `false` + +** renderer (string) + + Module that renders the images. "core.integrations.image" makes use of image.nvim and is + currently the only option + + default: `"core.integrations.image"` + +** scale (number) + + Make the images larger or smaller by adjusting the scale. Will not pad images with virtual + text when `conceal = true`, so they can overlap text. Images will not be blown up larger than + their true size, so images may still render one line tall. + + default: `1` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Autocommands}[`core.autocommands`] - Handles the creation and management of Neovim’s autocommands. + - {https://github.com/nvim-neorg/neorg/wiki/Core-Highlights}[`core.highlights`] - Manages your highlight groups with this module. + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + - {https://github.com/nvim-neorg/neorg/wiki/Neorgcmd-Module}[`core.neorgcmd`] - This module deals with handling everything related to the `:Neorg` command. + diff --git a/doc/wiki/Core-Presenter.norg b/doc/wiki/Core-Presenter.norg new file mode 100644 index 000000000..c660e81de --- /dev/null +++ b/doc/wiki/Core-Presenter.norg @@ -0,0 +1,36 @@ + +* `core.presenter` + +*** Powerpoint in Neorg + + The presenter module creates slideshows out of notes or documents. + +* Overview + + The presenter module provides a special Neorg display that resembles an active slideshow + presentation. + + To set it up, first be sure to set the `zen_mode` variable in the {# configuration}. + Afterwards, run `:Neorg presenter start` on any Norg file. The presenter will split up your file + at each level 1 heading, and display each in a different slide. + + NOTE: This module is due for a rewrite. All of its behaviour is not fully documented here as it will be + overwritten soon anyway. + +* Configuration + +** zen_mode (string) + + Zen mode plugin to use. Currenly suppported: + + - `zen-mode` - https://github.com/folke/zen-mode.nvim + - `truezen` - https://github.com/Pocco81/TrueZen.nvim + + default: `""` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + - {https://github.com/nvim-neorg/neorg/wiki/Queries-Module}[`core.queries.native`] - TS wrapper in order to fetch nodes using a custom table. + - {https://github.com/nvim-neorg/neorg/wiki/Core-UI}[`core.ui`] - A set of public functions to help developers create and manage UI (selection popups, prompts…) in their modules. + diff --git a/doc/wiki/Core-UI.norg b/doc/wiki/Core-UI.norg new file mode 100644 index 000000000..f07f00249 --- /dev/null +++ b/doc/wiki/Core-UI.norg @@ -0,0 +1,18 @@ + +* `core.ui` + +*** Module for managing and displaying UIs to the user. + +* Configuration + + This module provides no configuration options! + +* Required By + + - {https://github.com/nvim-neorg/neorg/wiki/Dirman}[`core.dirman`] - This module is be responsible for managing directories full of .norg files. + - {https://github.com/nvim-neorg/neorg/wiki/Esupports-Hop}[`core.esupports.hop`] - "Hop" between Neorg links, following them with a single keypress. + - {https://github.com/nvim-neorg/neorg/wiki/Looking-Glass}[`core.looking-glass`] - Allows for editing of code blocks within a separate buffer. + - {https://github.com/nvim-neorg/neorg/wiki/Core-Presenter}[`core.presenter`] - Neorg module to create gorgeous presentation slides. + - {https://github.com/nvim-neorg/neorg/wiki/TOC}[`core.qol.toc`] - Generates a table of contents for a given Norg buffer. + - {https://github.com/nvim-neorg/neorg/wiki/Calendar}[`core.ui.calendar`] - Opens an interactive calendar for date-related tasks. + diff --git a/doc/wiki/Default-Keybinds.norg b/doc/wiki/Default-Keybinds.norg new file mode 100644 index 000000000..3492cb844 --- /dev/null +++ b/doc/wiki/Default-Keybinds.norg @@ -0,0 +1,141 @@ + +* :keyboard: Neorg Keybinds :keyboard: + + A comprehensive list of all keys available in Neorg. + +*** Further Reading + + To find out how to rebind the available keys consult the {https://github.com/nvim-neorg/neorg/wiki/User-Keybinds}[`core.keybinds`] wiki entry. + +** Preset `neorg` // All Files + +*** Normal Mode + +**** `nn` - create a new `.norg` file to take notes in + + - Maps to: `(neorg.dirman.new-note)` + - Mnemonic: new note + +** Preset `neorg` // Norg Only + +*** Insert Mode + +**** `` - demote an object recursively + + - Maps to: `(neorg.promo.demote)` + +**** `` - promote an object recursively + + - Maps to: `(neorg.promo.promote)` + +**** `` - create an iteration of e.g. a list item + + - Maps to: `(neorg.itero.next-iteration)` + +**** `` - insert a link to a date at the current cursor position + + - Maps to: `(neorg.tempus.insert-date.insert-mode)` + - Mnemonic: date + +*** Normal Mode + +**** `<,` - demote an object non-recursively + + - Maps to: `(neorg.promo.demote)` + +**** `<<` - demote an object recursively + + - Maps to: `(neorg.promo.demote.nested)` + +**** `` - switch the task under the cursor between a select few states + + - Maps to: `(neorg.qol.todo-items.todo.task-cycle)` + +**** `` - hop to the destination of the link under the cursor + + - Maps to: `(neorg.esupports.hop.hop-link)` + +**** `cm` - magnifies a code block to a separate buffer. + + - Maps to: `(neorg.looking-glass.magnify-code-block)` + - Mnemonic: code magnify + +**** `id` - insert a link to a date at the given position + + - Maps to: `(neorg.tempus.insert-date)` + - Mnemonic: insert date + +**** `li` - invert all items in a list + + Unlike `lt`, inverting a list will respect mixed list + items, instead of snapping all list types to a single one. + - Maps to: `(neorg.pivot.list.invert)` + - Mnemonic: list invert + +**** `lt` - toggle a list from ordered <-> unordered + + - Maps to: `(neorg.pivot.list.toggle)` + - Mnemonic: list toggle + +**** `ta` - mark the task under the cursor as "ambiguous" + + - Maps to: `(neorg.qol.todo-items.todo.task-ambiguous)` + - Mnemonic: mark task as ambiguous + +**** `tc` - mark the task under the cursor as "cancelled" + + - Maps to: `(neorg.qol.todo-items.todo.task-cancelled)` + - Mnemonic: mark task as cancelled + +**** `td` - mark the task under the cursor as "done" + + - Maps to: `(neorg.qol.todo-items.todo.task-done)` + - Mnemonic: mark task as done + +**** `th` - mark the task under the cursor as "on-hold" + + - Maps to: `(neorg.qol.todo-items.todo.task-on-hold)` + - Mnemonic: mark task as on hold + +**** `ti` - mark the task under the cursor as "important" + + - Maps to: `(neorg.qol.todo-items.todo.task-important)` + - Mnemonic: mark task as important + +**** `tp` - mark the task under the cursor as "pending" + + - Maps to: `(neorg.qol.todo-items.todo.task-pending)` + - Mnemonic: mark task as pending + +**** `tr` - mark the task under the cursor as "recurring" + + - Maps to: `(neorg.qol.todo-items.todo.task-recurring)` + - Mnemonic: mark task as recurring + +**** `tu` - mark the task under the cursor as "undone" + + - Maps to: `(neorg.qol.todo-items.todo.task-undone)` + - Mnemonic: mark task as undone + +**** `` - same as ``, except open the destination in a vertical split + + - Maps to: `(neorg.esupports.hop.hop-link.vsplit)` + +**** `>.` - promote an object non-recursively + + - Maps to: `(neorg.promo.promote)` + +**** `>>` - promote an object recursively + + - Maps to: `(neorg.promo.promote.nested)` + +*** Visual Mode + +**** `<` - demote objects in range + + - Maps to: `(neorg.promo.demote.range)` + +**** `>` - promote objects in range + + - Maps to: `(neorg.promo.promote.range)` + diff --git a/doc/wiki/Defaults.norg b/doc/wiki/Defaults.norg new file mode 100644 index 000000000..93571287c --- /dev/null +++ b/doc/wiki/Defaults.norg @@ -0,0 +1,30 @@ + +* `core.defaults` + + *** + +* Overview + + This file contains all of the most important modules that any user would want + to have a "just works" experience. + + Individual entries can be disabled via the "disable" flag: + + @code lua + load = { + ["core.defaults"] = { + config = { + disable = { + -- module list goes here + "core.autocommands", + "core.itero", + }, + }, + }, + } + @end + +* Configuration + + This module provides no configuration options! + diff --git a/doc/wiki/Dependencies.norg b/doc/wiki/Dependencies.norg new file mode 100644 index 000000000..609e7ade1 --- /dev/null +++ b/doc/wiki/Dependencies.norg @@ -0,0 +1,205 @@ + +TODO: Rewrite parts of this to be more clear (remove the quotes). + +* Understanding Neorg dependencies + + Neorg depends on a number of moving parts and will only continue to accrue more dependencies to deliver on many of the features in it’s ROADMAP. Many of these features, like tree-sitter support in Neovim, are still marked experimental in their parent projects. This document is intended to help Neorg users navigate these dependencies, but users are always encouraged to refer to the parent projects for appropriate documentation. + +** Neovim + + *Neorg is a Neovim plugin, it is not an app.* Neorg attempts to utilize Neovim features when it makes sense to do so in order to provide a familiar editing environment that corresponds to Neovim and Neovim plugin conventions. However, the project reserves the right to break from those conventions in situations where the project determines that doing so will enable better execution on the project vision. + +*** Terminal Support + + If you are running neovim in a terminal emulator, be aware the terminal emulators are weird things. A particularly good description of terminals is provided by {https://wezfurlong.org/wezterm/what-is-a-terminal.html}[https://wezfurlong.org/wezterm/what-is-a-terminal.html]. A concise statement is that terminal emulators /emulate old terminal hardware, so that the kernel can pretend it is still talking to old terminal hardware/. Over the years, various emulators have wanted to offer capabilities above and beyond what those original terminals offered. Command line programs which wanted to use these extended capabilities needed to know whether or not they were on a supporting terminal, since attempting to use these features without appropriate support might cause bad behavior on terminals that did not support those features. Generally, a program can check the `TERM` environment variable and then lookup the relevant `termcap` or `terminfo` entry in the file system database of `term` files. This requires the system to have an appropriate `term` file installed in the relevant location. Alternatively, some terminal emulators support using escape sequences to query terminal capabilities via the XTVERSION and XTGETTCAP escape sequences, which directly query the emulator. + + If neovim is unable to determine the correct set of terminal capabilities, it may choose conservative defaults that prevent rendering of certain text styles in the terminal, such as italic, strikethrough, undercurl, etc. *For example, `screen` and `tmux` frequently advertise a `TERM` with limited capabilities because they cannot guarantee what kind of terminal emulator will attach to them.* + + /If your terminal font settings do not include appropriate rendering styles, this may also prevent you from seeing text rending in the way you expect./ + + There are a couple of ways that may help determine if terminal support is limiting the display of characters in neovim. + +*** Test outside of neovim + + Check the output of the following: + + @code bash + echo -e "\e[1mbold\e[0m" + echo -e "\e[3mitalic\e[0m" + echo -e "\e[3m\e[1mbold italic\e[0m" + echo -e "\e[4munderline\e[0m" + echo -e "\e[9mstrikethrough\e[0m" + echo -e "\x1B[31mred\e[0m" + + printf "\x1b[58:2::255:0:0m\x1b[4:1msingle\x1b[4:2mdouble\x1b[4:3mcurly\x1b[4:4mdotted\x1b[4:5mdashed\x1b[0m\n" + @end + + If this does not produce what you expect, there is a terminal or a font problem. If it works, but does not work in Neovim, then this may either be a problem with advertising/detecting terminal capabilities or setting highlight groups. + +**** Windows ConPTY does not support undercurl + + Windows terminal emulators almost all use ConPTY, which strips out certain escape sequences, including those used for more advanced underlines. There is an open ticket for this feature in `microsoft/terminal` but it is unknown when it will become a priority to address given that terminal support is not generally a Microsoft business priority. + +*** Check neovim diagnostics + + `nvim -V3log` will produce a file named `log`. After exiting, check the `log` file for a section beginning with `--- Terminal info ---`. + + `:checkhealth` will run some neovim diagnostics and open them in a new `:h tabpage`. You can use `:q` to exit the tab. This will include a section on the `terminal` and in some cases identifies `TERM` settings which may cause problems and how to address them + +**** Check that neovim is able to render these characters in other contexts + + ~ `:highlight mytest cterm=italic gui=italic` will create a highlight group named `mytest`. + ~ `:highlight mytest` will show a line that looks like `mytest /xxx/ cterm=italic gui=italic`. The `xxx` should be rendered /in the format specified/ (in this case italics). If not, Neovim is likely not getting the correct terminal capabilities. + ~ Test for any other format which you are concerned is not appearing correctly. + +**** Check that highlight groups are getting assigned correctly and have an appropriate definition + + See {#tree-sitter}[Tree-sitter] and {# Colorschemes} for this. + +*** Ensure your fonts support bold/italic/underline + + Usually terminal emulators automatically set up bold/italic/underline fonts, but these sometimes may fail. + Kitty is the most popularly used terminal emulator and some fonts are known to not have detectable "auto" bold fonts (for example Source Code Pro). + To fix this, go to your terminal emulator’s configuration and manually set the bold and italic fonts (e.g. `Source Code Pro Bold` and `Source Code Pro Italic`). + For kitty, this means: + + @code + bold_font Source Code Pro Bold + italic_font Source Code Pro Italic + bold_italic_font auto + @end + +** Tree-sitter + + Parsing of `.norg` documents in `neorg` is primarily handled by the `tree-sitter` library. + +*** Tree-sitter support in neovim + + Tree-sitter functionality is provided natively by Neovim, *but native support is not the same as supported with no configuration*. Neovim is only responsible for loading a binary **.so* file, providing facilities for executing queries against the parse tree, and for creating highlight groups and indent rules based on those queries when they are defined in an appropriate file location. Supplying these parser and query files is the responsibility of the user or may be delegated by the user to a plugin. See `:h treesitter-parsers` for more details on how Neovim locates its tree-sitter parsers and `:h treesitter-query` and `:h treesitter-highlight` for details on the runtimepath files like `queries/*/highlights.scm`. + +*** Nvim-treesitter plugin + + To make things easier the {https://github.com/nvim-treesitter/nvim-treesitter}[`nvim-treesitter`] plugin provides best-effort configuration support for downloading tree-sitter grammars (source code) from their repositories, compiling them automatically, and placing them in the correct paths along with appropriate highlight and other queries. + + `nvim-treesitter`, in turn, outsources its language-specific efforts to repositories of the form `tree-sitter-`. See the project repo for more details. + + *In order for Neorg to work properly, these features must be enabled when you load and `setup()` nvim-treesitter, especially the highlight module.* See {https://github.com/nvim-treesitter/nvim-treesitter#modules}[https://github.com/nvim-treesitter/nvim-treesitter#modules] for more details on how to do this. Within Neovim, you can run `:TSConfigInfo` to ensure that `modules.enable.highlight` has the expected value. + +**** C/C++ Toolchain + + In order for `nvim-treesitter` to properly build the `tree-sitter-norg` parser, it requires an appropriate compiler toolchain. Ensure that the `CC` environment variable points to a compiler that has C++14 support. + +***** MacOS C/C++ Toolchain often outdated + + The compiler bundled with many editions of MacOS lacks the appropriate level of support. You can run Neovim like so: `CC=/path/to/newer/compiler nvim -c "TSInstallSync norg"` in your shell of choice to install the Neorg parser with a newer compiler. You may also want to export the CC variable in general: `export CC=/path/to/newer/compiler`. + +*** Tree-sitter-norg + + As many of the features of `neorg` depend on proper `tree-sitter`-based parsing of the `.norg` document, it is important to ensure that you update `neorg` and the `tree-sitter-norg` parser at the same time. + + The manual way to do this is that after your `git pull` to update the `neorg` plugin, you call `nvim -c "TSInstallSync norg"`. + + The easiest way to do this is by using a {# Plugin Manager}. + +** Plugin Manager + + Plugin managers reduce the burden of maintaining a (Neo)vim configuration by providing mechanisms to automate repetitive tasks, most notably for updating groups of plugins and ensuring that plugin updates trigger additional commands, such as updating the `tree-sitter-norg` parser. + + Many users also appreciate the ability to lazy-load plugins and reduce Neovim starting time; however, lazy loading complicates the loading order of plugins and this is frequently misconfigured. *Therefore, we recommend lazy loading be disabled when troubleshooting an issue to ensure that packages are loading in the order you believe.* In many plugin managers, this includes keys like `ft`, `cmd`, `event`, etc. + + Importantly, plugin managers are not meant to prevent users from understanding {# Neovim}. Neovim understands how to find plugin files on the basis of its `:h runtimepath`. Plugin managers add appropriate entries to that path when it is time to load a plugin. + + They also make it possible to express a `Neovim` configuration which has multiple plugins (and therefore spans many files and directories) within a single file for the purposes of sharing configurations. + +*** Lazy.nvim + + Here is an example minimal `init.lua` which utilizes {https://github.com/folke/lazy.nvim}['lazy.nvim']: + + @code lua + -- bootstrap lazy.nvim + local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim" + if not vim.loop.fs_stat(lazypath) then + vim.fn.system({ + "git", + "clone", + "--filter=blob:none", + "https://github.com/folke/lazy.nvim.git", + "--branch=stable", -- latest stable release + lazypath, + }) + end + vim.opt.rtp:prepend(lazypath) + + require('lazy').setup({ + { + "nvim-neorg/neorg", + build = ":Neorg sync-parsers", + opts = { + load = { + ["core.defaults"] = {}, -- Loads default behaviour + ["core.concealer"] = {}, -- Adds pretty icons to your documents + ["core.dirman"] = { -- Manages Neorg workspaces + config = { + workspaces = { + notes = "~/notes", + }, + default_workspace = "notes", + }, + }, + }, + }, + dependencies = { + { "nvim-lua/plenary.nvim", }, + { + -- YOU ALMOST CERTAINLY WANT A MORE ROBUST nvim-treesitter SETUP + -- see https://github.com/nvim-treesitter/nvim-treesitter + "nvim-treesitter/nvim-treesitter", + opts = { + auto_install = true, + highlight = { + enable = true, + additional_vim_regex_highlighting = false, + }, + }, + config = function(_,opts) + require('nvim-treesitter.configs').setup(opts) + end + }, + { "folke/tokyonight.nvim", config=function(_,_) vim.cmd.colorscheme "tokyonight-storm" end,}, + }, + }, + }) + @end + +*** Packer.nvim + + I do not use Packer.nvim and cannot provide direct help for this package manager. However, it is common to see Packer problems which stem from `:PackerCompile` not being called after an update, resulting in incorrect things being cached. + +** Colorschemes + + A lightweight text markup plugin like `neorg` benefits from being able to display text-decorations like *bold* and /italic/, as well as highlighting headings in different colors. Neovim users often have colorschemes configured already, which may be among the default colorschemes bundled with Neovim or be one installed from an online source like Github. + + A full description of vim highlighting is best left to `:h highlight` and `:h syntax`. Suffice it to say that /syntax/ files use regular expressions to identify areas of text and mark them as belonging to some /highlight group/. Neovim extends this with `:h treesitter-highlight` to provide another mechanism of assigning /highlight groups/. `:h highlight` then allows users or colorschemes to define how highlight groups should appear. + + Vim has defined a set of `:h highlight-groups` with `:h group-name` naming conventions which have been conserved for a long time. However, many plugins define their own highlight-groups to allow for more specific theming. Well-behaved plugins generally provide fallbacks which link to one of these conserved highlight-groups in case the colorscheme does not define an appearance for the plugin-specific highlight group. However, the conserved set is primarily defined with programming in mind. Thus, there is no highlight-group which is guaranteed to be *bold*. `nvim-treesitter` attempts to standardize a set of names for highlight-groups which provide expanded functionality, such as `@text.strong`, based on community consensus. See {https://github.com/nvim-treesitter/nvim-treesitter/blob/master/CONTRIBUTING.md}[https://github.com/nvim-treesitter/nvim-treesitter/blob/master/CONTRIBUTING.md] for a full list of these groups. + + `neorg` uses many of these new conserved tree-sitter highlight groups as fallbacks for its plugin-specific highlight groups. Because this is a relatively new development, and because these groups are being promulgated by a plugin instead of Neovim core, many colorschemes *including the ones bundled with Neovim* do not support these new highlight groups. `:highlight @text.strong` will tell you the definition that Neovim currently has for that group. `tokyonight` and `kanagawa` are two themes which are known to support the relevant tree-sitter highlight-groups. + +** Concealing + + Although the purpose of a lightweight markup language is to produce documents that remain readable even in plain-text, it is often nice from a readability standpoint to be able to conceal the markup from view. + + Neorg, through it’s `core.conceal` module, is designed to substitute many characters with more aesthetic choices, hide the multiple characters in e.g. headlines and lists, and conceal link URLs and other markup. It achieves this by setting the `:h conceal` argument on the highlight group. On its own, this only applies a `conceal` tag to the highlight group. Users must configure their `:h conceallevel` and `:h concealcursor` to actually hide the text, as the default `conceallevel` setting does not conceal any text. This is good default Neovim behavior since only people who are aware of the `conceallevel` options and functionality will have text hidden from them. + +*** Ugly line wraps when concealing text + + There is a known bug in how concealing interacts with wrapped lines. This is a long-standing vim and Neovim behavior with no easy fix since it touches on complex rendering and UI logic to allow performant and logical editing on a file from within a window which displays contents which differ from buffer contents. + + There is a Neovim effort underway known as `anticonceal` which should hopefully address this bug. However, like all things, time is limited and priorities must be balanced and this is not an easy bug to address. Discussions around this bug have been ongoing for several years - if it is so pressing to your use case, implement a fix yourself or pay someone to do so at market rates. + + Having said all that, as users of Neorg, we also regularly deal with this bug. Some suggested option of workflows that accommodate for this behavior include the following: + 1. Do not use conceal + 2. Use hard wrap (`:h formatting`) and manually insert line breaks so that the concealed text wraps in a manner that suits your requirements + 3. Use soft wrap (`:h wrap`) in combination with the anchors features described in the {https://github.com/nvim-neorg/norg-specs}[norg-specs] to separate the link usage from its definition. This mitigates the rendering issues in Neovim by reducing the number of characters which must be concealed, resulting in better reflow behavior in most cases. Be cognizant that anchor names will need to be unique for linking to operate as expected. + - For a better editing experience, you may also be interested in `:h linebreak`, `:h breakindent` and `:h breakindentopt`. + diff --git a/doc/wiki/Dirman-Utils.norg b/doc/wiki/Dirman-Utils.norg new file mode 100644 index 000000000..464bdf0e4 --- /dev/null +++ b/doc/wiki/Dirman-Utils.norg @@ -0,0 +1,21 @@ + +* `core.dirman.utils` + + *** + +* Overview + + This internal submodule implements some basic utility functions for {https://github.com/nvim-neorg/neorg/wiki/Dirman}[`core.dirman`]. + Currently the only exposed API function is `expand_path`, which takes a path like `$name/my/location` and + converts `$name` into the full path of the workspace called `name`. + +* Configuration + + This module provides no configuration options! + +* Required By + + - {https://github.com/nvim-neorg/neorg/wiki/Completion}[`core.completion`] - A wrapper to interface with several different completion engines. + - {https://github.com/nvim-neorg/neorg/wiki/Dirman}[`core.dirman`] - This module is be responsible for managing directories full of .norg files. + - {https://github.com/nvim-neorg/neorg/wiki/Esupports-Hop}[`core.esupports.hop`] - "Hop" between Neorg links, following them with a single keypress. + diff --git a/doc/wiki/Dirman.norg b/doc/wiki/Dirman.norg new file mode 100644 index 000000000..e7122f392 --- /dev/null +++ b/doc/wiki/Dirman.norg @@ -0,0 +1,111 @@ + +* `core.dirman` + +*** The Most Critical Component of any Organized Workflow + + The `dirman` module handles different collections of notes in separate directories. + +* Overview + + `core.dirman` provides other modules the ability to see which directories the user is in, where + each note collection is stored and how to interact with it. + + When writing notes, it is often crucial to have notes on a certain topic be isolated from notes on another topic. + Dirman achieves this with a concept of "workspaces", which are named directories full of `.norg` notes. + + To use `core.dirman`, simply load up the module in your configuration and specify the directories you would like to be managed for you: + + @code lua + require('neorg').setup { + load = { + ["core.defaults"] = {}, + ["core.dirman"] = { + config = { + workspaces = { + my_ws = "~/neorg", -- Format: = + my_other_notes = "~/work/notes", + }, + index = "index.norg", -- The name of the main (root) .norg file + } + } + } + } + @end + + To query the current workspace, run `:Neorg workspace`. To set the workspace, run `:Neorg workspace `. + +*** Changing the Current Working Directory + + After a recent update `core.dirman` will no longer change the current working directory after switching + workspace. To get the best experience it’s recommended to set the `autochdir` Neovim option. + +*** Create a new note + + You can use dirman to create new notes in your workspaces. + + @code lua + local dirman = require('neorg').modules.get_module("core.dirman") + dirman.create_file("my_file", "my_ws", { + no_open = false, -- open file after creation? + force = false, -- overwrite file if exists + metadata = {} -- key-value table for metadata fields + }) + @end + +* Configuration + +** default_workspace (nil) + + The default workspace to set whenever Neovim starts. + + default: `nil` + +** index (string) + + The name for the index file. + + The index file is the "entry point" for all of your notes. + + default: `"index.norg"` + +** open_last_workspace (boolean) + + Whether to open the last workspace’s index file when `nvim` is executed + without arguments. + + May also be set to the string `"default"`, due to which Neorg will always + open up the index file for the workspace defined in `default_workspace`. + + default: `false` + +** use_popup (boolean) + + Whether to use core.ui.text_popup for `dirman.new.note` event. + if `false`, will use vim’s default `vim.ui.input` instead. + + default: `true` + +** workspaces (table) + + The list of active Neorg workspaces. + + There is always an inbuilt workspace called `default`, whose location is + set to the Neovim current working directory on boot. + @type [type] table + + *** default (table) + + default: `require("pathlib").cwd()` + + * Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Autocommands}[`core.autocommands`] - Handles the creation and management of Neovim’s autocommands. + - {https://github.com/nvim-neorg/neorg/wiki/Dirman-Utils}[`core.dirman.utils`] - A set of utilities for the `core.dirman` module. + - {https://github.com/nvim-neorg/neorg/wiki/Storage}[`core.storage`] - Deals with storing persistent data across Neorg sessions. + - {https://github.com/nvim-neorg/neorg/wiki/Core-UI}[`core.ui`] - A set of public functions to help developers create and manage UI (selection popups, prompts…) in their modules. + + * Required By + + - {https://github.com/nvim-neorg/neorg/wiki/Completion}[`core.completion`] - A wrapper to interface with several different completion engines. + - {https://github.com/nvim-neorg/neorg/wiki/Journal}[`core.journal`] - Easily track a journal within Neorg. + diff --git a/doc/wiki/Esupports-Hop.norg b/doc/wiki/Esupports-Hop.norg new file mode 100644 index 000000000..0beee1633 --- /dev/null +++ b/doc/wiki/Esupports-Hop.norg @@ -0,0 +1,44 @@ + +* `core.esupports.hop` + +*** Follow Various Link Locations + + `esupport.hop` handles the process of dealing with links so you don’t have to + +* Overview + + The hop module serves to provide an easy way to follow and fix broken links with a single keypress. + + By default, pressing `` in normal mode under a link will attempt to follow said link. + If the link location is found, you will be taken to the destination - if it is not, you will be + prompted with a set of actions that you can perform on the broken link. + +* Configuration + +** external_filetypes (empty list) + + List of strings specifying which filetypes to open in an external application, + should the user want to open a link to such a file. + +** fuzzing_threshold (number) + + This value determines the strictness of fuzzy matching when trying to fix a link. + Zero means only exact matches will be found, and higher values mean more lenience. + + `0.5` is the optimal default value, and it is recommended to keep this option as-is. + + default: `0.5` + +** lookahead (boolean) + + If true, will attempt to find a link further than your cursor on the current line, + even if your cursor is not over the link itself. + + default: `true` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Dirman-Utils}[`core.dirman.utils`] - A set of utilities for the `core.dirman` module. + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + - {https://github.com/nvim-neorg/neorg/wiki/Core-UI}[`core.ui`] - A set of public functions to help developers create and manage UI (selection popups, prompts…) in their modules. + diff --git a/doc/wiki/Exporting-Files.norg b/doc/wiki/Exporting-Files.norg new file mode 100644 index 000000000..476e833b4 --- /dev/null +++ b/doc/wiki/Exporting-Files.norg @@ -0,0 +1,42 @@ + +* `core.export` + +*** Convert Neorg Files to other Filetypes with `core.export` + +* Overview + + When sending files to people not invested in Neorg it’s nice to be able to use a format + that /they/ use. The `core.export` module is a backend module providing functionality + to write your own exporter for any given filetype. + + All export functionality is provided by the `:Neorg export` command. + + To export the currently opened buffer to another file format, you should use the `:Neorg export to-file` command. + The command takes the following arguments: + - `path` - the path to export to. Examples are: `my-file.md`, `~/output.md`. + If the second argument is not provided Neorg will try to infer the filetype to convert to through + the file extension. + - `filetype` (optional) - the filetype to export to. Useful if you want to use a non-standard extension, or + if the filetype you’re using cannot be inferred automatically. Note that this filetype /must/ be a filetype + that Neovim itself provides and/or understands, i.e. `md` or `markd` is not a valid filetype, however `markdown` is. + + Neorg also supports exporting a directory of files: this is where the `:Neorg export directory` command comes into play. + It takes 3 arguments: + - `directory` - the directory to export + - `filetype` - the filetype to export to + - `output-dir` (optional) - a custom output directory to use. If not provided will fall back to `config.public.export_dir` + (see {# configuration}). + +* Configuration + +** export_dir (string) + + The directory to export to when running `:Neorg export directory`. + The string can be formatted with the special keys: `` and ``. + + default: `"/-export"` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Filesystem.norg b/doc/wiki/Filesystem.norg new file mode 100644 index 000000000..5d6a5173a --- /dev/null +++ b/doc/wiki/Filesystem.norg @@ -0,0 +1,14 @@ + +* `core.fs` + +*** Module for Filesystem Operations + +* Overview + + `core.fs` is a small module providing functionality to perform common + operations safely on arbitrary filesystems. + +* Configuration + + This module provides no configuration options! + diff --git a/doc/wiki/Home.norg b/doc/wiki/Home.norg new file mode 100644 index 000000000..58c132bd6 --- /dev/null +++ b/doc/wiki/Home.norg @@ -0,0 +1,97 @@ + +* Welcome to the Neorg wiki! + + Want to know how to properly use Neorg? Your answers are contained here. + +* Kickstart + + If you would like a Neovim setup that has Neorg configured out of the box look no further than the {:Kickstart:}[kickstart guide]! + +* Using Neorg + + Neorg depends on a number of other technologies, all of which have to be correctly configured to keep Neorg running smoothly. + For some help on understanding how your terminal, Neovim, colourschemes, tree-sitter and more come together to produce your Neorg experience (or Neorg problems), see {:Dependencies:}[this document on understanding Neorg dependencies]. + + At first configuring Neorg might be rather scary. I have to define what modules I want to use in the `require('neorg').setup()` function? + I don’t even know what the default available values are! + Don’t worry, there are guides you are free to check out. The {:Tutorial:}[tutorial] guides you through what Neorg is and its basics. + Afterwards, feel free to check out the {:Setup-Guide:}[configuration guide] as well as the {:Cookbook:}[cookbook]. + +* Broken Installation + + Having issues when installing Neorg, specifically past the `8.0.0` version? Check out the {https://github.com/pysan3/Norg-Tutorial/blob/main/MIGRATION-v8.md}[following page] where you can troubleshoot your issue from start to finish. + +* Contributing to Neorg + + Neorg is a very big and powerful tool behind the scenes - way bigger than it may initially seem. + Modules are its core foundation, and building modules is like building lego bricks to form a massive structure. + There’s an in-the-works tutorial dedicated to making modules {https://github.com/andreadev-it/neorg-module-tutorials/blob/main/introduction.md}[right here]! + +* Module naming convention + + Neorg provides default modules, and users can extend Neorg by creating community modules. + We agreed on a module naming convention, and it should be used as is. + This convention should help users know at a glance what function the module serves in the grand scheme of things. + - Core modules: `core.*` + - Integrations with 3rd party software that are emdebbed in neorg: `core.integrations.*` + - External modules: `external.*` + - Integrations with 3rd party software that aren’t emdebbed in neorg: `external.integrations.*` + +* Default Modules + + Neorg comes with some default modules that will be automatically loaded if you require the {:Defaults:}[`core.defaults`] module: + + - {:Clipboard-Code-Blocks:}[`core.clipboard.code-blocks`] - Removes beginning whitespace from text copied from code blocks. + - {:Esupports-Hop:}[`core.esupports.hop`] - "Hop" between Neorg links, following them with a single keypress. + - {:Indent:}[`core.esupports.indent`] - A set of instructions for Neovim to indent Neorg documents. + - {:Metagen:}[`core.esupports.metagen`] - A Neorg module for generating document metadata automatically. + - {:Itero:}[`core.itero`] - Module designed to continue lists, headings and other iterables. + - {:Journal:}[`core.journal`] - Easily track a journal within Neorg. + - {:User-Keybinds:}[`core.keybinds`] - Module for managing keybindings with Neorg mode support. + - {:Looking-Glass:}[`core.looking-glass`] - Allows for editing of code blocks within a separate buffer. + - {:Pivot:}[`core.pivot`] - Toggles the type of list currently under the cursor. + - {:Promo:}[`core.promo`] - Promotes or demotes nestable items within Neorg files. + - {:TOC:}[`core.qol.toc`] - Generates a table of contents for a given Norg buffer. + - {:Todo-Items:}[`core.qol.todo_items`] - Module for implementing todo lists. + - {:Tangling:}[`core.tangle`] - An Advanced Code Block Exporter. + - {:Todo-Introspector:}[`core.todo-introspector`] - Module for displaying progress of completed subtasks in the virtual line. + - {:Calendar:}[`core.ui.calendar`] - Opens an interactive calendar for date-related tasks. + +* Other Modules + + Some modules are not included by default as they require some manual configuration or are merely extra bells and whistles + and are not critical to editing `.norg` files. Below is a list of all modules that are not required by default: + + - {:Completion:}[`core.completion`] - A wrapper to interface with several different completion engines. + - {:Concealer:}[`core.concealer`] - Enhances the basic Neorg experience by using icons instead of text. + - {:Dirman:}[`core.dirman`] - This module is be responsible for managing directories full of .norg files. + - {:Exporting-Files:}[`core.export`] - Exports Neorg documents into any other supported filetype. + - {:Markdown-Export:}[`core.export.markdown`] - Interface for `core.export` to allow exporting to markdown. + - {:Core-Latex-Renderer:}[`core.latex.renderer`] - An experimental module for rendering latex images inline. + - {:Core-Presenter:}[`core.presenter`] - Neorg module to create gorgeous presentation slides. + - {:Summary:}[`core.summary`] - Creates links to all files in any workspace. + - {:Norg-Text-Objects:}[`core.text-objects`] - A Neorg module for moving and selecting elements of the document. + +* Developer modules + + These are modules that are only meant for developers. They are generally required in other modules: + + - {:Autocommands:}[`core.autocommands`] - Handles the creation and management of Neovim’s autocommands. + - {:Clipboard:}[`core.clipboard`] - A module to manipulate and interact with the user’s clipboard. + - {:Defaults:}[`core.defaults`] - Metamodule for storing the most necessary modules. + - {:Dirman-Utils:}[`core.dirman.utils`] - A set of utilities for the `core.dirman` module. + - {:Filesystem:}[`core.fs`] - A cross-platform set of utilities to traverse filesystems. + - {:Core-Highlights:}[`core.highlights`] - Manages your highlight groups with this module. + - {https://github.com/nvim-neorg/neorg/wiki/Coq_nvim}[`core.integrations.coq_nvim`] - A module for integrating coq_nvim with Neorg. + - {:Nvim-Cmp:}[`core.integrations.nvim-cmp`] - A module for integrating nvim-cmp with Neorg. + - {:Nvim-Compe:}[`core.integrations.nvim-compe`] - A module for integrating nvim-compe with Neorg. + - {:Treesitter-Integration:}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + - {:Neorgcmd-Module:}[`core.neorgcmd`] - This module deals with handling everything related to the `:Neorg` command. + - {:Neorgcmd-return:}[`core.neorgcmd.commands.return`] - Return to last location before entering Neorg. + - {:Queries-Module:}[`core.queries.native`] - TS wrapper in order to fetch nodes using a custom table. + - {:Scanner-Module:}[`core.scanner`] - This module is an implementation of a scanner that can be used anywhere TS can’t be used. + - {:Storage:}[`core.storage`] - Deals with storing persistent data across Neorg sessions. + - {:Syntax:}[`core.syntax`] - Handles interaction for syntax files for code blocks. + - {:Tempus:}[`core.tempus`] - Parses and handles dates in Neorg. + - {:Core-UI:}[`core.ui`] - A set of public functions to help developers create and manage UI (selection popups, prompts…) in their modules. + diff --git a/doc/wiki/Indent.norg b/doc/wiki/Indent.norg new file mode 100644 index 000000000..aa0820023 --- /dev/null +++ b/doc/wiki/Indent.norg @@ -0,0 +1,210 @@ + +* `core.esupports.indent` + +*** Formatting on the Fly + +* Overview + + `core.esupports.indent` uses Norg’s format to unambiguously determine + the indentation level for the current line. + + The indent calculation is aided by {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[treesitter], which + means that the quality of indents is "limited" by the quality of the produced syntax tree, + which will get better and better with time. + + To reindent a file, you may use the inbuilt Neovim `=` operator. + Indent levels are also calculated as you type, but may not be entirely correct + due to incomplete syntax trees (if you find any such examples, then file an issue!). + +* Configuration + +** dedent_excess (boolean) + + When false will not dedent nodes, only indent them. This means that if a node + is indented too much to the right, it will not be touched. It will only be indented + if the node is to the left of the expected indentation level. + + Useful when writing documentation in the style of vimdoc, where content is indented + heavily to the right in comparison to the default Neorg style. + + default: `true` + +** format_on_enter (boolean) + + When true, will reformat the current line every time you press `` (Enter). + + default: `true` + +** format_on_escape (boolean) + + When true, will reformat the current line every time you press `` (i.e. every + time you leave insert mode). + + default: `true` + +** indents (table) + + The table of indentations. + + This table describes a set of node types and how they should be indented + when encountered in the syntax tree. + + It also allows for certain nodes to be given properties (modifiers), which + can additively stack indentation given more complex circumstances. + +*** _ (table) + + Default behaviour for every other node not explicitly defined. + +**** indent (number) + + default: `0` + +**** modifiers (list) + + - \(string) default: `"under-headings"` + +*** heading1 (table) + + Indent behaviour for headings. + + In "idiomatic norg", headings should not be indented. + +**** indent (number) + + default: `0` + +*** heading2 (table) + + Indent behaviour for headings. + + In "idiomatic norg", headings should not be indented. + +**** indent (number) + + default: `0` + +*** heading3 (table) + + Indent behaviour for headings. + + In "idiomatic norg", headings should not be indented. + +**** indent (number) + + default: `0` + +*** heading4 (table) + + Indent behaviour for headings. + + In "idiomatic norg", headings should not be indented. + +**** indent (number) + + default: `0` + +*** heading5 (table) + + Indent behaviour for headings. + + In "idiomatic norg", headings should not be indented. + +**** indent (number) + + default: `0` + +*** heading6 (table) + + Indent behaviour for headings. + + In "idiomatic norg", headings should not be indented. + +**** indent (number) + + default: `0` + +*** paragraph_segment (table) + + Indent behaviour for paragraph segments (lines of text). + +**** indent (number) + + default: `0` + +**** modifiers (list) + + - \(string) default: `"under-headings"` + - \(string) default: `"under-nestable-detached-modifiers"` + +*** ranged_tag (table) + +**** indent (number) + + default: `0` + +**** modifiers (list) + + - \(string) default: `"under-headings"` + +*** ranged_tag_content (table) + + Ranged tag contents’ indentation should be calculated by Neovim itself. + +**** indent (number) + + default: `-1` + +*** ranged_tag_end (table) + + `@end` tags should always be indented as far as the beginning `@` ranged verbatim tag. + +**** indent (function) + + default: `function(_, node)` + +*** strong_paragraph_delimiter (table) + + Indent behaviour for strong paragraph delimiters. + + The indentation of these should be determined based on the heading level + that it is a part of. Since the `strong_paragraph_delimiter` node isn’t actually + a child of the previous heading in the syntax tree some extra work is required to + make it indent as expected. + +**** indent (function) + + default: `function(buf, _, line)` + +** modifiers (table) + + Apart from indents, modifiers may also be defined. + + These are repeatable instructions for nodes that share common traits. + +*** under-headings (function) + + For any object that can exist under headings + + default: `function(_, node)` + +*** under-nestable-detached-modifiers (function) + + For any object that should be indented under a list + + default: `function(_, node)` + +** tweaks (empty list) + + Tweaks are user defined `node_name` => `indent_level` mappings, + allowing the user to overwrite the indentation level for certain nodes. + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Autocommands}[`core.autocommands`] - Handles the creation and management of Neovim’s autocommands. + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + +* Required By + + - {https://github.com/nvim-neorg/neorg/wiki/Promo}[`core.promo`] - Promotes or demotes nestable items within Neorg files. + diff --git a/doc/wiki/Itero.norg b/doc/wiki/Itero.norg new file mode 100644 index 000000000..d989b0a44 --- /dev/null +++ b/doc/wiki/Itero.norg @@ -0,0 +1,70 @@ + +* `core.itero` + +*** Fast List/Heading Continuation + + Fluidness is key, after all. + +* Overview + + `core.itero` is a rather small and simple module designed to assist in the creation of many lists, + headings and other repeatable (iterable) items. + + By default, the key that is used to iterate on an item is `` (Alt + Enter). If you want to + change the bind, remap the `core.itero.next-iteration` event. + + Begin by writing an initial item you’d like to iterate (in this instance, and unordered list item): + + default: `- Hello World!` + + With your cursor in insert mode at the end of the line, pressing the keybind will continue the item at whatever + nesting level it is currently at (where `|||` is the new cursor position): + + @code md + - Hello World! + - | + @end + + The same can also be done for headings: + + @code md + * Heading 1 + * | + @end + + This functionality is commonly paired with the {https://github.com/nvim-neorg/neorg/wiki/Promo}[`core.promo`] module to then indent/dedent + the item under the cursor with the `` and `` bindings. + +* Configuration + +** iterables (list) + + A list of lua patterns detailing what treesitter nodes can be "iterated". + Usually doesn’t need to be changed, unless you want to disable some + items from being iterable. + + - \(string) default: `"unordered_list%d"` + - \(string) default: `"ordered_list%d"` + - \(string) default: `"heading%d"` + - \(string) default: `"quote%d"` + +** retain_extensions (table) + + Which item types to retain extensions for. + + If the item you are currently iterating has an extension (e.g. `( )`, `(x)` etc.), + then the following items will also have an extension (by default `( )`) attached + to them automatically. + +*** ordered_list%d (boolean) + + default: `true` + +*** unordered_list%d (boolean) + + default: `true` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Journal.norg b/doc/wiki/Journal.norg new file mode 100644 index 000000000..598b9deb5 --- /dev/null +++ b/doc/wiki/Journal.norg @@ -0,0 +1,76 @@ + +* `core.journal` + +*** Dear diary… + + The journal module allows you to take personal notes with zero friction. + +* Overview + + The journal module exposes a total of six commands. + The first three, `:Neorg journal today|yesterday|tomorrow`, allow you to access entries + for a given time relative to today. A file will be opened with the respective date as a `.norg` file. + + The fourth command, `:Neorg journal custom`, allows you to specify a custom date as an argument. + The date must be formatted according to the `YYYY-mm-dd` format, e.g. `2023-01-01`. + + The `:Neorg journal template` command creates a template file which will be used as the base whenever + a new journal entry is created. + + Last but not least, the `:Neorg journal toc open|update` commands open or create/update a Table of Contents + file found in the root of the journal. This file contains links to all other journal entries, alongside + their titles. + +* Configuration + +** journal_folder (string) + + The name for the folder in which the journal files are put. + + default: `"journal"` + +** strategy (string) + + The strategy to use to create directories. + May be "flat" (`2022-03-02.norg`), "nested" (`2022/03/02.norg`), + a lua string with the format given to `os.date()` or a lua function + that returns a lua string with the same format. + + default: `"nested"` + +** template_name (string) + + The name of the template file to use when running `:Neorg journal template`. + + default: `"template.norg"` + +** toc_format (nil) + + Formatter function used to generate the toc file. + Receives a table that contains tables like { yy, mm, dd, link, title }. + + The function must return a table of strings. + + default: `nil` + +** use_template (boolean) + + Whether to apply the template file to new journal entries. + + default: `true` + +** workspace (nil) + + Which workspace to use for the journal files, the default behaviour + is to use the current workspace. + + It is recommended to set this to a static workspace, but the most optimal + behaviour may vary from workflow to workflow. + + default: `nil` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Dirman}[`core.dirman`] - This module is be responsible for managing directories full of .norg files. + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Kickstart.norg b/doc/wiki/Kickstart.norg new file mode 100644 index 000000000..752d0b44e --- /dev/null +++ b/doc/wiki/Kickstart.norg @@ -0,0 +1,108 @@ + +* Instantaneous Neorg Setup + + Get up and running with Neorg even with zero Neovim knowledge. + +** Prerequisites + + To use this configuration, a set of prerequisites must be fulfilled beforehand. + + ~ Install one of the Nerd fonts, for example the Meslo Nerd Font from {https://www.nerdfonts.com/font-downloads}[Nerd Fonts]. + ~ Set your terminal font to the installed Nerd Font. + ~ Make sure you have git by running `git --version`. + ~ Ensure you have Luarocks installed on your system: + -- *Windows*: install {https://github.com/rjpcomputing/luaforwindows/releases/tag/v5.1.5-52}[lua for windows]. + -- *MacOS*: install via `brew install luarocks`. + -- *`apk`*: `sudo apk add luarocks wget` + -- *`apt`*: `sudo apt install luarocks` + -- *`dnf`*: `sudo dnf install luarocks` + -- *`pacman`*: `sudo pacman -Syu luarocks` + +** Troubleshooting + + If you have any issues like bold/italic not rendering or highlights being improperly applied + I encourage you to check out the {https://github.com/nvim-neorg/neorg/wiki/Dependencies}[dependencies document] which explains troubleshooting steps + for different kinds of terminals. + + With that, let’s begin! + +** Creating our Init File + + - Open up a Neovim instance and run the following command: `:echo stdpath("config")`. + This will return the path where Neovim expects your `init.lua` to exist. + - Navigate to that directory (create it if it doesn’t exist) and create a file + called `init.lua` there. On Linux this will likely be `~/.config/nvim/init.lua`. Put the following into the `init.lua` file: + @code lua + -- Bootstrap lazy.nvim + local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim" + if not (vim.uv or vim.loop).fs_stat(lazypath) then + local lazyrepo = "https://github.com/folke/lazy.nvim.git" + local out = vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath }) + if vim.v.shell_error ~= 0 then + vim.api.nvim_echo({ + { "Failed to clone lazy.nvim:\n", "ErrorMsg" }, + { out, "WarningMsg" }, + { "\nPress any key to exit..." }, + }, true, {}) + vim.fn.getchar() + os.exit(1) + end + end + vim.opt.rtp:prepend(lazypath) + + -- Set up both the traditional leader (for keymaps) as well as the local leader (for norg files) + vim.g.mapleader = " " + vim.g.maplocalleader = "," + + -- Setup lazy.nvim + require("lazy").setup({ + spec = { + { + "rebelot/kanagawa.nvim", -- neorg needs a colorscheme with treesitter support + config = function() + vim.cmd.colorscheme("kanagawa") + end, + }, + { + "nvim-treesitter/nvim-treesitter", + build = ":TSUpdate", + opts = { + ensure_installed = { "c", "lua", "vim", "vimdoc", "query" }, + highlight = { enable = true }, + }, + config = function(_, opts) + require("nvim-treesitter.configs").setup(opts) + end, + }, + { + "nvim-neorg/neorg", + lazy = false, + version = "*", + config = function() + require("neorg").setup { + load = { + ["core.defaults"] = {}, + ["core.concealer"] = {}, + ["core.dirman"] = { + config = { + workspaces = { + notes = "~/notes", + }, + default_workspace = "notes", + }, + }, + }, + } + + vim.wo.foldlevel = 99 + vim.wo.conceallevel = 2 + end, + }, + }, + }) + @end + + - Close and reopen Neovim. Everything should just work! + - Open up any `.norg` file and start typing! You may see an initial error, just hit enter a few times, after + which Neorg should immediately fix itself. + diff --git a/doc/wiki/Looking-Glass.norg b/doc/wiki/Looking-Glass.norg new file mode 100644 index 000000000..d5314647b --- /dev/null +++ b/doc/wiki/Looking-Glass.norg @@ -0,0 +1,25 @@ + +* `core.looking-glass` + +*** Code Blocks + Superpowers + + The `core.looking-glass` module magnifies code blocks and allows you to edit them in a separate buffer. + +* Overview + + The looking glass module provides a simple way to edit code blocks in an external buffer, + which allows LSPs and other language-specific tools to kick in. + + The magnify command can be accessed by running `:Neorg keybind all core.looking-glass.magnify-code-block` with your cursor underneath the code + block you would like to magnify - it is not bound to any key as of currently, + but you may map it yourself via the {https://github.com/nvim-neorg/neorg/wiki/User-Keybinds}[`core.keybinds`] module. + +* Configuration + + This module provides no configuration options! + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + - {https://github.com/nvim-neorg/neorg/wiki/Core-UI}[`core.ui`] - A set of public functions to help developers create and manage UI (selection popups, prompts…) in their modules. + diff --git a/doc/wiki/Markdown-Export.norg b/doc/wiki/Markdown-Export.norg new file mode 100644 index 000000000..50053d522 --- /dev/null +++ b/doc/wiki/Markdown-Export.norg @@ -0,0 +1,84 @@ + +* `core.export.markdown` + +*** Neorg’s Markdown Exporter + +* Overview + + This module exists as an interface for `core.export` to export `.norg` files to Markdown. + As a user the only reason you would ever have to touch this module is to configure /how/ you’d + like your markdown to be exported (i.e. do you want to support certain extensions during the export). + To learn more about configuration, consult the {#configuration}[relevant section]. + +* Configuration + +** extension (string) + + Used by the exporter to know what extension to use + when creating markdown files. + The default is recommended, although you can change it. + + default: `"md"` + +** extensions (empty list) + + Any extensions you may want to use when exporting to markdown. By + default no extensions are loaded (the exporter is commonmark compliant). + You can also set this value to `"all"` to enable all extensions. + The full extension list is: `todo-items-basic`, `todo-items-pending`, `todo-items-extended`, + `definition-lists`, `mathematics`, `metadata` and `latex`. + +** mathematics (table) + + Data about how to render mathematics. + The default is recommended as it is the most common, although certain flavours + of markdown use different syntax. + +*** block (table) + + Block-level mathematics are represented as such: + + @code md + $$ + \frac{3, 2} + $$ + @end + +**** end (string) + + default: `"$$"` + +**** start (string) + + default: `"$$"` + +*** inline (table) + + Inline mathematics are represented `$like this$`. + +**** end (string) + + default: `"$"` + +**** start (string) + + default: `"$"` + +** metadata (table) + + Data about how to render metadata + There are a few ways to render metadata blocks, but this is the most + common. + +*** end (string) + + default: `"---"` + +*** start (string) + + default: `"---"` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Metagen.norg b/doc/wiki/Metagen.norg new file mode 100644 index 000000000..dbee03a44 --- /dev/null +++ b/doc/wiki/Metagen.norg @@ -0,0 +1,94 @@ + +* `core.esupports.metagen` + +*** Manually Writing Metadata? No Thanks + + The metagen module automatically places relevant metadata at the top of your `.norg` files. + +* Overview + + The metagen module exposes two commands - `:Neorg inject-metadata` and `:Neorg update-metadata`. + + - The `inject-metadata` command will remove any existing metadata and overwrite it with fresh information. + - The `update-metadata` preserves existing info, updating things like the `updated` fields (when the file + was last edited) as well as a few other non-destructive fields. + +* Configuration + +** author (string) + + Custom author name that overrides default value if not nil or empty + Default value is autopopulated by querying the current user’s system username. + + default: `""` + +** delimiter (string) + + Custom delimiter between tag and value + + default: `": "` + +** tab (string) + + How to generate a tabulation inside the `@document.meta` tag + + default: `""` + +** template (nil) + + Custom template to use for generating content inside `@document.meta` tag + + default: `default_template` + +** timezone (string) + Timezone information in the timestamps + + - "utc" the timestamp is in UTC+0 + - "local" the timestamp is in the local timezone + - "implicit-local" like "local", but the timezone information is omitted from the timestamp + + default: `"local"` + +** type (string) + One of "none", "auto" or "empty" + + - "none" generates no metadata + - "auto" generates metadata if it is not present + - "empty" generates metadata only for new files/buffers. + + default: `"none"` + +** undojoin_updates (boolean) + + Whether or not to call `:h :undojoin` just before changing the timestamp in + `update_metadata`. This will make your undo key undo the last change before writing the file + in addition to the timestamp change. This will move your cursor to the top of the file. For + users with an autosave plugin, this option must be paired with keybinds for undo/redo to + avoid problems with undo tree branching: + + @code lua + vim.keymap.set("n", "u", function() + require("neorg.modules").get_module("core.esupports.metagen").skip_next_update() + local k = vim.api.nvim_replace_termcodes("u", true, false, true) + vim.api.nvim_feedkeys(k, 'n', false) + end) + vim.keymap.set("n", "", function() + require("neorg.modules").get_module("core.esupports.metagen").skip_next_update() + local k = vim.api.nvim_replace_termcodes("", true, false, true) + vim.api.nvim_feedkeys(k, 'n', false) + end) + @end + + default: `false` + +** update_date (boolean) + + Whether updated date field should be automatically updated on save if required + + default: `true` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Autocommands}[`core.autocommands`] - Handles the creation and management of Neovim’s autocommands. + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Neorgcmd-Module.norg b/doc/wiki/Neorgcmd-Module.norg new file mode 100644 index 000000000..bdbb43bd4 --- /dev/null +++ b/doc/wiki/Neorgcmd-Module.norg @@ -0,0 +1,39 @@ + +* `core.neorgcmd` + +*** Does the Heavy Lifting for the `:Neorg` Command + +* Overview + + This internal module handles everything there is for the `:Neorg` command to function. + + Different modules can define their own commands, completions and conditions on when they’d + like these commands to be avaiable. + + For a full example on how to create your own command, it is recommended to read the + `core.neorgcmd`’s `module.lua` file. At the beginning of the file is an examples table + which walks you through the necessary steps. + +* Configuration + +** default (list) + + A list of default commands to load. + + This feature will soon be deprecated, so it is not recommended to touch it. + + - \(string) default: `"return"` + +** load (list) + + A list of neorgcmd modules to load automatically. + This feature will soon be deprecated, so it is not recommended to touch it. + + - \(string) default: `"default"` + +* Required By + + - {https://github.com/nvim-neorg/neorg/wiki/Core-Latex-Renderer}[`core.latex.renderer`] - An experimental module for rendering latex images inline. + - {https://github.com/nvim-neorg/neorg/wiki/Neorgcmd-return}[`core.neorgcmd.commands.return`] - Return to last location before entering Neorg. + - {https://github.com/nvim-neorg/neorg/wiki/Tangling}[`core.tangle`] - An Advanced Code Block Exporter. + diff --git a/doc/wiki/Neorgcmd-return.norg b/doc/wiki/Neorgcmd-return.norg new file mode 100644 index 000000000..1ca3f1ae3 --- /dev/null +++ b/doc/wiki/Neorgcmd-return.norg @@ -0,0 +1,18 @@ + +* `core.neorgcmd.commands.return` + +*** Provides the `:Neorg return` Command + +* Overview + + When executed (`:Neorg return`), all currently open `.norg` files are deleted from + the buffer list, and the current workspace is set to "default". + +* Configuration + + This module provides no configuration options! + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Neorgcmd-Module}[`core.neorgcmd`] - This module deals with handling everything related to the `:Neorg` command. + diff --git a/doc/wiki/Norg-Text-Objects.norg b/doc/wiki/Norg-Text-Objects.norg new file mode 100644 index 000000000..976c95a40 --- /dev/null +++ b/doc/wiki/Norg-Text-Objects.norg @@ -0,0 +1,62 @@ + +* `core.text-objects` + +*** Navigation, Selection, and Swapping + +* Overview + + - Easily move items up and down in the document + - Provides text objects for headings, tags, and lists + +** Usage + + Users can create keybinds for some or all of the different events this module exposes. Those are: + + - `core.text-objects.item_up` - Moves the current "item" up + - `core.text-objects.item_down` - same but down + - `core.text-objects.textobject.heading.outer` + - `core.text-objects.textobject.heading.inner` + - `core.text-objects.textobject.tag.inner` + - `core.text-objects.textobject.tag.outer` + - `core.text-objects.textobject.list.outer` - around the entire list + + /Movable "items" include headings, and list items (ordered/unordered/todo)/ + +*** Example + + Example keybinds that would go in your Neorg configuration: + + @code lua + vim.keymap.set("n", "", "(neorg.text-objects.item-up)", {}) + vim.keymap.set("n", "", "(neorg.text-objects.item-down)", {}) + vim.keymap.set({ "o", "x" }, "iH", "(neorg.text-objects.textobject.heading.inner)", {}) + vim.keymap.set({ "o", "x" }, "aH", "(neorg.text-objects.textobject.heading.outer)", {}) + @end + +* Configuration + +** moveables (table) + +*** headings (list) + + - \(string) default: `"heading%d"` + - \(string) default: `"heading%d"` + +*** todo_items (list) + + - \(string) default: `"todo_item%d"` + - \(list) + -- \(string) default: `"todo_item%d"` + -- \(string) default: `"unordered_list%d"` + +*** unordered_list_elements (list) + + - \(string) default: `"unordered_list%d"` + - \(list) + -- \(string) default: `"todo_item%d"` + -- \(string) default: `"unordered_list%d"` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Nvim-Cmp.norg b/doc/wiki/Nvim-Cmp.norg new file mode 100644 index 000000000..9e147eb76 --- /dev/null +++ b/doc/wiki/Nvim-Cmp.norg @@ -0,0 +1,24 @@ + +* `core.integrations.nvim-cmp` + +*** Integrating Neorg with `nvim-cmp` + +* Overview + + This module works with the {https://github.com/nvim-neorg/neorg/wiki/Completion}[`core.completion`] module to attempt to provide + intelligent completions. Note that integrations like this are second-class citizens and may not work in 100% + of scenarios. If they don’t then please file a bug report! + + After setting up `core.completion` with the `engine` set to `nvim-cmp`, make sure to also set up "neorg" + as a source in `nvim-cmp`: + + @code lua + sources = { + { name = "neorg" }, + }, + @end + +* Configuration + + This module provides no configuration options! + diff --git a/doc/wiki/Nvim-Compe.norg b/doc/wiki/Nvim-Compe.norg new file mode 100644 index 000000000..b9360bd08 --- /dev/null +++ b/doc/wiki/Nvim-Compe.norg @@ -0,0 +1,17 @@ + +* `core.integrations.nvim-compe` + +*** Integrating Neorg with `nvim-compe` + +* Overview + + WARNING: This module is *deprecated*, and no further support for the module will be provided. + That does not mean it will not work, however any bugs will not be dealt with by the main Neorg team. + + A module for integrating nvim-compe with Neorg. + Works with {https://github.com/nvim-neorg/neorg/wiki/Completion}[`core.completion`] to provide intelligent completions. + +* Configuration + + This module provides no configuration options! + diff --git a/doc/wiki/Philosophy.norg b/doc/wiki/Philosophy.norg new file mode 100644 index 000000000..4fdd75d0b --- /dev/null +++ b/doc/wiki/Philosophy.norg @@ -0,0 +1,15 @@ + +* :rocket: Project Philosophy + + Neorg is a project that stands on the shoulders of giants, namely `org-mode`, `markdown` and + partially `asciidoc`. + + If Neorg is a different approach to a similar problem that all other three systems have solved, + why create yet another file format? Why go through all of the troubles? + +** Design Decisions + + > [!NOTE] + This page is a work-in-progress. + There is a design decisions document present in the norg file format {https://github.com/nvim-neorg/norg-specs/blob/main/design-decisions.norg}[here] in the meantime. + diff --git a/doc/wiki/Pivot.norg b/doc/wiki/Pivot.norg new file mode 100644 index 000000000..b1a5610f3 --- /dev/null +++ b/doc/wiki/Pivot.norg @@ -0,0 +1,29 @@ + +* `core.pivot` + +*** Ordered or Unordered? + + That -is- was the question. Now you no longer have to ask! + +* Overview + + `core.pivot` allows you to switch (or pivot) between the two list types in Norg with the press of a button. + +*** Keybinds + + This module exposes two keybinds: + - `core.pivot.toggle-list-type` (default binding: `lt` ["list toggle"]) - takes a + list and, based on the opposite type of the first list item, inverts all the other items in that list. + Does not respect mixed lists, all items in the list will be converted to the same type. + - `core.pivot.invert-list-type` (default binding: `li` ["list invert"]) - same behaviour as + the previous keybind, however respects mixed lists - unordered items will become ordered, whereas ordered + items will become unordered. + +* Configuration + + This module provides no configuration options! + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Promo.norg b/doc/wiki/Promo.norg new file mode 100644 index 000000000..405295732 --- /dev/null +++ b/doc/wiki/Promo.norg @@ -0,0 +1,36 @@ + +* `core.promo` + +*** You have Received a Promotion! + + The `promo` module increases or decreases the nesting level of nestable items by repeating their characters. + +* Overview + + When dealing with Norg, it may sometimes be tedious to continually repeat a single character to increase + your nesting level. For example, for a level 6 nested unordered list, you need to repeat the `-` character + six times: + + default: `------ This is my item!` + + The `core.promo` module allows you to indent these object by utilizing the inbuilt Neovim keybinds: + - `>>` - increase the indentation level for the current object (also dedents children) + - `<<` - decrease the indentation level for the current object recursively (also dedents children) + - `>.` - increase the indentation level for the current object (non-recursively) + - `<,` - decrease the indentation level for the current object (non-recursively) + + In insert mode, you are also provided with two keybinds, also being Neovim defaults: + - `` increase the indentation level for the current object + - `` decrease the indentation level for the current object + + This module is commonly used with the {https://github.com/nvim-neorg/neorg/wiki/Itero}[`core.itero`] module for an effective workflow. + +* Configuration + + This module provides no configuration options! + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Indent}[`core.esupports.indent`] - A set of instructions for Neovim to indent Neorg documents. + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Queries-Module.norg b/doc/wiki/Queries-Module.norg new file mode 100644 index 000000000..a0f950f05 --- /dev/null +++ b/doc/wiki/Queries-Module.norg @@ -0,0 +1,22 @@ + +* `core.queries.native` + +*** Queries Made Easy + +* Overview + + The `core.queries.native` module provides useful Treesitter wrappers + to query information from Norg documents. + +* Configuration + + This module provides no configuration options! + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + +* Required By + + - {https://github.com/nvim-neorg/neorg/wiki/Core-Presenter}[`core.presenter`] - Neorg module to create gorgeous presentation slides. + diff --git a/doc/wiki/Scanner-Module.norg b/doc/wiki/Scanner-Module.norg new file mode 100644 index 000000000..23de2c090 --- /dev/null +++ b/doc/wiki/Scanner-Module.norg @@ -0,0 +1,14 @@ + +* `core.scanner` + +*** Scanner module for Neorg + +* Overview + + This module is an implementation of a scanner that can be used anywhere TS can’t be used. + It is not currently used anywhere, and is small enough to be self-documenting. + +* Configuration + + This module provides no configuration options! + diff --git a/doc/wiki/Setup-Guide.norg b/doc/wiki/Setup-Guide.norg new file mode 100644 index 000000000..cfaf394b7 --- /dev/null +++ b/doc/wiki/Setup-Guide.norg @@ -0,0 +1,131 @@ + +* Setting up Neorg + + A guide on configuring Neorg. + + > [!NOTE] + If you’re just getting started and have no idea why and where to use Neorg, + feel free to check out the {https://github.com/nvim-neorg/neorg/wiki/Tutorial}[tutorial]. + +** Where do I begin? + + Neorg, being a large organizational tool for many different types of people, needs to be + extensible and highly configurable. It’s for this reason that setting it up takes slightly + longer than your average Neovim plugin. + + Because of this, learning to navigate the Neorg wiki as well as learning the basics of how the system + works will get you a very long way in making Neorg your own. + + This guide assumes that you’ve completed the initial {https://github.com/nvim-neorg/neorg?tab=readme-ov-file#-installation}[setup process] successfully and without errors. + +** Default Setup + + The default configuration looks like follows: + + default: `require("neorg").setup()` + + This code initializes Neorg with the /default options/. In practice it’s equivalent to the following: + + @code lua + require("neorg").setup({ + load = { + ["core.defaults"] = {}, + } + }) + @end + + This immediately introduces you to an important concept: *modules*. + + The entire core of Neorg is modular, that is, all functionality is isolated into bits + of code. Every module has its own configuration options, its own behaviours, + its own keymaps, etc. + + `core.defaults` is a special type of module called a metamodule - it acts as a quick way to load a bunch of other modules + at once. If you’d like to see what sort of modules `core.defaults` loads, check out {https://github.com/nvim-neorg/neorg/wiki#default-modules}[this wiki entry]. + +** Configuring Parts of Neorg + + By default, Neorg comes with the bare experience. It loads modules that are critical for Neorg to function + properly. This workflow is mainly tailored for people who use Neorg to write documentation in the Norg file format, but nothing more than that. + + If you’re using Neorg to write notes or to perform time-tracking tasks you may want to load /extra modules/ + that provide more functionality than the default. + + These extra modules are listed {https://github.com/nvim-neorg/neorg/wiki#other-modules}[in a separate heading in the wiki]. Feel free to check some of them out! + They all have documentation and their behaviours are explained. + +** Loading New Modules + + The most common module people set up is the concealer module - it converts our + notes from regular plaintext to beautified plaintext thanks to its use of + icons. If you click on the module name in the wiki, it’ll take you to {https://github.com/nvim-neorg/neorg/wiki/Concealer}[this + page]. + + To load the module, we use the full path of the module (in this case `core.concealer`). + Let’s adapt our configuration: + + @code lua + require("neorg").setup({ + load = { + ["core.defaults"] = {}, + ["core.concealer"] = {}, -- We added this line! + } + }) + @end + + If you restart Neovim and enter a `test.norg` file with the following content: + + default: `* Hello from Neorg!` + + You should see that the heading has a nice icon! + + A decent chunk of modules require no configuration and work out of the box. Feel free to try as + many as you like! + +*** Dependence on Neovim Options + + If you carefully read the {https://github.com/nvim-neorg/neorg/wiki/Concealer#overview}[overview page for the concealer], + you’ll notice that the concealer respects the Neovim `conceallevel` and `concealcursor` options. + + If possible, Neorg will not mess with your Neovim options. Check out the help pages for both options + and tweak them as you see fit. For example, `vim.opt.conceallevel = 3` will cause many elements of the document + like the asterisks around `*bold*` words to disappear! + +** Configuring Individual Modules + + If you had read onwards in the concealer’s page you may have noticed a {https://github.com/nvim-neorg/neorg/wiki/Concealer#configuration}[configuration section]. + This section details all of the possible configuration options as well as their descriptions. Click around and see what you can find! + + Continuing with our concealer example, let’s say we wanted to change the `icon_preset` setting. + The documentation tells us this option is a string, and that its default value is `"basic"`. + + To configure the module, let’s extend our configuration code: + + @code lua + require("neorg").setup({ + load = { + ["core.defaults"] = {}, + ["core.concealer"] = { + config = { -- We added a `config` table! + icon_preset = "varied", -- And we set our option here. + }, + }, + } + }) + @end + + Notice that, to configure a module, we first provide a `config` table, and then all of our configuration inside! + + If you save, quit and re-enter Neovim, the concealer should now use a completely different set of icons than it did before! + +** Running `:checkhealth` to Find Mistakes + + If you find something that isn’t behaving as intended feel free to run `:checkhealth neorg` - this will open up a window with a set of checkboxes (or crosses if there were errors). + + The builtin checkhealth ensures that your configuration is "clean" - that means that there are no errors or mistakes on your end. If something is wrong (e.g. you forgot to wrap your + module configuration in a `config = {}` block) then the health check will issue a warning or error with detailed instructions on how to fix the issue :) + +** That’s it! + + These are the most critical things that you need to know to get started with configuring Neorg. If you would like to understand /how/ to start using Neorg, check out the {https://github.com/nvim-neorg/neorg/wiki/Tutorial}[tutorial]! + diff --git a/doc/wiki/Storage.norg b/doc/wiki/Storage.norg new file mode 100644 index 000000000..b2fa20b1f --- /dev/null +++ b/doc/wiki/Storage.norg @@ -0,0 +1,21 @@ + +* `core.storage` + +*** Store persistent data and query it easily with `core.storage` + +* Configuration + +** path (string) + + Full path to store data (saved in mpack data format) + + default: `vim.fn.stdpath("data") .. "/neorg.mpack"` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Autocommands}[`core.autocommands`] - Handles the creation and management of Neovim’s autocommands. + +* Required By + + - {https://github.com/nvim-neorg/neorg/wiki/Dirman}[`core.dirman`] - This module is be responsible for managing directories full of .norg files. + diff --git a/doc/wiki/Summary.norg b/doc/wiki/Summary.norg new file mode 100644 index 000000000..ffff0aaad --- /dev/null +++ b/doc/wiki/Summary.norg @@ -0,0 +1,43 @@ + +* `core.summary` + +*** Write notes, not boilerplate. + + The summary module creates links and annotations to all files in a given workspace. + +* Overview + + The `core.summary` module exposes a single command - `:Neorg generate-workspace-summary`. + + When executed with the cursor hovering over a heading, `core.summary` will generate, you guessed it, + a summary of the entire workspace, with links to each respective entry in that workspace. + + If arguments are provided then a partial summary is generated containing only categories that + you have provided. + E.g. `:Neorg generate-workspace-summary work todos` would only generate a + summary of the categories `work` and `todos`. + + The way the summary is generated relies on the `strategy` configuration option, + which by default consults the document metadata (see also + {https://github.com/nvim-neorg/neorg/wiki/Metagen}[`core.esupports.metagen`]) or the first heading title + as a fallback to build up a tree of categories, titles and descriptions. + +* Configuration + +** strategy (string) + + The strategy to use to generate a summary. + + Possible options are: + + - "default" - read the metadata to categorize and annotate files. Files + without metadata will use the top level heading as the title. If no headings are present, the filename will be used. + - "by_path" - Similar to "default" but uses the capitalized name of the folder containing a *.norg file as category. + @type [type] string|fun(files: PathlibPath[], ws_root: PathlibPath, heading_level: number?, include_categories: string[]?): string[]? + + default: `"default"` + + * Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Syntax.norg b/doc/wiki/Syntax.norg new file mode 100644 index 000000000..fce7ed45c --- /dev/null +++ b/doc/wiki/Syntax.norg @@ -0,0 +1,68 @@ + +* `core.syntax` + +*** Where Treesitter can’t Reach + + When a language not supported by Treesitter is found a fallback is made to use vim regex highlighting. + +* Overview + + The `core.syntax` module highlights any `@code` region where there is no treesitter parser present + to highlight the region. + + This module very closely resembles the {https://github.com/nvim-neorg/neorg/wiki/Concealer}[`concealer`], but some parts have been + adapted to fit the correct use case. + +***** Author’s note: + + This module will appear as spaghetti code at first glance. This is intentional. + If one needs to edit this module, it is best to talk to me at `katawful` on GitHub. + Any edit is assumed to break this module. + +* Configuration + +** performance (table) + + Performance options for highlighting. + + These options exhibit the same behaviour as the {https://github.com/nvim-neorg/neorg/wiki/Concealer}[`concealer`]’s. + +*** increment (number) + + How many lines each "chunk" of a file should take up. + + When the size of the buffer is greater than this value, + the buffer is then broken up into equal chunks and operations + are done individually on those chunks. + + default: `1250` + +*** interval (number) + + How long the syntax module should wait before starting to conceal + a new chunk. + + default: `500` + +*** max_debounce (number) + + The maximum amount of recalculations that take place at a single time. + More operations than this count will be dropped. + + Especially useful when e.g. holding down `x` in a buffer, forcing + hundreds of recalculations at a time. + + default: `5` + +*** timeout (number) + + How long the syntax module should wait before starting to conceal + the buffer. + + default: `0` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Autocommands}[`core.autocommands`] - Handles the creation and management of Neovim’s autocommands. + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/TOC.norg b/doc/wiki/TOC.norg new file mode 100644 index 000000000..db7dc98a9 --- /dev/null +++ b/doc/wiki/TOC.norg @@ -0,0 +1,32 @@ + +* `core.qol.toc` + +*** A Bird’s Eye View of Norg Documents + + The TOC module generates a table of contents for a given Norg buffer. + +* Overview + + The TOC module exposes a single command - `:Neorg toc`. This command can be executed with one of three + optional arguments: `left`, `right` and `qflist`. + + When `left` or `right` is supplied, the Table of Contents split is placed on that side of the screen. + When the `qflist` argument is provided, the whole table of contents is sent to the Neovim quickfix list, + should that be more convenient for you. + + When in the TOC view, `` can be pressed on any of the entries to move to that location in the respective + Norg document. The TOC view updates automatically when switching buffers. + +* Configuration + +** enter (boolean) + + Enter a ToC window opened manually (any ToC window not opened by auto_toc) + + default: `true` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + - {https://github.com/nvim-neorg/neorg/wiki/Core-UI}[`core.ui`] - A set of public functions to help developers create and manage UI (selection popups, prompts…) in their modules. + diff --git a/doc/wiki/Tangling.norg b/doc/wiki/Tangling.norg new file mode 100644 index 000000000..292ee6e44 --- /dev/null +++ b/doc/wiki/Tangling.norg @@ -0,0 +1,212 @@ + +* `core.tangle` + +*** From Code Blocks to Files + + The `core.tangle` module exports code blocks within a `.norg` file straight to a file of your choice. + +* Overview + + The goal of this module is to allow users to spit out the contents of code blocks into + many different files. This is the primary component required for a literate configuration in Neorg, + where the configuration is annotated and described in a `.norg` document, and the actual code itself + is thrown out into a file that can then be normally consumed by e.g. an application. + + The `tangle` module currently provides a single command: + - `:Neorg tangle current-file` - performs all possible tangling operations on the current file + +*** Usage Tutorial + + By default, /zero/ code blocks are tangled. You must provide where you’d like to tangle each code + block manually (global configuration will be discussed later). To do so, add a `#tangle ` tag above the code block you’d wish to export, where is relative to the + current file. For example: + + |example + #tangle init.lua + @code lua + print("Hello World!") + @end + |end + + The above snippet will /only/ tangle that single code block to the desired output file: `init.lua`. + +**** Global Tangling for Single Files + + Apart from tangling a single or a set of code blocks, you can declare a global output file in the document’s metadata: + + |example + @document.meta + tangle: ./init.lua + @end + |end + + This will tangle all `lua` code blocks to `init.lua`, /unless/ the code block has an explicit `#tangle` tag associated with it, in which case + the `#tangle` tag takes precedence. + +**** Global Tangling for Multiple Files + + Apart from a single filepath, you can provide many in an array: + + |example + @document.meta + tangle: [ + ./init.lua + ./output.hs + ] + @end + |end + + The above snippet tells the Neorg tangling engine to tangle all `lua` code blocks to `./init.lua` and all `haskell` code blocks to `./output.hs`. + As always if any of the code blocks have a `#tangle` tag then that takes precedence. + +**** Ignoring Code Blocks + + Sometimes when tangling you may want to omit some code blocks. For this you may use the `#tangle.none` tag: + + |example + #tangle.none + @code lua + print("I won't be tangled!") + @end + |end + +**** Global Tangling with Extra Options + + But wait, it doesn’t stop there! You can supply a string to `tangle`, an array to `tangle`, but also an object! + It looks like this: + + |example + @document.meta + tangle: { + languages: { + lua: ./output.lua + haskell: my-haskell-file + } + delimiter: heading + scope: all + } + @end + |end + + The `language` option determines which filetype should go into which file. + It’s a simple language-filepath mapping, but it’s especially useful when the output file’s language type cannot be inferred from the name or shebang. + It is also possible to use the name `_` as a catchall to direct output for all files not otherwise listed. + + The `delimiter` option determines how to delimit code blocks that export to the same file. + The following variations are allowed: + + - `heading` – Try to determine the filetype of the code block and insert any headings from the original document as a comment in the tangled output. + If filetype detection fails, `newline` will be used instead. + - `file-content` – Try to determine the filetype of the codeblock and insert the Neorg file content as a delimiter. + If filetype detection fails, `none` will be used instead. + - `newline` – Use an extra newline between tangled blocks. + - `none` – Do not add any delimiter. This implies that the code blocks are inserted into the tangle target as-is. + + The `scope` option is discussed below. + +**** Tangling Scopes + + What you’ve seen so far is the tangler operating in `all` mode. This means it captures all code blocks of a certain type unless that code block is tagged + with `#tangle.none`. There are two other types: `tagged` and `main`. + +***** The `tagged` Scope + + When in this mode, the tangler will only tangle code blocks that have been `tagged` with a `#tangle` tag. + Note that you don’t have to always provide a filetype, and that: + + |example + #tangle + @code lua + @end + |end + + Will use the global output file for that language as defined in the metadata. I.e., if I do: + + |example + @document.meta + tangle: { + languages: { + lua: ./output.lua + } + scope: tagged + } + @end + + @code lua + print("Hello") + @end + + #tangle + @code lua + print("Sup") + @end + + #tangle other-file.lua + @code lua + print("Ayo") + @end + |end + + The first code block will not be touched, the second code block will be tangled to `./output.lua` and the third code block will be tangled to `other-file.lua`. You + can probably see that this system can get expressive pretty quick. + +***** The `main` scope + + This mode is the opposite of the `tagged` one in that it will only tangle code blocks to files that are defined in the document metadata. I.e. in this case: + + |example + @document.meta + tangle: { + languages: { + lua: ./output.lua + } + scope: main + } + @end + + @code lua + print("Hello") + @end + + #tangle + @code lua + print("Sup") + @end + + #tangle other-file.lua + @code lua + print("Ayo") + @end + |end + + The first code block will be tangled to `./output.lua`, the second code block will also be tangled to `./output.lua` and the third code block will be ignored. + +* Configuration + +** indent_errors (string) + When text in a code block is less indented than the block itself, Neorg will not tangle that + block to a file. Instead it can either print or vim.notify error. By default, vim.notify is + loud and is more likely to create a press enter message. + + - "notify" - Throw a normal looking error + - "print" - print the error + + default: `"notify"` + +** report_on_empty (boolean) + + Notify when there is nothing to tangle (INFO) or when the content is empty (WARN). + + default: `true` + +** tangle_on_write (boolean) + + Tangle all code blocks in the current norg file on file write. + + default: `false` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + - {https://github.com/nvim-neorg/neorg/wiki/Neorgcmd-Module}[`core.neorgcmd`] - This module deals with handling everything related to the `:Neorg` command. + diff --git a/doc/wiki/Tempus.norg b/doc/wiki/Tempus.norg new file mode 100644 index 000000000..891b687ec --- /dev/null +++ b/doc/wiki/Tempus.norg @@ -0,0 +1,15 @@ + +* `core.tempus` + +*** Hassle-Free Dates + +* Overview + + `core.tempus` is an internal module specifically designed + to handle complex dates. It exposes two functions: `parse_date(string) -> date|string` + and `to_lua_date(date) -> osdate`. + +* Configuration + + This module provides no configuration options! + diff --git a/doc/wiki/Todo-Introspector.norg b/doc/wiki/Todo-Introspector.norg new file mode 100644 index 000000000..f1da00d63 --- /dev/null +++ b/doc/wiki/Todo-Introspector.norg @@ -0,0 +1,57 @@ + +* `core.todo-introspector` + +*** See Your Progress at a Glance + + The introspector module displays progress for nested tasks. + +* Overview + + When an item with a TODO status has children with their own TODOs this module enables virtual text in the top level item and displays the + progress of the subtasks. By default it displays in the format of `[completed/total] (progress%)`. + +* Configuration + +** completed_statuses (list) + + Which status should count towards the completed count (should be a subset of counted_statuses). + + Defaults to the following: `done`. + + - \(string) default: `"done"` + +** counted_statuses (list) + + Which status types to count towards the totol. + + Defaults to the following: `done`, `pending`, `undone`, `urgent`. + + - \(string) default: `"done"` + - \(string) default: `"pending"` + - \(string) default: `"undone"` + - \(string) default: `"urgent"` + +** format (function) + Callback to format introspector. Takes in two parameters: + + - `completed`: number of completed tasks + - `total`: number of total counted tasks + + Should return a string with the format you want to display the introspector in. + + Defaults to "[completed/total] (progress%)" + + default: `function(completed, total)` + +** highlight_group (string) + + Highlight group to display introspector in. + + Defaults to "Normal". + + default: `"Normal"` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Todo-Items.norg b/doc/wiki/Todo-Items.norg new file mode 100644 index 000000000..676764785 --- /dev/null +++ b/doc/wiki/Todo-Items.norg @@ -0,0 +1,103 @@ + +* `core.qol.todo_items` + +*** Todo Item Swiss Army Knife + +* Overview + + This module handles the whole concept of toggling TODO items, as well as updating + parent and/or children items alongside the current item. + + The following keybinds are exposed: + - `(neorg.qol.todo-items.todo.task-done)` (`td`) + - `(neorg.qol.todo-items.todo.task-undone)` (`tu`) + - `(neorg.qol.todo-items.todo.task-pending)` (`tp`) + - `(neorg.qol.todo-items.todo.task-on_hold)` (`th`) + - `(neorg.qol.todo-items.todo.task-cancelled)` (`tc`) + - `(neorg.qol.todo-items.todo.task-recurring)` (`tr`) + - `(neorg.qol.todo-items.todo.task-important)` (`ti`) + - `(neorg.qol.todo-items.todo.task-cycle)` (``) + - `(neorg.qol.todo-items.todo.task-cycle-reverse)` (no default keybind) + + With your cursor on a line that contains an item with a TODO attribute, press + any of the above keys to toggle the state of that particular item. + Parent items of the same type and children items of the same type are update accordingly. + +* Configuration + +** create_todo_items (boolean) + + When `true`, will automatically create a TODO extension for an item + if it does not exist and an operation is performed on that item. + + Given the following example: + + default: `- Test Item` + + With this option set to true, performing an operation (like pressing `` + or what have you) will convert the non-todo item into one: + + default: `- ( ) Test Item` + + default: `true` + +** create_todo_parents (boolean) + + When set to `true`, will automatically convert parent + items to TODOs whenever a child item’s TODO state is updated. + + For instance, given the following example: + + |example + - Text + -- \( ) Child text + |end + + When this option is `true` and the child’s state is updated to e.g. + `(x)` via the `td` keybind, the new output becomes: + + |example + - \(x) Text + -- \(x) Child text + |end + + default: `false` + +** order (list) + + The default order of TODO item cycling when cycling via + ``. + + Defaults to the following order: `undone`, `done`, `pending`. + + - \(list) + -- \(string) default: `"undone"` + -- \(string) default: `" "` + - \(list) + -- \(string) default: `"done"` + -- \(string) default: `"x"` + - \(list) + -- \(string) default: `"pending"` + -- \(string) default: `"-"` + +** order_with_children (list) + + The default order of TODO item cycling when the item + has nested children with TODO items. + + When cycling through TODO items with children it’s not + always sensible to follow the same schema as the `order` table. + + Defaults to the following order: `undone`, `done`. + + - \(list) + -- \(string) default: `"undone"` + -- \(string) default: `" "` + - \(list) + -- \(string) default: `"done"` + -- \(string) default: `"x"` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] - A module designed to integrate Treesitter into Neorg. + diff --git a/doc/wiki/Treesitter-Integration.norg b/doc/wiki/Treesitter-Integration.norg new file mode 100644 index 000000000..f6c478ed8 --- /dev/null +++ b/doc/wiki/Treesitter-Integration.norg @@ -0,0 +1,98 @@ + +* `core.integrations.treesitter` + +*** Snazzy Treesitter Integration + +* Configuration + +** configure_parsers (boolean) + + If true will auto-configure the parsers to use the recommended setup. + Set to false only if you know what you’re doing, or if the setting messes + with your personal configuration. + + default: `true` + +** install_parsers (boolean) + + If true will automatically install Norg parsers if they are not present. + + default: `true` + +** parser_configs (table) + + Configurations for each parser as required by `nvim-treesitter`. + If you would like to tweak your parser configs you may do so here. + +*** norg (table) + + Configuration for the mainline norg parser. + +**** branch (string) + + default: `"main"` + +**** files (list) + + - \(string) default: `"src/parser.c"` + - \(string) default: `"src/scanner.cc"` + +**** revision (string) + + default: `"6348056b999f06c2c7f43bb0a5aa7cfde5302712"` + +**** url (string) + + default: `"https://github.com/nvim-neorg/tree-sitter-norg"` + +*** norg_meta (table) + + Configuration for the metadata parser (used to parse the contents + of `@document.meta` blocks). + +**** branch (string) + + default: `"main"` + +**** files (list) + + - \(string) default: `"src/parser.c"` + +**** revision (string) + + default: `"a479d1ca05848d0b51dd25bc9f71a17e0108b240"` + +**** url (string) + + default: `"https://github.com/nvim-neorg/tree-sitter-norg-meta"` + +* Dependencies + + - {https://github.com/nvim-neorg/neorg/wiki/Core-Highlights}[`core.highlights`] - Manages your highlight groups with this module. + +* Required By + + - {https://github.com/nvim-neorg/neorg/wiki/Clipboard}[`core.clipboard`] - A module to manipulate and interact with the user’s clipboard. + - {https://github.com/nvim-neorg/neorg/wiki/Completion}[`core.completion`] - A wrapper to interface with several different completion engines. + - {https://github.com/nvim-neorg/neorg/wiki/Concealer}[`core.concealer`] - Enhances the basic Neorg experience by using icons instead of text. + - {https://github.com/nvim-neorg/neorg/wiki/Esupports-Hop}[`core.esupports.hop`] - "Hop" between Neorg links, following them with a single keypress. + - {https://github.com/nvim-neorg/neorg/wiki/Indent}[`core.esupports.indent`] - A set of instructions for Neovim to indent Neorg documents. + - {https://github.com/nvim-neorg/neorg/wiki/Metagen}[`core.esupports.metagen`] - A Neorg module for generating document metadata automatically. + - {https://github.com/nvim-neorg/neorg/wiki/Exporting-Files}[`core.export`] - Exports Neorg documents into any other supported filetype. + - {https://github.com/nvim-neorg/neorg/wiki/Markdown-Export}[`core.export.markdown`] - Interface for `core.export` to allow exporting to markdown. + - {https://github.com/nvim-neorg/neorg/wiki/Itero}[`core.itero`] - Module designed to continue lists, headings and other iterables. + - {https://github.com/nvim-neorg/neorg/wiki/Journal}[`core.journal`] - Easily track a journal within Neorg. + - {https://github.com/nvim-neorg/neorg/wiki/Core-Latex-Renderer}[`core.latex.renderer`] - An experimental module for rendering latex images inline. + - {https://github.com/nvim-neorg/neorg/wiki/Looking-Glass}[`core.looking-glass`] - Allows for editing of code blocks within a separate buffer. + - {https://github.com/nvim-neorg/neorg/wiki/Pivot}[`core.pivot`] - Toggles the type of list currently under the cursor. + - {https://github.com/nvim-neorg/neorg/wiki/Core-Presenter}[`core.presenter`] - Neorg module to create gorgeous presentation slides. + - {https://github.com/nvim-neorg/neorg/wiki/Promo}[`core.promo`] - Promotes or demotes nestable items within Neorg files. + - {https://github.com/nvim-neorg/neorg/wiki/TOC}[`core.qol.toc`] - Generates a table of contents for a given Norg buffer. + - {https://github.com/nvim-neorg/neorg/wiki/Todo-Items}[`core.qol.todo_items`] - Module for implementing todo lists. + - {https://github.com/nvim-neorg/neorg/wiki/Queries-Module}[`core.queries.native`] - TS wrapper in order to fetch nodes using a custom table. + - {https://github.com/nvim-neorg/neorg/wiki/Summary}[`core.summary`] - Creates links to all files in any workspace. + - {https://github.com/nvim-neorg/neorg/wiki/Syntax}[`core.syntax`] - Handles interaction for syntax files for code blocks. + - {https://github.com/nvim-neorg/neorg/wiki/Tangling}[`core.tangle`] - An Advanced Code Block Exporter. + - {https://github.com/nvim-neorg/neorg/wiki/Norg-Text-Objects}[`core.text-objects`] - A Neorg module for moving and selecting elements of the document. + - {https://github.com/nvim-neorg/neorg/wiki/Todo-Introspector}[`core.todo-introspector`] - Module for displaying progress of completed subtasks in the virtual line. + diff --git a/doc/wiki/Tutorial.norg b/doc/wiki/Tutorial.norg new file mode 100644 index 000000000..bc91dc92f --- /dev/null +++ b/doc/wiki/Tutorial.norg @@ -0,0 +1,251 @@ + +* Getting Started + + A guide on getting started with Neorg. + +** Neorg as a Concept + + First of all, welcome! There’s quite a journey ahead of you, hope you stick around :) + + This file will get you started with Neorg as your general note taking and life management tool. + + Before we get into any of the details, let us discuss what Neorg /is/ and what it /isn’t/. Neorg is a frontend for a markup format called norg - it provides a load + of functions for interacting with these norg files. Think of Norg files as highly advanced Markdown files (if you’ve ever had experience with Markdown before). + + The beauty of markup is that it can contain /anything/ - general documentation for your project, notes about a school subject, + technical documentation for software, theses, presentation slides… you get the idea. Because plain text is so vertasile, Neorg is built to account for as many + use cases as possible. + + If you haven’t encountered this type of tool before, it’s officially called an /organizational tool/. The name is vague because, well, the concept is pretty vague! + Neorg is a tool that can handle any task you throw at it, as long as you can represent that problem in plaintext. + + Because of this, you’ll never learn /all/ of Neorg, and that’s okay! As you get more comfortable in a certain part of Neorg (e.g. the note-taking side or the + task management side) you can then extend your knowledge to other domains if you need. + +** Our First Steps + + *The first thing you’ll want to do is set up Neorg*. There’s an entire guide present {https://github.com/nvim-neorg/neorg?tab=readme-ov-file#-installation}[in the readme]! Feel free to check it out and - once you’re done - hop back into this file and get going. + + Neorg is generally always active whenever you start Neovim (unless you lazy load it) - this allows you to jump to convenient locations and files whenever you need. + + Before we get ahead of ourselves, let’s get a feel for the default state of the plugin. By default, Neorg is merely an advanced editing tool. To see why and how, open up + any directory of your choice and open up a `note.norg` file. Ready? + +** Basic Syntax + + Terminology alert: *Neorg* is the name of the Neovim plugin. *Norg* is the name of the markup format that you save onto your disk. Keep this in mind as we progress! + + Norg has a lot of default syntax that should immediately feel familiar if you’ve used `org-mode` or some Markdown. First, let’s type some text: + + default: `This is my note!` + + Just like in a basic `.txt` file or like in Markdown, any text is allowed within the document. + The power of markup languages shines in the ways you can alter the text though, so let’s learn some! + +**** Inline Markup + + Any word can be made bold, italic, underline, superscript, subscript - all through the use of modifiers. Below are a bunch of examples: + + default: `This is my note! In here I will have some *bold* text, some /italic/, _underline_, ^superscript^ and ,subscript,!` + + And indeed, upon typing those, you should see Neorg appropriately make the text *bold*, /italic/ and *underline*! Superscript and subscript cannot be properly rendered + within terminals, so they’re just coloured instead. + + /Fantastic!/ Being able to mark up any text like this without any effort is very nice. + + > [!NOTE] + If the bold, italic or underline are not showing properly you can find a troubleshooting guide {https://github.com/nvim-neorg/neorg/wiki/Dependencies}[here]! Terminals can be tricky sometimes. + +**** Lists + + As you’re writing, you’ll naturally want to enumerate some things in the form of a list. Below is a simple example of a list: + + |example + Below I'll create a list of things that I should buy: + - Apples + - Oranges + - Milk + |end + + All it takes is to prefix a line with a `-` and you’re set! Adding more than one new line will break the list apart into two: + + |example + Below I'll create two lists of things that I should buy: + - Apples + - Oranges + + - Milk + |end + + Apart from unordered lists, you may want to enforce an order on the list. You may be inclined to do something like this: + + |example +Below I'll create an ordered list of stuff: + + 1. First thing + 2. Second thing + |end + + Nobody’s stopping you from doing this, but Neorg won’t recognize the list, it’ll just think it’s text. In norg, ordered lists are defined using the tilde (`~`): + + |example + ~ First thing + ~ Second thing + |end + + If you have the {https://github.com/nvim-neorg/neorg/wiki/Concealer}[concealer] module enabled this will automatically get visually converted into a numeric list. + + This approach may seem very odd initially until it clicks. When you write lists using the `1.` syntax, any time you want to add an item or reorder the list, you have to manually update /all/ of the + items afterwards, or keep track of what the index of the previous item was. Let’s say I have a list of 10 items, and I want to move the second item to the end. Now I have to change the numbers of all + the other entries! What if I want to add a new item at the end of the list? You have to look through the list to see what the number of the last entry was so that you can increment it by one. + + Using the `~` syntax, Neorg does all of the counting for you, while still displaying the appropriate list index through the concealer. Neat! + +**** Headings + + As you write more complex notes you’ll want to divide them up in some logical fashion. Within norg, this is done through headings: + +|example +* Shopping + My shopping list consists of: + - Milk + - Butter + - Bread + |end + + As you write, you may notice that Neorg will automatically indent things for you. The indentation is based on how far the heading’s title is indented! For example, if you were to have this document: + +|example +* Shopping + My shopping list consists of: + - Milk + - Butter + - Bread + |end + + Pressing `gg=G` (`gg` - go to top of document, `=` - indent, `G` - to the bottom of the document) will indent all of the content to match the indentation of the title! + Neorg calls this /dynamic indentation/. It can of course be tweaked. + + Headings can be nested as much as you want by simply repeating the amount of asterisks! + +|example +* Shopping +** Important Shopping + This is stuff I must immediately buy: + - Bread +** Other Stuff + This is not as important: + - Milk + - Tomatoes (yum) + |end + +** Next Steps: Marking Things as Tasks + + Alright! We’ve learned how to make basic norg files, but where’s the whole "organizational" part? When will I understand? One step at a time :) + + You’ve now learned to create a basic file /somewhere/ on your filesystem, and how to write some norg markup! Before we start organizing your files into meaningful places, let’s learn about TODO + statuses. + + Say I have a list of things I’d like to do: + + |example + - Take out the trash + - Watch "how to delete emacs" video + - Wish Mum a happy birthday + |end + + On its own, this is just a list… not very useful, is it? However, norg allows us to annotate /anything/ within our documents as a task by giving it a TODO status: + + |example + - \( ) Take out the trash + - \( ) Watch "how to delete emacs" video + - \( ) Wish Mum a happy birthday + |end + + A TODO status is marked by the regular brackets right after the item itself. In our case, there’s just a space inbetween the brackets - this means the task is /undone/. + + Now let’s say I finished watching the "how to delete emacs" video, and I would like to mark it as complete. Put your cursor on the same line as the task and press `Ctrl + Space`! + This will toggle the state of the item to "done". + + > [!TIP] + If you have the concealer enabled, this will change the task to a checkmark, but what has really happened under the hood is that + the space has turned into an `x`! If you ever want to see the raw text of your file, run `:Neorg toggle-concealer` :) + + Pressing `Ctrl + Space` again will toggle the task between three states - undone, done and pending. Pending is marked by the `-` character. + + Apart from just these three states (which is what other markup formats commonly support), norg extends the amount of TODOs to a set of *twelve*! + + Apart from just undone, done and pending, all of these TODO states are available: + + |example + - \(=) On hold + - \(_) Cancelled + - \(!) Urgent + - \(?) Ambiguous (uncertain) + - \(+) Recurring (happens every so often) + |end + + To set a TODO item to a specific state you can use one of the many keybinds listed in the {https://github.com/nvim-neorg/neorg/wiki/Todo-Items#overview}[`todo_items` module’s wiki]. + + > [!NOTE] + If you’re a keen reader you will have noticed that this is nowhere near 12 TODO states. + The others are a bit more advanced, you’ll learn them as necessary! + +*** But Wait, There’s More + + Tasks aren’t exclusive to lists. In norg, you can assign a task to /anything/. Not quite + done with a heading yet? No problem! + + default: `* ( ) Undone Heading` + + This will work, as will a task status attached to anything else in this fashion. + +** Part Two: File Management + + Now that you understand the basics of norg files and what you can put inside of them, let’s give these files some meaning. + + The simplest thing to get started with is writing your own diary/journal with Neorg! By default, your journal will be placed in the current working directory. + To open up the journal run `:Neorg journal today`, it should launch you into a new file! + + A core concept of Neorg is the concept of /workspaces/. A workspace is a directory which contains an *index file* + (most commonly referred to as `index.norg`) in its root. This index file usually contains links to other parts in the workspace, sorted in some manner. + + How do we manage such workspaces, you may ask? With `core.dirman` (short for directory manager) of course! + In your configuration, add a `core.dirman` entry as illustrated below: + + @code lua + require("neorg").setup({ + load = { + ["core.defaults"] = {}, + ["core.dirman"] = { + config = { + workspaces = { + notes = "~/notes", + }, + }, + }, + }, + }) + @end + + In that snippet we set up a list of workspaces, currently with just one workspace: `notes`. + This `notes` workspace points to, you guessed it, `~/notes`! + + When in Neovim, `:Neorg workspace` will show you the current workspace you’re in. This will usually be the `default` workspace - the `default` workspace + always gets created on-the-fly and points to Neovim’s current working directory (seen via the `:pwd` command). + + To switch to the notes workspace, run `:Neorg workspace notes`. This will switch the active workspace to `notes` and immediately drop you into its + `index.norg` file! You’re free to perform any edits you may like in that workspace. + + If you were working on something beforehand (e.g. some code) you may use the + `:Neorg return` command to close all norg buffers you opened since running the + `:Neorg workspace ...` command and put you right back where you started. Neat! + +** To be continued… + + You thought it ends here! Wrong. You’ve learned that Neorg is an editing mode as well as a diary writer + and a quasi file manager. Apart from this, it has many other features that are likely to be useful for a specific use case of yours. + + The next parts of this tutorial are under construction… head over to either the {https://www.youtube.com/playlist?list=PLx2ksyallYzVI8CN1JMXhEf62j2AijeDa}[youtube series] or + the {https://github.com/nvim-neorg/neorg/wiki#other-modules}[list of modules] to further your journey with Neorg! Have fun :) + diff --git a/doc/wiki/User-Keybinds.norg b/doc/wiki/User-Keybinds.norg new file mode 100644 index 000000000..722ab3f33 --- /dev/null +++ b/doc/wiki/User-Keybinds.norg @@ -0,0 +1,85 @@ + +* `core.keybinds` + +*** The Language of Neorg + + `core.keybinds` manages mappings for operations on or in `.norg` files. + +* Overview + + The `core.keybinds` module configures an out-of-the-box Neovim experience by providing a default + set of keys. + + To disable default keybinds, see the next section. To remap the existing keys, see {https://github.com/nvim-neorg/neorg/wiki/User-Keybinds#remapping-keys}[here]. + + To find common problems, consult the {https://github.com/nvim-neorg/neorg/wiki/User-Keybinds#faq}[FAQ]. + +*** Disabling Default Keybinds + + By default when you load the `core.keybinds` module all keybinds will be enabled. If you would like to change this, be sure to set `default_keybinds` to `false`: + + @code lua + ["core.keybinds"] = { + config = { + default_keybinds = false, + }, + } + @end + +*** Remapping Keys + + To understand how to effectively remap keys, one must understand how keybinds are set. + Neorg binds actions to various `` mappings that look like so: `(neorg...`. + + To remap a key, simply map an action somewhere in your configuration: + + default: `vim.keymap.set("n", "my-key-here", "(neorg.pivot.list.toggle)", {})` + + Neorg will recognize that the key has been bound by you and not bind its own key. + +**** Binding Keys for Norg Files Only + + This approach has a downside - all of Neorg’s keybinds are set on a per-buffer basis + so that keybinds don’t "overflow" into buffers you don’t want them active in. + + When you map a key using `vim.keymap.set`, you set a global key which is always active, even in non-norg + files. There are two ways to combat this: + - Create a file under `/ftplugin/norg.lua`: + `lua vim.keymap.set("n", "my-key-here", "(neorg.pivot.list.toggle)", { buffer = true })` + - Create an autocommand using `vim.api.nvim_create_autocmd`: + `lua vim.api.nvim_create_autocmd("Filetype", { pattern = "norg", callback = function() vim.keymap.set("n", "my-key-here", "(neorg.pivot.list.toggle)", { buffer = true }) end, })` + + Notice that in both situations a `{ buffer = true }` was supplied to the function. + This way, your remapped keys will never interfere with other files. + +*** Discovering Keys + + A comprehensive list of all keybinds can be found on {https://github.com/nvim-neorg/neorg/wiki/Default-Keybinds}[this page!] + +** FAQ + +*** Some (or all) keybinds do not work + + Neorg refuses to bind keys when it knows they’ll interfere with your configuration. + Run `:checkhealth neorg` to see a full list of what keys Neorg has considered "conflicted" + or "rebound". + + If you see that /all/ of your keybinds are in conflict, you’re likely using a plugin that is mapping to your + local leader key. This is a known issue with older versions of `which-key.nvim`. Since version `3.0` of which-key the issue has been fixed - we + recommend updating to the latest version to resolve the errors. + +* Configuration + +** default_keybinds (boolean) + + Whether to enable the default keybinds. + + default: `true` + +** preset (string) + + Which keybind preset to use. + Currently allows only a single value: `"neorg"`. + + default: `"neorg"` + diff --git a/doc/wiki/_Sidebar.norg b/doc/wiki/_Sidebar.norg new file mode 100644 index 000000000..13e3c7278 --- /dev/null +++ b/doc/wiki/_Sidebar.norg @@ -0,0 +1,52 @@ + +* :star2: Neorg + + - {https://github.com/nvim-neorg/neorg/wiki/Setup-Guide}[Setup Guide] + - {https://github.com/nvim-neorg/neorg/wiki/Tutorial}[Tutorial] + - {https://github.com/nvim-neorg/neorg/wiki/Default-Keybinds}[Default Keybinds] + + Inbuilt modules: + + - {https://github.com/nvim-neorg/neorg/wiki/Autocommands}[`core.autocommands`] + - {https://github.com/nvim-neorg/neorg/wiki/Clipboard}[`core.clipboard`] + - {https://github.com/nvim-neorg/neorg/wiki/Clipboard-Code-Blocks}[`core.clipboard.code-blocks`] + - {https://github.com/nvim-neorg/neorg/wiki/Completion}[`core.completion`] + - {https://github.com/nvim-neorg/neorg/wiki/Concealer}[`core.concealer`] + - {https://github.com/nvim-neorg/neorg/wiki/Defaults}[`core.defaults`] + - {https://github.com/nvim-neorg/neorg/wiki/Dirman}[`core.dirman`] + - {https://github.com/nvim-neorg/neorg/wiki/Dirman-Utils}[`core.dirman.utils`] + - {https://github.com/nvim-neorg/neorg/wiki/Esupports-Hop}[`core.esupports.hop`] + - {https://github.com/nvim-neorg/neorg/wiki/Indent}[`core.esupports.indent`] + - {https://github.com/nvim-neorg/neorg/wiki/Metagen}[`core.esupports.metagen`] + - {https://github.com/nvim-neorg/neorg/wiki/Exporting-Files}[`core.export`] + - {https://github.com/nvim-neorg/neorg/wiki/Markdown-Export}[`core.export.markdown`] + - {https://github.com/nvim-neorg/neorg/wiki/Filesystem}[`core.fs`] + - {https://github.com/nvim-neorg/neorg/wiki/Core-Highlights}[`core.highlights`] + - {https://github.com/nvim-neorg/neorg/wiki/Coq_nvim}[`core.integrations.coq_nvim`] + - {https://github.com/nvim-neorg/neorg/wiki/Nvim-Cmp}[`core.integrations.nvim-cmp`] + - {https://github.com/nvim-neorg/neorg/wiki/Nvim-Compe}[`core.integrations.nvim-compe`] + - {https://github.com/nvim-neorg/neorg/wiki/Treesitter-Integration}[`core.integrations.treesitter`] + - {https://github.com/nvim-neorg/neorg/wiki/Itero}[`core.itero`] + - {https://github.com/nvim-neorg/neorg/wiki/Journal}[`core.journal`] + - {https://github.com/nvim-neorg/neorg/wiki/User-Keybinds}[`core.keybinds`] + - {https://github.com/nvim-neorg/neorg/wiki/Core-Latex-Renderer}[`core.latex.renderer`] + - {https://github.com/nvim-neorg/neorg/wiki/Looking-Glass}[`core.looking-glass`] + - {https://github.com/nvim-neorg/neorg/wiki/Neorgcmd-Module}[`core.neorgcmd`] + - {https://github.com/nvim-neorg/neorg/wiki/Neorgcmd-return}[`core.neorgcmd.commands.return`] + - {https://github.com/nvim-neorg/neorg/wiki/Pivot}[`core.pivot`] + - {https://github.com/nvim-neorg/neorg/wiki/Core-Presenter}[`core.presenter`] + - {https://github.com/nvim-neorg/neorg/wiki/Promo}[`core.promo`] + - {https://github.com/nvim-neorg/neorg/wiki/TOC}[`core.qol.toc`] + - {https://github.com/nvim-neorg/neorg/wiki/Todo-Items}[`core.qol.todo_items`] + - {https://github.com/nvim-neorg/neorg/wiki/Queries-Module}[`core.queries.native`] + - {https://github.com/nvim-neorg/neorg/wiki/Scanner-Module}[`core.scanner`] + - {https://github.com/nvim-neorg/neorg/wiki/Storage}[`core.storage`] + - {https://github.com/nvim-neorg/neorg/wiki/Summary}[`core.summary`] + - {https://github.com/nvim-neorg/neorg/wiki/Syntax}[`core.syntax`] + - {https://github.com/nvim-neorg/neorg/wiki/Tangling}[`core.tangle`] + - {https://github.com/nvim-neorg/neorg/wiki/Tempus}[`core.tempus`] + - {https://github.com/nvim-neorg/neorg/wiki/Norg-Text-Objects}[`core.text-objects`] + - {https://github.com/nvim-neorg/neorg/wiki/Todo-Introspector}[`core.todo-introspector`] + - {https://github.com/nvim-neorg/neorg/wiki/Core-UI}[`core.ui`] + - {https://github.com/nvim-neorg/neorg/wiki/Calendar}[`core.ui.calendar`] +