afaire.txt

*afaire.txt*                                                       *afaire.nvim*

Afaire is a minimalist Neovim plugin to handle "notes". These are prioritized
to-do lists that require a more heavy documentation than just a single line.
It aims at integrating with well-established Neovim plugins, such as Telescope
(:help telescope).

Afaire can only be configured through a Lua configuration. No vimscript setup
is available.

================================================================================
1. SETUP AND CONFIGURATION

afaire.setup({opts})                                            *afaire.setup()*
  Setup function to be called by the user prior using the plugin. There is
  no vimscript

  Usage: >
  require("afaire").setup({
    -- Entry `directories` is mandatory. It must contain at least one item.
    -- Each item is called a `directory`. It is associated with several
    -- configuration parameters, one of them (`notes`) being mandatory.
    directories = {
      work = {
        -- All notes will be stored in this directory. Archives will be
        -- written in a directory named `archives/`, which will be placed
        -- in the `notes` directory.
        notes = "~/path/to/a/directory",
      },
      home = {
        notes = "~/path/to/another/directory",
        -- In case you want to store your archives in a different directories
        -- than `notes`, you may override this settings.
        archives = "~/path/to/archives",
      },
    },

    -- When the plugin starts, it selects a directory where to write the new
    -- notes (and where to search for them). The settings below is mandatory,
    -- and it must correspond to a valid entry in the `directories` table
    -- above.
    default_directory = "work",

    -- By default, notes are markdown files, using a `.md` extension. A really
    -- determined user may want to override these settings to generate
    -- something completely different.
    --
    -- `default_filetype` expects a parameter compatible with what vim
    -- calls a filetype (:help filetype).
    --
    -- `default_extension` is just text that is suffixed to the filename of a
    -- note upon its creation. As vim uses the extension to determine the
    -- filetype, this text should be "compatible" with the selected filetype.
    default_filetype = "markdown",
    default_extension = ".md",

    -- Set this to `false` if you don't want to use the integration
    -- with telescope. Most of this plugin relies on this integration, so
    -- this would be a bad idea to disable this settings... but maybe you
    -- have an excellent reason to do so.
    with_telescope_extension = true,

    -- This settings expect to receive the name of a *highlight group* (see
    -- :help hl). This is used to color the priorities of notes within
    -- telescope. See :help afaire.hl for details.
    default_highlight_group = "Identifier",

    -- Notes may optionnally set a `due` parameter, which is expected to
    -- correspond to a time. As long as it is set, Afaire displays it through
    -- the Telescope integration. However, automatic coloration may be
    -- performed depending on the urgency of the note (i.e. how close from
    -- "today" is the due time.
    --
    -- Since the `due` parameter is a string, this settings allows the user
    -- to configure the due format. This must be a table that contain exactly
    -- three items: `year`, `month` and `day`. There can be in any order: this
    -- configures the format of the due date.
    --
    -- For example, with a value of  `{ "year", "month", "day" }`, due dates
    -- are parsed as yy/mm/dd. Note that the separator can be anyè
    -- single-letter character (e.g. a slash, a dot, a dash).
    --
    due_format = { "year", "month", "day" },

    -- This function is called to evaluate the urgency of a note. It accepts
    -- as parameter the date of the note, as a time table containing the keys
    -- `year`, `month` and `day` (see `due_format`).
    --
    -- This function must return the name of an existing highlight group to
    -- color the due date in the Telescope integration.
    evaluate_note_urgency = function(date) return "HighlightGroup" end,

    -- When a new note is created, the plugin generates a default boilerplate
    -- using the contents of the string returned by this function.
    --
    -- Its parameter `context` is a table containing the following parameters:
    -- * options: the sanitized configuration options provided to .setup()
    -- * timestamp: a timestamp generated by os.time(). It is
    --   used as part of the file name of the note. This is the creation time
    --   of the note
    -- * title: optional string provided by the user (see :help afaire.Afaire)
    --   when creating the note
    -- * file: full path to the note to be created
    template = function(context) return "string" end,

    -- This function is a bit too advanced for now. If you really are
    -- motivated, please dig in the code, or open an issue :)
    load_note_metadata = function(...) end,
  })
<

================================================================================
2. COMMANDS

afaire.Afaire(...)                                               *afaire.Afaire*

  Vim command that creates a new note (in the current directory). The plugin
  automatically creates a new note with most parameters already setup for you.
  This includes the title of the note, which corresponds to the arguments
  provided to the command?

  If no argument is provided to the command, the title must be written
  directly in the buffer.

  Save the file to write the note.

  Please note that the note file is created with a timestamp of the current
  time (in seconds). This is not robust at all to concurrent accesses. I.e.
  if two notes are simultaneously created at the same "time" within the same
  second, there will be two handled on the same file.


  Usage: >
  :Afaire My new note
  :Afaire
<

  Unless you have deeply modified the defaults of the plugin, a new note looks
  like the following: >

  ---
  title = "The title of a note (if you provided it to :Afaire)"
  created = "a human-readable date, compatible with os.date()"
  priority = "D"
  due = ""
  ---

  Write the details here, using plain markdown :)
<

  By default, a note is a markdown file. Key parameters are contained in a
  front matter (delimited by two triple dashes followed by a new line). The
  front matter consists in plain lua code. Every meaningful variable are
  already written. `due` may be left empty. `priority` must be a single 
  uppercase letter of the latin alphabet.

  See the `due_format` configuration settings for details.


afaire.AfaireDirectory(...)                                      *afaire.Afaire*

  Change the current directory. This is not the "current working directory";
  it has nothing to do with :chdir. It tells the plugin to use a different
  entry in the configuration settings `directories` to access notes.

  Usage: >
  :AfaireDirectory home
<


================================================================================
3. TELESCOPE INTEGRATION                                      *afaire.telescope*

Unless `with_telescope_extension` is explicitly set to `false`, Afaire adds an
extension to the Telescope plugin. This really is the main graphical
interface: a Telescope Picker is used to display the notes in the current
"directory". These are sorted by descending priority. It shows the following
information:

* The priority, as a single upper case letter. It is colored according to
  specific highlight groups (see :help afaire.hl)
* The "due date", if set in a note. There is space for 10 characters.
* The short title of the note.

>
  A  01/01/1900  This is the short title of a note
  Z              This is another note
<

A file previewer shows the full contents of the note file in a dedicated
interface. As this is a "classic" telescope plugin, you may use arrow keys to
navigate in the notes, and press `<CR>` (Enter) to open the note. You may also
fuzzy search among the short titles of the notes.

The additional key binding `<C-K>` (Control+K) archives the currently
highlighted note. A prompt asks for confirmation. The archived note will be
moved to the `directory.archives` directory, and removed from the telescope
interface. Please note that there is no going back: you may not "un-archive"
an archived note.

================================================================================
4. HIGHLIGHT GROUPS                                                  *afaire.hl*

Highlight groups are currently only being used with the Telescope integration.
They are used to color a note, depending on its priority. Since a priority is
a single uppercase letter of the latin alphabet (from "A" to "Z"), afaire may
use one highlight group per priority. These are named
`AfairePriority<LETTER>`, where `<LETTER>` corresponds to the priority.

As such, there are at most 26 highlight groups that Afaire uses to display the
priority of a task. Since this may be an awful lot to configure, Afaire only
sets a few of them by default (A, B, C, D, E, K, X, Y, Z). If a note has a
priority with no existing highlight group, then the value of
`default_highlight_group` is used.

Additional highlight groups are defined to notify the urgency of a task:

* `AfaireUrgencyExpired`: when the due date of a task is expired
* `AfaireUrgencyToday`: the task is due for today
* `AfaireUrgencyTwoDays`: the task is due within two days
* `AfaireUrgencyThreeDays`: the task is due within three days
* `AfaireUrgencyWeek`: the task is due within seven days (one calendar week)

You may want to override these highlight groups if the default coloration does
not suit your taste.


vim:tw=78:ts=8:ft=help:norl: