*alpha.txt*
*alpha*
==============================================================================
CONTENTS                                                        *alpha-contents*

    INTRO .......................................... |alpha-intro|
    COMMANDS ....................................... |alpha-commands|
    CONFIGURATION .................................. |alpha-configuration|
    AUTOCMD ........................................ |alpha-autocmd|
    COLORS ......................................... |alpha-colors|
    EXAMPLE ........................................ |alpha-example|

==============================================================================
INTRO                                                              *alpha-intro*

alpha is a plugin that shows a programmable greeter screen when neovim is
launched.

==============================================================================
COMMANDS                                                        *alpha-commands*

>
    :Alpha
<
Open the alpha buffer.

==============================================================================
CONFIGURATION                                              *alpha-configuration*

the following is documentation for the types alpha uses for configuration

config:
>
 config = {
    -- required

    -- table of elements from top to bottom
    -- key is arbitrary, so you can use lua's array syntax
    layout = {},

    -- optional
    opts = {
        -- number: how much space to pad on the sides of the screen
        margin = 0

        -- theme-specific setup,
        -- ran once before the first draw
        setup = function

        -- when true,
        -- use 'noautocmd' when setting 'alpha' buffer local options.
        -- this can help performance, but it will prevent the
        -- FileType autocmd from firing, which may break integration
        -- with other plguins.
        -- default: false (disabled)
        noautocmd = bool

        -- table of default keymaps
        keymap = {
            -- nil | string | string[]: key combinations used to press an
            -- item.
            press = '<CR>',
            -- nil | string | string[]: key combination used to select an item to
            -- press later.
            press_queue = '<M-CR>'
        }
    }
 }
<
button:
>
 {
    -- required

    -- element type
    type = "button",
    -- the text to display
    val = "string",
    -- what to do when the button is pressed
    -- useful functions:
    -- local key = vim.api.nvim_replace_termcodes(shortcut, true, false, true)
    -- vim.api.nvim_feedkeys(key, "normal", false)
    on_press = function() end,

    -- optional
    opts = {
        -- define a buffer-local keymap for this element
        -- accepts the arguments for 'nvim_set_keymap' as an array
        -- normally pairs with an 'on_press' function that feeds the lhs
        -- keys (see alpha.dashboard.button implementation)
        keymap = { {mode}, {lhs}, {rhs}, {*opts} }

        position = "left" | "center" | "right",
        hl = "hl_group" | {{"hl_group", 0, -1}} | {{{"hl_group", 0, -1}}}

        shortcut = "string",
        align_shortcut = "left" | "right",
        hl_shortcut = "hl_group",

        -- starting at the first character,
        -- from 0 to #shortcut + #val,
        -- place the cursor on this row
        cursor = 0,
        -- how wide to pad the button.
        -- useful if position = "center"
        width = 50,
        -- when `shrink_margin` is true, the margin will
        -- shrink when the window width is too small to display
        -- the full width margin + the full element.
        -- 'dashboard' has this set to true, since it has huge margins and
        -- small layout elements, and 'startify' has this set to
        -- false, since it has huge layout elements and a small margin
        -- defaults to true
        shrink_margin = true | false
    }
 }
<

text:
>

 {
    -- required

    -- element type
    type = "text",
    -- the text to display
    -- when it's an array, each element is placed
    -- on a different line
    val = "string" | { "array" } | function,

    -- optional
    opts = {
        position = "left" | "center" | "right",
        hl = "hl_group" | {{"hl_group", 0, -1}} | {{{"hl_group", 0, -1}}}
    }
 }
<
padding:
>
 {
    type = "padding",
    val = 0 -- number
 }
<

group:
>
 {
    -- required
    type = "group"
    val = {} | function -- table of elements

    -- optional
    opts = {
        -- number of newlines inbetween each element
        spacing = 1
        -- this table will extend the opts table of each entry of 'val'
        -- keeping the entry from 'inherit'
        -- unless the val.[n].opts.priority is >= opts.priority
        inherit = {}
        priority = 1 -- defaults to 1, see above
        -- vertically center the group within the window.
        -- padding is automatically added above the group so that the
        -- group appears centered. if elements already rendered above
        -- the group push it past the center point, no padding is added.
        position = "v_center"
    }
 }
<
terminal:
>
 -- note: require'alpha.term' must be called
 -- after require'alpha'
 {
    -- required
    type = "terminal"
    command = "string" | function -- the shell command to run
    -- command size can be fixed, or calculated by mutating these
    width = 0 -- number
    height = 0 -- number

    -- optional
    opts = {
        -- turns 'false' after the command is run
        -- when redraw = true alpha will rerun the command
        -- on the next redraw
        redraw = true
        -- see :h nvim_open_win {config} parameter
        window_config = {}
    }
 }
<

A theme may supply predefined widgets like buttons, headers, etc that
you can use to customize the theme by updating its opts table

==============================================================================
COLORS                                                            *alpha-colors*

Highlighting is handled internally by the neovim api.

Most elements accept `opts.hl = "hl_group"` or an array of
`{'hl_group', start_col, end_col}`

for multiline elements, you supply a 2 dimensional array of
`{'hl_group', start_col, end_col}`

`start_col` and `end_col` is based on byte index not char index. See
alpha.utils.charhl_to_bytehl for character-wise highlighting.

You can highlight a button shortcut by supplying a highlight group to the
option `x.opt.hl_shortcut`

the builtin themes currently highlight with builtin highlight groups
like `Number` and `Keyword`

==============================================================================
AUTOCMDS                                                        *alpha-autocmds*

alpha supports the following autocmds
- `autocmd User AlphaReady`
  meaning: alpha buffer has been loaded and has completed the first draw
- `autocmd User AlphaClosed`
  meaning: alpha buffer was unloaded

there is an option to use *:noautocmd* when setting alpha's buffer local options
see |alpha-configuration|

==============================================================================
THEME OPTIONS                                              *alpha-theme-options*

theta/startify:
>
 mru_opts = {
    -- return 'true' for paths which should not appear as entries in the MRU
    -- menu. defaults to
    ignore = function(path, ext)
        return (string.find(path, "COMMIT_EDITMSG")) or (vim.tbl_contains(default_mru_ignore, ext))
    end,
    -- when 'true', selecting an item from the MRU menu will automatically
    -- change your working directory to the parent directory of the entry.
    -- defaults to
    autocd = false
 }

 file_icons = {
     -- enable / disable icons in the MRU menu entries
     -- defaults to
     enabled = true,
     -- enable / disable highlighting for the icons in the MRU menu entries
     -- defaults to
     highlight = true,
     -- available: devicons, mini, to use nvim-web-devicons or mini.icons
     -- if provider not loaded and enabled is true, it will try to use another provider
     provider = "mini",
 }
<

theta/dashboard:
>
 -- string: replaces `leader` "leader" in the button keymaps.
 -- note: does not replace how it's displayed, so you'll want to
 -- redfine the `dashboard.section.buttons.val` table
 leader = "SPC"

==============================================================================
EXAMPLE                                                          *alpha-example*

For the default configuration, see the Quick Start guide in the README.md
>
>
 use {
     "goolord/alpha-nvim",
     config = function ()
         local alpha = require'alpha'
         local dashboard = require'alpha.themes.dashboard'
         dashboard.section.header.val = {
             [[                               __                ]],
             [[  ___     ___    ___   __  __ /\_\    ___ ___    ]],
             [[ / _ `\  / __`\ / __`\/\ \/\ \\/\ \  / __` __`\  ]],
             [[/\ \/\ \/\  __//\ \_\ \ \ \_/ |\ \ \/\ \/\ \/\ \ ]],
             [[\ \_\ \_\ \____\ \____/\ \___/  \ \_\ \_\ \_\ \_\]],
             [[ \/_/\/_/\/____/\/___/  \/__/    \/_/\/_/\/_/\/_/]],
         }
         dashboard.section.buttons.val = {
             dashboard.button( "e", "  New file" , ":ene <BAR> startinsert <CR>"),
             dashboard.button( "q", "󰅚  Quit NVIM" , ":qa<CR>"),
         }
         local handle = io.popen('fortune')
         local fortune = handle:read("*a")
         handle:close()
         dashboard.section.footer.val = fortune

         dashboard.config.opts.noautocmd = true

         vim.cmd[[autocmd User AlphaReady echo 'ready']]

         alpha.setup(dashboard.config)
     end
 }
<

Example with the startify theme:
>
    use {
        "goolord/alpha-nvim",
        requires = { 'echasnovski/mini.icons' },
        config = function ()
            local alpha = require'alpha'
            local startify = require'alpha.themes.startify'
            startify.section.header.val = {
                [[                                   __                ]],
                [[      ___     ___    ___   __  __ /\_\    ___ ___    ]],
                [[     / _ `\  / __`\ / __`\/\ \/\ \\/\ \  / __` __`\  ]],
                [[    /\ \/\ \/\  __//\ \_\ \ \ \_/ |\ \ \/\ \/\ \/\ \ ]],
                [[    \ \_\ \_\ \____\ \____/\ \___/  \ \_\ \_\ \_\ \_\]],
                [[     \/_/\/_/\/____/\/___/  \/__/    \/_/\/_/\/_/\/_/]],
            }
            startify.section.top_buttons.val = {
                startify.button( "e", "  New file" , ":ene <BAR> startinsert <CR>"),
            }
            -- disable MRU
            startify.section.mru.val = { { type = "padding", val = 0 } }
            -- disable MRU cwd
            startify.section.mru_cwd.val = { { type = "padding", val = 0 } }
            -- disable file_icons
            startify.file_icons.enabled = false
            -- startify.file_icons.highlight = false
            -- startify.file_icons.highlight = 'Keyword'
            --
            startify.section.bottom_buttons.val = {
                startify.button( "q", "󰅚  Quit NVIM" , ":qa<CR>"),
            }
            startify.section.footer.val = {
                { type = "text", val = "footer" },
            }
            -- ignore filetypes in MRU

            startify.mru_opts.ignore = function(path, ext)
                return
                        (string.find(path, "COMMIT_EDITMSG"))
                    or  (vim.tbl_contains(default_mru_ignore, ext))
            end
            alpha.setup(startify.config)
        end
    }
<

==============================================================================
FAQ                                                                  *alpha-faq*


How to work with indentLine plugin?~

    Disable the plugin while in alpha:
>
    let g:indentLine_fileTypeExclude = ['alpha']

How to disable the tabline in alpha buffer?~
  >
    autocmd User AlphaReady set showtabline=0 | autocmd BufUnload <buffer> set showtabline=2

How do I make a theme with no buttons?~

    alpha needs to know where to place the cursor, falling back to {1,0}
    negatively impacted performance, so if you want to use a theme with no
    buttons, either create an empty button
>
    { type = "button", val = "" }
<
    or arbitrarily pick an element of some other type change to
>
    el.type = "button"
<
    as the sole possible cursor position for your theme

==============================================================================

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