code:
# `use-package`

[![Join the chat at https://gitter.im/use-package/Lobby](https://badges.gitter.im/use-package/Lobby.svg)](https://gitter.im/use-package/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Build Status](https://travis-ci.org/jwiegley/use-package.svg?branch=master)](https://travis-ci.org/jwiegley/use-package)
[![MELPA](http://melpa.milkbox.net/packages/use-package-badge.svg)](http://melpa.milkbox.net/#/use-package)
[![MELPA Stable](https://stable.melpa.org/packages/use-package-badge.svg)](https://stable.melpa.org/#/use-package)

The `use-package` macro allows you to isolate package configuration in your
`.emacs` file in a way that is both performance-oriented and, well, tidy.  I
created it because I have over 80 packages that I use in Emacs, and things
were getting difficult to manage.  Yet with this utility my total load time is
around 2 seconds, with no loss of functionality!

Notes for users upgrading to 2.x are located [at the bottom](#upgrading-to-2x).

## Installing use-package

Either clone from this GitHub repository or install from
[MELPA](http://melpa.milkbox.net/) (recommended).

## Getting started

Here is the simplest `use-package` declaration:

``` elisp
;; This is only needed once, near the top of the file
(eval-when-compile
  ;; Following line is not needed if use-package.el is in ~/.emacs.d
  (add-to-list 'load-path "<path where use-package is installed>")
  (require 'use-package))

(use-package foo)
```

This loads in the package `foo`, but only if `foo` is available on your
system. If not, a warning is logged to the `*Messages*` buffer.

Use the `:init` keyword to execute code before a package is loaded.  It
accepts one or more forms, up to the next keyword:

``` elisp
(use-package foo
  :init
  (setq foo-variable t))
```

Similarly, `:config` can be used to execute code after a package is loaded.
In cases where loading is done lazily (see more about autoloading below), this
execution is deferred until after the autoload occurs:

``` elisp
(use-package foo
  :init
  (setq foo-variable t)
  :config
  (foo-mode 1))
```

As you might expect, you can use `:init` and `:config` together:

``` elisp
(use-package color-moccur
  :commands (isearch-moccur isearch-all)
  :bind (("M-s O" . moccur)
         :map isearch-mode-map
         ("M-o" . isearch-moccur)
         ("M-O" . isearch-moccur-all))
  :init
  (setq isearch-lazy-highlight t)
  :config
  (use-package moccur-edit))
```

In this case, I want to autoload the commands `isearch-moccur` and
`isearch-all` from `color-moccur.el`, and bind keys both at the global level
and within the `isearch-mode-map` (see next section).  When the package is
actually loaded (by using one of these commands), `moccur-edit` is also
loaded, to allow editing of the `moccur` buffer.

## Key-binding

Another common thing to do when loading a module is to bind a key to primary
commands within that module:

``` elisp
(use-package ace-jump-mode
  :bind ("C-." . ace-jump-mode))
```

This does two things: first, it creates an autoload for the `ace-jump-mode`
command and defers loading of `ace-jump-mode` until you actually use it.
Second, it binds the key `C-.` to that command.  After loading, you can use
`M-x describe-personal-keybindings` to see all such keybindings you've set
throughout your `.emacs` file.

A more literal way to do the exact same thing is:

``` elisp
(use-package ace-jump-mode
  :commands ace-jump-mode
  :init
  (bind-key "C-." 'ace-jump-mode))
```

When you use the `:commands` keyword, it creates autoloads for those commands
and defers loading of the module until they are used.  Since the `:init` form
is always run -- even if `ace-jump-mode` might not be on your system --
remember to restrict `:init` code to only what would succeed either way.

The `:bind` keyword takes either a cons or a list of conses:

``` elisp
(use-package hi-lock
  :bind (("M-o l" . highlight-lines-matching-regexp)
         ("M-o r" . highlight-regexp)
         ("M-o w" . highlight-phrase)))
```

The `:commands` keyword likewise takes either a symbol or a list of symbols.

NOTE: Special keys like `tab` or `F1`-`Fn` can be written in square brackets,
i.e. `[tab]` instead of `"tab"`. The syntax for the keybindings is similar to
the "kbd" syntax: see [https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html](https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html)
for more information.

Examples:

``` elisp
(use-package helm
  :bind (("M-x" . helm-M-x)
         ("M-<f5>" . helm-find-files)
         ([f10] . helm-buffers-list)
         ([S-f10] . helm-recentf)))
```

Furthermore, [remapping commands](https://www.gnu.org/software/emacs/manual/html_node/elisp/Remapping-Commands.html)
with `:bind` and `bind-key` works as expected, because when the
binding is a vector, it is passed straight to `define-key`. So the
following example will rebind `M-q` (originally `fill-paragraph`) to
`unfill-toggle`:

``` elisp
(use-package unfill
  :bind ([remap fill-paragraph] . unfill-toggle))
```

### Binding to keymaps

Normally `:bind` expects that commands are functions that will be autoloaded
from the given package. However, this does not work if one of those commands
is actually a keymap, since keymaps are not functions, and cannot be
autoloaded using Emacs' `autoload` mechanism.

To handle this case, `use-package` offers a special, limited variant of
`:bind` called `:bind-keymap`. The only difference is that the "commands"
bound to by `:bind-keymap` must be keymaps defined in the package, rather than
command functions. This is handled behind the scenes by generating custom code
that loads the package containing the keymap, and then re-executes your
keypress after the first load, to reinterpret that keypress as a prefix key.

For example:

``` elisp
(use-package projectile
  :bind-keymap
  ("C-c p" . projectile-command-map))
```

### Binding within local keymaps

Slightly different from binding a key to a keymap, is binding a key *within* a
local keymap that only exists after the package is loaded.  `use-package`
supports this with a `:map` modifier, taking the local keymap to bind to:

``` elisp
(use-package helm
  :bind (:map helm-command-map
         ("C-c h" . helm-execute-persistent-action)))
```

The effect of this statement is to wait until `helm` has loaded, and then to
bind the key `C-c h` to `helm-execute-persistent-action` within Helm's local
keymap, `helm-mode-map`.

Multiple uses of `:map` may be specified. Any binding occurring before the
first use of `:map` are applied to the global keymap:

``` elisp
(use-package term
  :bind (("C-c t" . term)
         :map term-mode-map
         ("M-p" . term-send-up)
         ("M-n" . term-send-down)
         :map term-raw-map
         ("M-o" . other-window)
         ("M-p" . term-send-up)
         ("M-n" . term-send-down)))
```

## Modes and interpreters

Similar to `:bind`, you can use `:mode` and `:interpreter` to establish a
deferred binding within the `auto-mode-alist` and `interpreter-mode-alist`
variables. The specifier to either keyword can be a cons cell, a list of cons
cells, or a string or regexp:

``` elisp
(use-package ruby-mode
  :mode "\\.rb\\'"
  :interpreter "ruby")

;; The package is "python" but the mode is "python-mode":
(use-package python
  :mode ("\\.py\\'" . python-mode)
  :interpreter ("python" . python-mode))
```

If you aren't using `:commands`, `:bind`, `:bind*`, `:bind-keymap`,
`:bind-keymap*`, `:mode`, or `:interpreter` (all of which imply `:defer`; see
the docstring for `use-package` for a brief description of each), you can
still defer loading with the `:defer` keyword:

``` elisp
(use-package ace-jump-mode
  :defer t
  :init
  (autoload 'ace-jump-mode "ace-jump-mode" nil t)
  (bind-key "C-." 'ace-jump-mode))
```

This does exactly the same thing as the following:

``` elisp
(use-package ace-jump-mode
  :bind ("C-." . ace-jump-mode))
```

## Magic handlers

Similar to `:mode` and `:interpreter`, you can also use `:magic` and
`:magic-fallback` to cause certain function to be run if the beginning of a
file matches a given regular expression. The difference between the two is
that `:magic-fallback` has a lower priority than `:mode`. For example:

``` elisp
(use-package pdf-tools
  :load-path "site-lisp/pdf-tools/lisp"
  :magic ("%PDF" . pdf-view-mode)
  :config
  (pdf-tools-install))
```

This registers an autoloaded command for `pdf-view-mode`, defers loading of
`pdf-tools`, and runs `pdf-view-mode` if the beginning of a buffer matches the
string `"%PDF"`.

## Hooks

The `:hook` keyword allows adding functions onto hooks, here only the basename
of the hook is required. Thus, all of the following are equivalent:

``` elisp
(use-package ace-jump-mode
  :hook prog-mode)

(use-package ace-jump-mode
  :hook (prog-mode . ace-jump-mode))

(use-package ace-jump-mode
  :commands ace-jump-mode
  :init
  (add-hook 'prog-mode-hook #'ace-jump-mode))
```

And likewise, when multiple hooks should be applied, the following are also
equivalent:

``` elisp
(use-package ace-jump-mode
  :hook (prog-mode text-mode))

(use-package ace-jump-mode
  :hook ((prog-mode text-mode) . ace-jump-mode))

(use-package ace-jump-mode
  :hook ((prog-mode . ace-jump-mode)
         (text-mode . ace-jump-mode)))

(use-package ace-jump-mode
  :commands ace-jump-mode
  :init
  (add-hook 'prog-mode-hook #'ace-jump-mode)
  (add-hook 'text-mode-hook #'ace-jump-mode))
```

The use of `:hook`, as with `:bind`, `:mode`, `:interpreter`, etc., causes the
functions being hooked to implicitly be read as `:commands` (meaning they will
establish interactive `autoload` definitions for that module, if not already
defined as functions), and so `:defer t` is also implied by `:hook`.

## Package customization

### Customizing variables.

The `:custom` keyword allows customization of package custom variables.

``` elisp
(use-package comint
  :custom
  (comint-buffer-maximum-size 20000 "Increase comint buffer size.")
  (comint-prompt-read-only t "Make the prompt read only."))
```

The documentation string is not mandatory.

**NOTE**: These are only for people who wish to keep customizations with their
accompanying use-package declarations. Functionally, the only benefit over
using `setq` in a `:config` block is that customizations might execute code
when values are assigned. If you currently use `M-x customize-option` and save
to a settings file, you do not want to use this option.

### Customizing faces

The `:custom-face` keyword allows customization of package custom faces.

``` elisp
(use-package eruby-mode
  :custom-face
  (eruby-standard-face ((t (:slant italic)))))
```

## Notes about lazy loading

In almost all cases you don't need to manually specify `:defer t`.  This is
implied whenever `:bind` or `:mode` or `:interpreter` is used.  Typically, you
only need to specify `:defer` if you know for a fact that some other package
will do something to cause your package to load at the appropriate time, and
thus you would like to defer loading even though use-package isn't creating
any autoloads for you.

You can override package deferral with the `:demand` keyword.  Thus, even if
you use `:bind`, using `:demand` will force loading to occur immediately and
not establish an autoload for the bound key.

## Information about package loads

When a package is loaded, and if you have `use-package-verbose` set to `t`, or
if the package takes longer than 0.1s to load, you will see a message to
indicate this loading activity in the `*Messages*` buffer.  The same will
happen for configuration, or `:config` blocks that take longer than 0.1s to
execute.  In general, you should keep `:init` forms as simple and quick as
possible, and put as much as you can get away with into the `:config` block.
This way, deferred loading can help your Emacs to start as quickly as
possible.

Additionally, if an error occurs while initializing or configuring a package,
this will not stop your Emacs from loading.  Rather, the error will be
captured by `use-package`, and reported to a special `*Warnings*` popup
buffer, so that you can debug the situation in an otherwise functional Emacs.

## Conditional loading

You can use the `:if` keyword to predicate the loading and initialization of
modules.

For example, I only want `edit-server` running for my main,
graphical Emacs, not for other Emacsen I may start at the command line:

``` elisp
(use-package edit-server
  :if window-system
  :init
  (add-hook 'after-init-hook 'server-start t)
  (add-hook 'after-init-hook 'edit-server-start t))
```
In another example, we can load things conditional on the operating system:

``` elisp
(use-package exec-path-from-shell
  :if (memq window-system '(mac ns))
  :ensure t
  :config
  (exec-path-from-shell-initialize))
```

The `:disabled` keyword can turn off a module you're having difficulties with,
or stop loading something you're not using at the present time:

``` elisp
(use-package ess-site
  :disabled
  :commands R)
```

When byte-compiling your `.emacs` file, disabled declarations are omitted
from the output entirely, to accelerate startup times.

Note that `:when` is provided as an alias for `:if`, and `:unless foo` means
the same thing as `:if (not foo)`. For example, the following will also stop
`:ensure` from happening on Mac systems:

``` elisp
(when (memq window-system '(mac ns))
  (use-package exec-path-from-shell
    :ensure t
    :config
    (exec-path-from-shell-initialize)))
```

### Conditional loading before :preface

If you need to conditionalize a use-package form so that the condition occurs
before even the `:preface` is executed, simply use `when` around the
use-package form itself:

### Loading packages in sequence

Sometimes it only makes sense to configure a package after another has been
loaded, because certain variables or functions are not in scope until that
time. This can achieved using an `:after` keyword that allows a fairly rich
description of the exact conditions when loading should occur. Here is an
example:

``` elisp
(use-package hydra
  :load-path "site-lisp/hydra")

(use-package ivy
  :load-path "site-lisp/swiper")

(use-package ivy-hydra
  :after (ivy hydra))
```

In this case, because all of these packages are demand-loaded in the order
they occur, the use of `:after` is not strictly necessary. By using it,
however, the above code becomes order-independent, without an implicit
depedence on the nature of your init file.

By default, `:after (foo bar)` is the same as `:after (:all foo bar)`, meaning
that loading of the given package will not happen until both `foo` and `bar`
have been loaded. Here are some of the other possibilities:

``` elisp
:after (foo bar)
:after (:all foo bar)
:after (:any foo bar)
:after (:all (:any foo bar) (:any baz quux))
:after (:any (:all foo bar) (:all baz quux))
```

When you nest selectors, such as `(:any (:all foo bar) (:all baz quux))`, it
means that the package will be loaded when either both `foo` and `bar` have
been loaded, or both `baz` and `quux` have been loaded.

Note: Pay attention if you set `use-package-always-defer` to t, and also use
the `:after` keyword, as you will need to specify how the declared package is
to be loaded: e.g., by some `:bind`. If you're not using one of tho mechanisms
that registers autoloads, such as `:bind` or `:hook`, and your package manager
does not provide autoloads, it's possible that without adding `:demand t` to
those declarations, your package will never be loaded.

### Prevent loading if dependencies are missing

While the `:after` keyword delays loading until the dependencies are loaded,
the somewhat simpler `:requires` keyword simply never loads the package if the
dependencies are not available at the time the `use-package` declaration is
encountered. By "available" in this context it means that `foo` is available
of `(featurep 'foo)` evaulates to a non-nil value. For example:

``` elisp
(use-package abbrev
  :requires foo)
```

This is the same as:

``` elisp
(use-package abbrev
  :if (featurep 'foo))
```

As a convenience, a list of such packages may be specified:

``` elisp
(use-package abbrev
  :requires (foo bar baz))
```

For more complex logic, such as that supported by `:after`, simply use `:if`
and the appropriate Lisp expression.

## Byte-compiling your .emacs

Another feature of `use-package` is that it always loads every file that it
can when `.emacs` is being byte-compiled.  This helps to silence spurious
warnings about unknown variables and functions.

However, there are times when this is just not enough.  For those times, use
the `:defines` and `:functions` keywords to introduce dummy variable and
function declarations solely for the sake of the byte-compiler:

``` elisp
(use-package texinfo
  :defines texinfo-section-list
  :commands texinfo-mode
  :init
  (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode)))
```

If you need to silence a missing function warning, you can use `:functions`:

``` elisp
(use-package ruby-mode
  :mode "\\.rb\\'"
  :interpreter "ruby"
  :functions inf-ruby-keys
  :config
  (defun my-ruby-mode-hook ()
    (require 'inf-ruby)
    (inf-ruby-keys))

  (add-hook 'ruby-mode-hook 'my-ruby-mode-hook))
```

### Prevent a package from loading at compile-time

Normally, `use-package` will load each package at compile time before
compiling the configuration, to ensure that any necessary symbols are in scope
to satisfy the byte-compiler.  At times this can cause problems, since a
package may have special loading requirements, and all that you want to use
`use-package` for is to add a configuration to the `eval-after-load` hook.  In
such cases, use the `:no-require` keyword:

``` elisp
(use-package foo
  :no-require t
  :config
  (message "This is evaluated when `foo' is loaded"))
```

## Extending the load-path

If your package needs a directory added to the `load-path` in order to load,
use `:load-path`.  This takes a symbol, a function, a string or a list of
strings.  If the path is relative, it is expanded within
`user-emacs-directory`:

``` elisp
(use-package ess-site
  :load-path "site-lisp/ess/lisp/"
  :commands R)
```

Note that when using a symbol or a function to provide a dynamically generated
list of paths, you must inform the byte-compiler of this definition so the
value is available at byte-compilation time.  This is done by using the
special form `eval-and-compile` (as opposed to `eval-when-compile`).  Further,
this value is fixed at whatever was determined during compilation, to avoid
looking up the same information again on each startup:

``` elisp
(eval-and-compile
  (defun ess-site-load-path ()
    (shell-command "find ~ -path ess/lisp")))

(use-package ess-site
  :load-path (lambda () (list (ess-site-load-path)))
  :commands R)
```

## Catching errors during use-package expansion

By default, if `use-package-expand-minimally` is nil (the default),
use-package will attempts to catch and report errors that occur during
expansion of use-package declarations in your init file. Setting
`use-package-expand-minimally` to t completely disables this checking.

This behavior may be overridden locally using the `:catch` keyword. If `t` or
`nil`, it enables or disables catching errors at load time. It can also be a
function taking two arguments: the keyword being processed at the time the
error was encountered, and the error object (as generated by
`condition-case`). For example:

``` elisp
(use-package example
  ;; Note that errors are never trapped in the preface, since doing so would
  ;; hide definitions from the byte-compiler.
  :preface (message "I'm here at byte-compile and load time.")
  :init (message "I'm always here at startup")
  :config
  (message "I'm always here after the package is loaded")
  (error "oops")
  ;; Don't try to (require 'example), this is just an example!
  :no-require t
  :catch (lambda (keyword err)
           (message (error-message-string err))))
```

Evaluating the above form will print these messages:

```
I’m here at byte-compile and load time.
I’m always here at startup
Configuring package example...
I’m always here after the package is loaded
oops
```

## Diminishing and delighting minor modes

`use-package` also provides built-in support for the diminish and
delight utilities -- if you have them installed. Their purpose is to
remove or change minor mode strings in your mode-line.

[diminish](https://github.com/myrjola/diminish.el) is invoked with
the `:diminish` keyword, which is passed either a minor mode symbol, a
cons of the symbol and its replacement string, or just a replacement
string, in which case the minor mode symbol is guessed to be the
package name with "-mode" appended at the end:

``` elisp
(use-package abbrev
  :diminish abbrev-mode
  :config
  (if (file-exists-p abbrev-file-name)
      (quietly-read-abbrev-file)))
```

[delight](https://elpa.gnu.org/packages/delight.html) is invoked with
the `:delight` keyword, which is passed a minor mode symbol, a
replacement string or
quoted
[mode-line data](https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Line-Data.html) (in
which case the minor mode symbol is guessed to be the package name
with "-mode" appended at the end), both of these, or several lists of
both. If no arguments are provided, the default mode name is hidden
completely.

``` elisp
;; Don't show anything for rainbow-mode.
(use-package rainbow-mode
  :delight)

;; Don't show anything for auto-revert-mode, which doesn't match
;; its package name.
(use-package autorevert
  :delight auto-revert-mode)

;; Remove the mode name for projectile-mode, but show the project name.
(use-package projectile
  :delight '(:eval (concat " " (projectile-project-name))))

;; Completely hide visual-line-mode and change auto-fill-mode to " AF".
(use-package emacs
  :delight
  (auto-fill-function " AF")
  (visual-line-mode))
```

## Package installation

You can use `use-package` to load packages from ELPA with `package.el`. This
is particularly useful if you share your `.emacs` among several machines; the
relevant packages are downloaded automatically once declared in your `.emacs`.
The `:ensure` keyword causes the package(s) to be installed automatically if
not already present on your system (set `(setq use-package-always-ensure t)`
if you wish this behavior to be global for all packages):

``` elisp
(use-package magit
  :ensure t)
```

If you need to install a different package from the one named by
`use-package`, you can specify it like this:

``` elisp
(use-package tex
  :ensure auctex)
```

Note that `:ensure` will install a package if it is not already installed, but
it does not keep it up-to-date. If you want to keep your packages updated
automatically, one option is to use
[auto-package-update](https://github.com/rranelli/auto-package-update.el),
like

``` elisp
(use-package auto-package-update
  :config
  (setq auto-package-update-delete-old-versions t)
  (setq auto-package-update-hide-results t)
  (auto-package-update-maybe))
```

Lastly, when running on Emacs 24.4 or later, use-package can pin a package to
a specific archive, allowing you to mix and match packages from different
archives.  The primary use-case for this is preferring packages from the
`melpa-stable` and `gnu` archives, but using specific packages from `melpa`
when you need to track newer versions than what is available in the `stable`
archives is also a valid use-case.

By default `package.el` prefers `melpa` over `melpa-stable` due to the
versioning `(> evil-20141208.623 evil-1.0.9)`, so even if you are tracking
only a single package from `melpa`, you will need to tag all the non-`melpa`
packages with the appropriate archive. If this really annoys you, then you can
set `use-package-always-pin` to set a default.

If you want to manually keep a package updated and ignore upstream updates,
you can pin it to `manual`, which as long as there is no repository by that
name, will Just Work(tm).

`use-package` throws an error if you try to pin a package to an archive that
has not been configured using `package-archives` (apart from the magic
`manual` archive mentioned above):

```
Archive 'foo' requested for package 'bar' is not available.
```

Example:

``` elisp
(use-package company
  :ensure t
  :pin melpa-stable)

(use-package evil
  :ensure t)
  ;; no :pin needed, as package.el will choose the version in melpa

(use-package adaptive-wrap
  :ensure t
  ;; as this package is available only in the gnu archive, this is
  ;; technically not needed, but it helps to highlight where it
  ;; comes from
  :pin gnu)

(use-package org
  :ensure t
  ;; ignore org-mode from upstream and use a manually installed version
  :pin manual)
```

**NOTE**: the `:pin` argument has no effect on emacs versions < 24.4.

### Usage with other package managers

By overriding `use-package-ensure-function` and/or
`use-package-pre-ensure-function`, other package managers can override
`:ensure` to use them instead of `package.el`. At the present time,
the only package manager that does this
is [`straight.el`](https://github.com/raxod502/straight.el).

## Gathering Statistics

If you'd like to see how many packages you've loaded, what stage of
initialization they've reached, and how much aggregate time they've
spent (roughly), you can enable `use-package-compute-statistics` after
loading `use-package` but before any `use-package` forms, and then run
the command `M-x use-package-report` to see the results. The buffer
displayed is a tabulated list. You can use `S` in a column to sort the
rows based on it.

## Keyword Extensions

Starting with version 2.0, `use-package` is based on an extensible
framework that makes it easy for package authors to add new keywords,
or modify the behavior of existing keywords.

Some keyword extensions are now included in the `use-package`
distribution and can be optionally installed.

### `(use-package-ensure-system-package)`

The `:ensure-system-package` keyword allows you to ensure system
binaries exist alongside your package declarations.

First, you will want to make sure `exec-path` is cognisant of all
binary package names that you would like to ensure are
installed. [`exec-path-from-shell`](https://github.com/purcell/exec-path-from-shell)
is often a good way to do this.

To enable the extension after you've loaded `use-package`:

``` elisp
(use-package use-package-ensure-system-package
  :ensure t)
```

Here’s an example of usage:

``` emacs-lisp
(use-package rg
  :ensure-system-package rg)
```

This will expect a global binary package to exist called `rg`. If it
does not, it will use your system package manager (using the package
[`system-packages`](https://github.com/jabranham/system-packages)) to
attempt an install of a binary by the same name asyncronously. For
example, for most `macOS` users this would call: `brew install rg`.

If the package is named differently than the binary, you can use a
cons in the form of  `(binary . package-name)`, i.e.:

``` emacs-lisp
(use-package rg
  :ensure-system-package
  (rg . ripgrep))
```

In the previous `macOS` example, this would call: `brew install
ripgrep` if `rg` was not found.

What if you want to customize the install command further?

``` emacs-lisp
(use-package tern
  :ensure-system-package (tern . "npm i -g tern"))
```

`:ensure-system-package` can also take a cons where its `cdr` is a
string that will get called by `(async-shell-command)` to install if
it isn’t found.

You may also pass in a list of cons-es:

``` emacs-lisp
(use-package ruby-mode
  :ensure-system-package
  ((rubocop     . "gem install rubocop")
   (ruby-lint   . "gem install ruby-lint")
   (ripper-tags . "gem install ripper-tags")
   (pry         . "gem install pry")))
```

### `(use-package-chords)`

The `:chords` keyword allows you to define
[`key-chord`](http://www.emacswiki.org/emacs/key-chord.el) bindings
for `use-package` declarations in the same manner as the `:bind`
keyword.

To enable the extension:

``` elisp
(use-package use-package-chords
  :ensure t
  :config (key-chord-mode 1))
```

Then you can define your chord bindings in the same manner as `:bind` using a cons or a list of conses:

``` elisp
(use-package ace-jump-mode
  :chords (("jj" . ace-jump-char-mode)
           ("jk" . ace-jump-word-mode)
           ("jl" . ace-jump-line-mode)))
```

### How to create an extension

#### First step: Add the keyword

The first step is to add your keyword at the right place in
`use-package-keywords`.  This list determines the order in which things will
happen in the expanded code.  You should never change this order, but it gives
you a framework within which to decide when your keyword should fire.

#### Second step: Create a normalizer

Define a normalizer for your keyword by defining a function named after the
keyword, for example:

``` elisp
(defun use-package-normalize/:pin (name-symbol keyword args)
  (use-package-only-one (symbol-name keyword) args
    (lambda (label arg)
      (cond
       ((stringp arg) arg)
       ((symbolp arg) (symbol-name arg))
       (t
        (use-package-error
         ":pin wants an archive name (a string)"))))))
```

The job of the normalizer is take a list of arguments (possibly nil), and turn
it into the single argument (which could still be a list) that should appear
in the final property list used by `use-package`.

#### Third step: Create a handler

Once you have a normalizer, you must create a handler for the keyword:

``` elisp
(defun use-package-handler/:pin (name-symbol keyword archive-name rest state)
  (let ((body (use-package-process-keywords name-symbol rest state)))
    ;; This happens at macro expansion time, not when the expanded code is
    ;; compiled or evaluated.
    (if (null archive-name)
        body
      (use-package-pin-package name-symbol archive-name)
      (use-package-concat
       body
       `((push '(,name-symbol . ,archive-name)
               package-pinned-packages))))))
```

Handlers can affect the handling of keywords in two ways.  First, it can
modify the `state` plist before recursively processing the remaining keywords,
to influence keywords that pay attention to the state (one example is the
state keyword `:deferred`, not to be confused with the `use-package` keyword
`:defer`).  Then, once the remaining keywords have been handled and their
resulting forms returned, the handler may manipulate, extend, or just ignore
those forms.

The task of each handler is to return a *list of forms* representing code to
be inserted.  It does not need to be a `progn` list, as this is handled
automatically in other places.  Thus it is very common to see the idiom of
using `use-package-concat` to add new functionality before or after a code
body, so that only the minimum code necessary is emitted as the result of a
`use-package` expansion.

#### Fourth step: Test it out

After the keyword has been inserted into `use-package-keywords`, and a
normalizer and a handler defined, you can now test it by seeing how usages of
the keyword will expand.  For this, temporarily set `use-package-debug` to
`t`, and just evaluate the `use-package` declaration.  The expansion will be
shown in a special buffer called `*use-package*`.

## Some timing results

On my Retina iMac, the "Mac port" variant of Emacs 24.4 loads in 0.57s, with
around 218 packages configured (nearly all of them lazy-loaded).  However, I
experience no loss of functionality, just a bit of latency when I'm first
starting to use Emacs (due to the autoloading).  Since I also use idle-loading
for many packages, perceived latency is typically reduced overall.

On Linux, the same configuration loads in 0.32s.

If I don't use Emacs graphically, I can test the absolute minimum times.  This
is done by running:

``` bash
time emacs -l init.elc -batch --eval '(message "Hello, world!")'
```

On the Mac I see an average of 0.36s for the same configuration, and on Linux
0.26s.

# Upgrading to 2.x

## Semantics of :init is now consistent

The meaning of `:init` has been changed: It now *always* happens before
package load, whether `:config` has been deferred or not.  This means that
some uses of `:init` in your configuration may need to be changed to `:config`
(in the non-deferred case).  For the deferred case, the behavior is unchanged
from before.

Also, because `:init` and `:config` now mean "before" and "after", the `:pre-`
and `:post-` keywords are gone, as they should no longer be necessary.

Lastly, an effort has been made to make your Emacs start even in the presence
of use-package configuration failures.  So after this change, be sure to check
your `*Messages*` buffer.  Most likely, you will have several instances where
you are using `:init`, but should be using `:config` (this was the case for me
in a number of places).

## :idle has been removed

I am removing this feature for now because it can result in a nasty
inconsistency.  Consider the following definition:

``` elisp
(use-package vkill
  :commands vkill
  :idle (some-important-configuration-here)
  :bind ("C-x L" . vkill-and-helm-occur)
  :init
  (defun vkill-and-helm-occur ()
    (interactive)
    (vkill)
    (call-interactively #'helm-occur))

  :config
  (setq vkill-show-all-processes t))
```

If I load my Emacs and wait until the idle timer fires, then this is the
sequence of events:

    :init :idle <load> :config

But if I load Emacs and immediately type C-x L without waiting for the idle
timer to fire, this is the sequence of events:

    :init <load> :config :idle

It's possible that the user could use `featurep` in their idle to test for
this case, but that's a subtlety I'd rather avoid.

## :defer now accepts an optional integer argument

`:defer [N]` causes the package to be loaded -- if it has not already been --
after `N` seconds of idle time.

``` elisp
(use-package back-button
  :commands (back-button-mode)
  :defer 2
  :init
  (setq back-button-show-toolbar-buttons nil)
  :config
  (back-button-mode 1))
```

## Add :preface, occurring before everything except :disabled

`:preface` can be used to establish function and variable definitions that
will 1) make the byte-compiler happy (it won't complain about functions whose
definitions are unknown because you have them within a guard block), and 2)
allow you to define code that can be used in an `:if` test.

Note that whatever is specified within `:preface` is evaluated both at load
time and at byte-compilation time, in order to ensure that definitions are
seen by both the Lisp evaluator and the byte-compiler, so you should avoid
having any side-effects in your preface, and restrict it merely to symbol
declarations and definitions.

## Add :functions, for declaring functions to the byte-compiler

What `:defines` does for variables, `:functions` does for functions.

## use-package.el is no longer needed at runtime

This means you should put the following at the top of your Emacs, to further
reduce load time:

``` elisp
(eval-when-compile
  (require 'use-package))
(require 'diminish)                ;; if you use :diminish
(require 'bind-key)                ;; if you use any :bind variant
```


code:
#+TITLE: Joshua Branson
#+AUTHOR:wayfire.org
#+LATEX_HEADER: \usepackage{lmodern}
#+LATEX_HEADER: \usepackage[QX]{fontenc}

* getting a proper desktop background
<ammen99> 1) you have installed wf-shell and `wf-background` is in your $PATH
<ammen99> 2) you have `~/.config/wayfire.ini`
<joshuaBPMan> you know...probably not.
<joshuaBPMan> haha.
<joshuaBPMan> Let me find out.  [17:05]
<ammen99> 3) you have `~/.config/wf-shell.ini`
* getting wayfire's panel

https://github.com/WayfireWM/wf-shell

repo_name: hwpplayers/cheatsheets

license: mit


code:
#+AUTHOR: Joshua Branson
#+Title: WHM Cheatsheet

* To change a FTP password on a domain
 - log into WHM [[file:~/programming/org/gtd/projects/working-for-waypoint.org::*password%20related%20notes][WHM info]]
 - in the search bar, search for Password Mod
 - In the appearing domain listing, click your domain
 - click on the password generator
 - click that I saved the password
 - click any of the checkboxs
 - update the info

Usually the resulting ftp info is

|-------------------------+----------+------------|
| host                    | username | password   |
|-------------------------+----------+------------|
| www.setyourwaypoint.com | <domain> | <password> |
| www.setyourwaypoint.com | tdsdrive | secret...  |
|-------------------------+----------+------------|


code:
#+TITLE: Wordpress Cheatsheet
#+AUTHOR: Joshua Branson

* Familiarizing Yourself With Wordpress
** Vocab
You can find more vocab words specific to wordpress [[https://codex.wordpress.org/Glossary][in the glossary,]]  and in the [[https://codex.wordpress.org/WordPress_Semantics][Semantics]]
- *posts* are the elements that make up a web page.  Every time someone makes a blog post, they create a post.
- *media* pictures, video, etc. that enhance a blog.
- *categories* are a hierarchically taxonomies.  Each post is filed under 1 or more categories, and some categories can have parent categories.
- *tags* are keywords that hint at the content in a post.  Tags are flat taxonomies.  They have no parent or child tags.
- *taxonomies* are grouping constructs, of which the two default are tags and categories.
- *custom taxonomies* are user created taxonomies that allow the end-user, which is the user visiting the site, to better search for posts, pages, or custom post types.  You could create a custom taxonomy called "post size", that would group
  posts based on their length.  So if a post had many words, it would be large, then there would be a medium, and small.
  You could then let a user select posts based on the post's length.
- *custom post types* are web developer defined post types.  You could create a custom taxonomy to post types
- *post meta data* is the information associated with a post.  This includes tags, categories, custom taxonomies, the author, date of publication, etc.  It is like the tag on a t-shirt.  It gives you extra information about the product, but the tag is /not/ the product.
- *Meta Section* a section on the wordpress site that allows a user to log in.  It is like a front door in that you can walk and see the inside of the site if you log in, just like walking in a door.
- *Pages* are static pages that are usually not changed often.
- *custom post types* are like accrisoft's custom directories.  They group data in ways that can be queries and posted to the page.  They are like a new genetically engineered cloned new animal.  There is no other animal on earth like these clones, but I can create as many of them as I want.
- *The Loop* processes the display of posts.  This is at the core of wordpress.  It loops over the title of an article, the excerpt, content, category, tag, etc.
- *Template Tags* are a group of php functions that perform an action or display info. ie: wp_page_title ()
- *Template Files* contain the programming things that control how a wordpress site looks
- *widgets* are little programs that can be added to pages
- *menus* a list of navigational items that help your user navigate the site
- *Post Formats* allow one to control the display of a specific post
- *Plugins* are add-ons that extend wordpress
** Specific php files
# I found this information here: https://yoast.com/wordpress-theme-anatomy/
- *rtl.css*
  The right to left stylesheet that is included automatically if this in an english blog
- *The Loop* displays the contents of the main area of your site.
- *index.php* This is the main template file.  It is required in all themes.  If *home.php* does not exist, and if your site does /NOT/

  A working index.php can look like this:

  #+BEGIN_EXAMPLE
<?php
get_header();
if (have_posts()) :
   while (have_posts()) :
      the_post();
         the_content();
   endwhile;
endif;
get_sidebar();
get_footer();
?>

  #+END_EXAMPLE
have a specified static homepage, then *index.php* will be loaded (by default to list the latest blog posts).
- *home.php* This is the home page by default, and it normally shows the latest blog posts.  BUT if you specify that your site should have a static front page, then *front-page.php* will be used instead.
- *front-page.php* This page is loaded if a static front page is specified under Admin > Settings > Reading.
- *header.php*
  Displays the header of the website and sets the html element "meta" values.
- *single.php* displays a single post.  So, when read you read a post in the blog, single.php generated it.  You can also specify if you want a sidebar to show here as well.  For this page and for all others, index.php is used if the query template is not present.
- *single-{post-type}.php* This is user when the user views a single post from a custom post type.  For example, single-book.php is what wordpress would use to display a specific book that that user clicks on: ie:  Chronicles of Narnia.
- *archive-{post-type}.php* displays old archive posts from a specific post type.  ie: /archive-books.php/ will display an archive of posts from the custom post type "books".  Do archive pages show many posts?  1, 2, or 3?  Or none?  If the user clicks on a specific post type but /archive-{post-type}.php/ does not exist, then wordpress uses /archive.php/ to load the page.
- *archive.php* When viewing 10 or so archived articles blurbs, *archive.php* will configure how their appear on the page.
- *page.php* controls what individual pages look like.  I can even specify sidebars or other element that I so desire.  I can apparently create new page templates by copying _page.php_, renaming it to whatever I want, then pasting in the following code:
  #+BEGIN_SRC
  <?php
  /*
  Template Name: YourNameHere
  */
  ?>
  #+END_SRC

But how would that work?  If I copy page.php on the server, then there would be 2 files: page.php & page.phpCopy.  This would not add a new page type.  If I copied page.php into a child theme, this would /not/ work either, because the child theme's page.php would over-ride the parent theme.  hmmm?
- *page-{slug}.php* This determines what the user will see when visiting a specific page.  For example, when a user visits about.php, wordpress uses page-about.php to display the page.
- *category.php* is word when users request posts by categories.
- *tag.php* is used when when visitors request posts by tag.
- *taxonomy.php* is used when a user of the site selects a sub-taxonomy in a costum taxonomy.php.  So perhaps you have a taxonomy called
people.  You could have a sub-taxonomy called a /term/ Nationality with values in the database "Irish" and "German".
- *comments.php* control the output of the comments
- *single-<custom post type>.php* displays single custom defined posts.  For example, if you define a custom post type called "review", then you would call your file *single-review.php*, and somehow magic happens.
** folders
:PROPERTIES:
:ORDERED:  t
:END:
- *wp-admin* is the directory in wordpress that manage the admin view of wordpress
- *wp-content* is the dir where your wordpress site is stored
  - *plugins* houses your wordpress plugins
  - *themes* house your wordpress themes
  - *uploads* are probably your media files
- *wp-include*
  are the core files of wordpress.  It is how wordpress communicates to the database.
- *wp-config.php* is at the base of the wordpress install and it has all the information for your database connections.
* Removing functions from wordpress themes
[[http://code.tutsplus.com/tutorials/a-guide-to-overriding-parent-theme-functions-in-your-child-theme--cms-22623][removing functions in wordpress]]
** Removing functions from from hooks via remove/add_action
** Define the function in your child theme's function.php file
Your child theme is loaded just before the parent theme, and if the parent theme is written properly, then the child's functions will override the parent's.

The parent's function has to be written like this:

# this is not C code, but I just wanted to get syntax highlighting to work
#+BEGIN_SRC C
  if ( ! function_exists( 'storefront_footer_widgets' ) ) {
     /* some content here */
   }
#+END_SRC

So if your child theme's function.php has the function

#+BEGIN_SRC c
  function storefront_footer_widgets () {
  /* some code here */
  }
#+END_SRC

Then your child theme's function will overwrite the parent's function.  Cool eh?
2085 Puget Drive
West Lafayette, * wordpress template hierarchy
# https://developer.wordpress.org/themes/basics/template-hierarchy/

When wordpress views a specific webpage, it selects in page that is the highest in the hierarchy.
* The default "20" themes and _s (Underscores) theme
wordpress wrote "20 14", "20 23", "20 12", and "20 10", for developers to study!  I can learn how wordpress builds themes by studying those themes.

Developers should use the Underscores theme as a base for developing new themes.  It is a starter theme.  I can learn more about it here: http://underscores.me/
* [[https://developer.wordpress.org/themes/getting-started/][Theme Handbook]]  I am more or less copying the theme handbook verbatium
** Theme basics
I'm going to learn theme files and post types.  I'll also learn about the loop, which Well it sureis what pulls information out of the wordpress database.
** Template Files
- Page Templates /only/ to specific pages, groups of pages, or a page section.  Page Templates intended to change a page/s look and feel. \\
  So a page template is like a liquid file for shoppify.  A page template is like a the metal structure that encases a dam before workers pour concrete in the holes to fill it up.  The structure that builds a dam marks sections where concrete will be filled.  In this case the structure is the template and the concrete is the data that is filled.

- Template tags are php functions that expand during the php execution. ie:

  #+BEGIN_SRC
  <?php
  echo 'the_title()';
  echo 'the_content()';
  ?>
  #+END_SRC

  Template tags are like the titles of the temp workers at the dam.  There's a supervisor (Jim), concrete pourer (Rick), structural specialist (Don), etc.  During construction of the dam, you refer to these people as supervisor or boss, but when it's time to get execute processing of payment (executing the php code), then you have to expand the supervisor's name to "John Fullname".

  - "Template hierarchy" is the chronological list that wordpress goes through to determine which theme template files to use.
* Ajax links
  [[http://www.fiftyfoureleven.com/resources/programming/xmlhttprequest/examples][Ajax Links]]
  [[http://codex.wordpress.org/Function_Reference/WP_Ajax_Response][Ajax Response]]
  https://premium.wpmudev.org/blog/load-posts-ajax/

* for my test of wordpress I should know important wordpress glossary words that are found here [[http://codex.wordpress.org/Glossary][Glossary]]
* I can generate cool wordpress stuff via this site: https://generatewp.com/
* STARTED Building a test that I need to pass to "learn" wordpress
:LOGBOOK:
CLOCK: [2016-02-17 Wed 09:21]--[2016-02-17 Wed 09:28] =>  0:07
CLOCK: [2016-02-16 Tue 17:08]--[2016-02-16 Tue 17:45] =>  0:37
CLOCK: [2016-02-16 Tue 16:26]--[2016-02-16 Tue 16:52] =>  0:26
CLOCK: [2016-02-16 Tue 15:28]--[2016-02-16 Tue 16:03] =>  0:35
CLOCK: [2016-02-12 Fri 09:21]--[2016-02-12 Fri 09:29] =>  0:08
CLOCK: [2016-02-11 Thu 13:37]--[2016-02-11 Thu 13:46] =>  0:09
CLOCK: [2016-02-11 Thu 10:36]--[2016-02-11 Thu 11:55] =>  1:19
CLOCK: [2016-02-11 Thu 10:02]--[2016-02-11 Thu 10:06] =>  0:04
CLOCK: [2016-02-10 Wed 15:48]--[2016-02-10 Wed 15:58] =>  0:10
CLOCK: [2016-02-10 Wed 15:24]--[2016-02-10 Wed 15:29] =>  0:05
CLOCK: [2016-02-10 Wed 14:29]--[2016-02-10 Wed 15:22] =>  0:53
CLOCK: [2016-02-10 Wed 13:59]--[2016-02-10 Wed 14:05] =>  0:06
:END:
** DONE What's the difference between a taxonomy and a custom post type?
CLOSED: [2016-12-13 Tue 13:35]
:LOGBOOK:
- State "DONE"       from              [2016-12-13 Tue 13:35]
:END:
A taxonomy is a way of grouping things.  categories and tags are taxonomies.

A post is content that a user inserts into wordpress.

The default post type is just the content that displays on every page.  So when a user browses the home page, the Loop queries the database for the post that is supposed to be on the home page.  That particular post is displayed.
** How do I add a new page templates?
** How do I use the loop? to implement pagination? to add various new content to a page? ie 5 posts
** Widgets included with Wordpress are what?
** What can widgets do?
** What can plugins do?
** can I use Ajax?  How?
** DONE what's the wordpress version of a custom directory?
CLOSED: [2016-12-13 Tue 13:35]
:LOGBOOK:
- State "DONE"       from              [2016-12-13 Tue 13:35]
:END:
   A custom post type.
** DONE What's the wordpress version of a lister?
CLOSED: [2016-12-13 Tue 13:35]
:LOGBOOK:
- State "DONE"       from              [2016-12-13 Tue 13:35]
:END:
   A php query that uses the loop.
** DONE What's the wordpress version of a default detail layout?
CLOSED: [2016-12-13 Tue 13:35]
:LOGBOOK:
- State "DONE"       from              [2016-12-13 Tue 13:35]
:END:
   A page template
** DONE What's wordpresses's vocab word for page layouts?
CLOSED: [2016-12-13 Tue 13:35]
:LOGBOOK:
- State "DONE"       from              [2016-12-13 Tue 13:35]
:END:
   A page template
** How can I embed a form on wordpress?
** How do I send email w/ wordpress?
** How do I over-write a parent theme's function?
   - How do you nullify a parent theme's function?
     You can make the parent theme's function do nothing. Ie: your child theme's functions.php has this:

     #+BEGIN_SRC
     /* make the woocommerce_breadcrumb do nothing */
     function woocommerce_breadcrumb () {

     }
     #+END_SRC
   - How do you how do I hook in a function to run after a specified event?
   - How do a remove a parent-theme's function in the child theme?
** I should know at least 30% or the common action hooks and filter hooks that wordpress uses:
http://codex.wordpress.org/Plugin_API/Action_Reference
http://codex.wordpress.org/Plugin_API/Filter_Reference
** Understand wordpress conceptually
*** know 95% of wordpress' vocab found here:
[[https://codex.wordpress.org/Glossary][in the glossary,]]  and in the [[https://codex.wordpress.org/WordPress_Semantics][Semantics]]
**** Action
An action is (it is also a type of hook) an event that happens on the server side when a client requests a page.  wp_loaded (when wordpress is fully loaded), shutdown (php execution is about to end), get_header (is the event that happens to load the top part of your webpage).

- wp_head/wp_footer are the actions that load in the header and the footer
- init is the action that is performed before any headers are sent to the client.  So If you wanted to redirect
  a user to a different page, you could do this here:
- wp_enqueue_scripts is the event that adds js files to your sites
- post_class & body_class are actions that let you customize the classes that your post and body have.  This
  makes it nice to give certain pages various css styles to affect how things look.
**** Capabilities
The permission to perform some task.  Some users of a wordpress site have certain abilities to perform some tasks, that others lack.  So a newbie admin might not have the ability to edit the home page
**** CGI:
 Common Gateway Interface specifies how the server can communicate with the client (web browser).  Forms use this.
**** Content
Is the information stored in a post.  It can be text, images, video?
**** Deprecated
these functions or variables will soon be obsolete or are already
**** DOM
document object model is a standard that allows programmers to to dynamically and programatically access HTML on the page
**** Filter
A filter is a php function that associates itself with an action (a php function that runs at a certain point).   It can filter some existing action to do anything else.  ie: A /custom filter/ (add_filter ()), replaces code from
an action.  This is called "hooking."

- the_content
  You can filter (replace/update/remove) any of the stuff in the content with this.
- the_excerpt
  You can filter (replace/update/remove) any of the stuff in the except with this filter.
**** Gallery
Each post can have an associated gallery!  When you are editing a post, you can click on the gallery tab!  This lets you upload lots of images to your post!  When you have have more than 1 image in your gallery, the bottom of
the gallery tab includes a shortcode that you can insert to display the photos.
**** Hook
This lets you run your own code at certain events.  A hook can either be an action or a filter.
A hook lets you change all sorts of things about wordpress w/o diving into the core files, which is very nice.
A list of all hooks is available here:
http://adambrown.info/p/wp_hooks/version/4.1
***** An Action hook (also called an action)
Actions do things.
ie: add content, perform some calculation, go to the mall, you name it.
An action hook lets you specify that your code should run at a specific point.
It does not change existing content.

An action is like drinking dirty water.  You do something: ie drink dirty water.
***** A filter hook (also called a filter)
Filters change things.

A filter hook lets you use a php function to do something to data before it is displayed.  ie:

#+BEGIN_SRC
$title = apply_filters('wp_title', $title, $sep, $seplocation);

#+END_SRC

This above is a code snippet from wordpress core that lets you do something to the title before it is
rendered on the page, like truncating it if the title is too long, etc.

A filter changes things.  So a filter is like filtering water.  You don't get changed.  The water doesn't really go anyplace special.  It just gets filtered.
** what is nonce?
It is a number used once.  It part of an authentication method.
** learn how to use REST [/]
*** to display excerpts and titles of posts
*** to implement pagination
** DONE hooks (actions vs. filters)
CLOSED: [2016-12-13 Tue 14:04]
:LOGBOOK:
- State "DONE"       from              [2016-12-13 Tue 14:04]
:END:
Both actions and filters are hooks, but they are subtly different.

actions let a developer modify or add to wordpress functionality
filters let a developer alter content before the user sees it
* general security info
https://members.nearlyfreespeech.net/jbranso/support/wordpress_adv

members.nearlyfreespeech.net
Advanced WordPress Configuration - NearlyFreeSpeech.NET Member Interface

Note: Everything on this page assumes that you set up WordPress in accordance with our installation guide and that you are running WordPress on at least Apache 2.4 and PHP 5.4. If any of these assumptions are not correct, the instructions below may fail horribly.
Recommended Plugins
Spam filtering

We recommend Akismet, which comes standard with WordPress. To activate it with WP-CLI:

    wp plugin activate akismet

Additional configuration will be required from the WordPress dashboard "Plugins" section once Akismet is activated; visit that section and you should see a prompt to activate your Akismet account.
Stopping Login Attacks

If you encounter frequent problems with attackers using bulk attempts to attempt to hack their way into your WordPress blog, you may want to consider relocating the login script. This can be accomplished using the sf-move-login plugin.

Before continuing, make sure you are already logged in to the admin interface for your blog.

Install the plugin like any other:

    wp plugin install sf-move-login
    wp plugin activate sf-move-login

Once this is done, there are still two additional steps to make this work.

First, you will need to set the new login link. To do this, go to the "Settings" entry on the WordPress admin panel's sidebar, and then select the "Move Login" entry under that. On the "Move Login" Settings page, enter the new login path (e.g. secretdoor). You can also change the URLs of other common actions from here, but login is by far the most commonly attacked. Click the "Save Changes" button to save your entry.

Next, you must edit your .htaccess file. After you click "Save Changes" the page will reload. Right below that button, the page will list the code you need. Cut and paste the contents of the textbox into your .htaccess file. (Make sure to do this after you save any changes.)

After completing all the steps, this will have the effect of changing your blog's login page from /wp-login.php to /secretdoor. You can (and should) customize secretdoor to whatever you want to use. You may also wish to edit your theme to remove references to the login page, but that is optional.

We recommend that you configure and test this with two different browsers open (e.g. Chrome and Firefox), one that is logged in to the WordPress Dashboard that you can use for the configuration, and one that is not that you can use for testing.

If something doesn't go according to plan and you wind up locked out of your blog, you can add this line to your wp-config.php file to temporarily disable the plugin so you can get logged in:

define( 'SFML_ALLOW_LOGIN_ACCESS', true ); # Do NOT use unless locked out.

Make sure not to add this blindly or leave it in there if needed, as it will defeat the purpose of the plugin.
Blocking Pingbacks

Unfortunately, the "pingback" feature of WordPress can be used to attack other sites. And when attackers use it to attack other sites, it will generally block any legitimate visitors from your site as well. To help keep the Internet (and your own site) safe, you should strongly consider blocking pingbacks.

XML-RPC is used by remote posting tools like mobile apps or third-party sites that post to your blog. If you don't use XML-RPC at all, and most people don't, you can change the permissions of xmlrpc.php to 600 after each update and completely immunize your site from this issue: it will stop your site from being used in attacks, and will prevent would-be attackers from wasting your resources. (Incidentally, this is what we will do if we see your site participating in this type of attack.)

If you do use XML-RPC, you can use a simple plugin that disables the pingback feature but leaves the other functions intact:

    wp plugin install disable-xml-rpc-pingback
    wp plugin activate disable-xml-rpc-pingback

This plugin doesn't need any configuration. It isn't 100% effective like disabling XML-RPC entirely, but it's easy, minimally invasive, and still very effective in greatly reducing resources wasted by would-be attackers.
General security

Try Wordfence. To install and activate it with WP-CLI:

    wp plugin install wordfence
    wp plugin activate wordfence

Additional configuration will be required from the dashboard "Plugins" section once it is activated; visit that section and you should see a prompt to start a tour of the plugin. In the left-hand navigation column, it also adds its own "Wordfence" section from which you can access the tour, tools and configuration options.

In most cases, the defaults are good, but you should check the following options:

    Make sure the options for firewall, login security, Live Traffic View, and automatic scheduled scans are enabled.
    Disable the option to automatically update Wordfence; it won't work. When you get an email that Wordfence (or WordPress itself, or another theme or plugin) needs an update, just pop in and update it with WP-CLI.

Depending on your personal situation and desires, many of the other options can be safely tweaked as well.
Content caching

Content caching can speed up your site and is highly recommended for WordPress site that experiences even occasional bursts of activity. We have tested and recommend Hyper Cache.

First, in the root directory of your WordPress installation (/home/public/ for these instructions), do:

    chmod 775 wp-content/
    chgrp web wp-content/

This plugin also requires switching to "pretty" permalinks; visit Settings > Permalinks in the WordPress dashboard. First choose your format (we like "day and name"), save the change, and then you'll need to add a few lines to an .htaccess file in your blog's root directory. Those lines will be shown at the bottom of the permalinks configuration page; be sure to select all of them before pasting them into your .htaccess file. Once you've set this up, in WP-CLI, do:

    wp plugin install hyper-cache
    wp plugin activate hyper-cache

Then add the following line to your wp-config.php file (at the beginning just under the <?php):

    define( 'WP_CACHE', true );

Then at the command line, in the WordPress base directory do:

    mkdir -p wp-content/cache
    chgrp web wp-content/cache
    chmod 775 wp-content/cache
    mkdir -p wp-content/cache/hyper-cache
    chgrp web wp-content/cache/hyper-cache
    chgrp web wp-content/plugins/hyper-cache/*.php

(The directories might have been created for you already, but if so they'll still need permissions and ownership set.)

After this, you can tweak settings for Hyper Cache from the WordPress dashboard at Settings > Hyper Cache. Be sure to visit their site for more information about how to verify that Hyper Cache is working, and how to customize it.
Receiving update notifications

It's a good idea to set up a way to find out when your WordPress core, plugins and themes have updates available. Here are a few good options:

    WP Updates Notifier: This plugin provides email-based notifications that include detailed information about the update and its expected compatibility with your version of WordPress.
    Pushover Notifications for WordPress: This plugin can send basic notifications to your iOS or Android device. It also requires the purchase of the corresponding Pushover app (iOS, Android).
    You can also subscribe to the WordPress announcement mailing list for information about new releases of the WordPress core and other news.

Securing your WordPress installation
PHP Script Access Limitation

In your wp-content directory, you might want to consider adding the following lines to an .htaccess file to deny access to all .php scripts. This might break a few plugins or themes that use requests that bypass the regular WordPress system, but it will also break most hacking attempts, and should be included in any directory that contains uploaded or cached content. You can paste this (including the last line break) at the command line:

    cat >>.htaccess <<NFSNRULES

    <FilesMatch "\.php">

    	Require all denied

    </FilesMatch>

    NFSNRULES

To reverse this restriction for a subdirectory if needed, switch to that subdirectory and enter:

    cat >>.htaccess <<NFSNRULES

    <FilesMatch "\.php">

    	Require all granted

    </FilesMatch>

    NFSNRULES

Using HTTPS (SSL/TLS)

For WordPress 4.0 and later, no special plugin is required. To configure HTTPS for a WordPress 4.0 or later blog, follow these instructions:

    First, be sure that you've set up and enabled SSL for your site, and that it's working.
    Add the following line to your wp-config.php file:

        if ( $_SERVER[ 'HTTP_X_FORWARDED_PROTO' ] == 'https' ) $_SERVER[ 'HTTPS' ] = 'on';

    In your WordPress dashboard, under Settings > General, update your "WordPress Address (URL)" and "Site Address (URL)" from "http" to "https".

For versions of WordPress prior to 4.0, to allow your WordPress site to be accessed via https, follow these steps:

    First, be sure that you've set up and enabled SSL for your site, and that it's working.
    Install and activate Wordpress HTTPS. From WP-CLI:
        wp plugin install wordpress-https
        wp plugin activate wordpress-https
    Read the Wordpress HTTPS Installation Guide.
    In your WordPress dashboard, under Settings > General, update your "WordPress Address (URL)" and "Site Address (URL)" from "http" to "https".
    (Optional) After everything above is complete and working, you can require that absolutely everything on your site be accessed only via HTTPS by editing the .htaccess file at the root of your site (/home/public) to add these two lines just below "RewriteEngine On:"

        RewriteCond %{HTTP:X-Forwarded-Proto} !https

        RewriteRule .* https://%{HTTP_HOST}%{REQUEST_URI} [L]

Other optimization considerations
Fix wp-cron!

WordPress includes the ability to set posts to appear in the future, and has a couple of other features that are time-sensitive. To implement this functionality, a default WordPress install will call a script called wp-cron.php every time it is accessed.

This behavior causes all sorts of problems, especially on busy sites. Getting called on every hit when there's almost always nothing to do is already wasteful (and "wasteful" on a service like ours that bills for resources is a code word for "unnecessarily expensive"), but the real problem comes when things get out of hand. This program has a history of locking problems, so when a site gets busy it can go crazy and wind up running dozens of times at once trying to figure out if it should be running at all (and the answer is almost always "no"). Say goodbye to your blog performance!

Fixing this issue takes two easy steps.

    Simply add this text to your wp-config.php file:

        define( 'DISABLE_WP_CRON', true );

    Go to the site info panel and add an hourly scheduled task for your site to run wp-cron:

    Tag
        wpcron
    URL or Shell Command
        http://example.nfshost.com/wp-cron.php?doing_wp_cron
    User
        me (not used with URLs)
    Hour
        *
    Day of Week
        *
    Date
        *

    (Replace example.nfshost.com with your site's actual name and adjust the URL as necessary if you didn't install WordPress directly in the public directory.) You don't need to use curl or wget; a scheduled task that has a URL as its command will automatically be treated as a web request.

This approach has the additional benefit that if something weird happens while WordPress is doing its thing internally, you'll be much more likely to be get notified about it in an email message. With the default setup, those error messages may disappear into the void, never to be seen again.
Preventing robots.txt and favicon.ico 404 errors

Requests for these two files can generate many 404 errors if the files don't exist. The way WordPress handles 404 errors is very inefficient, and can result in unnecessary strain on high-traffic sites if either of these files do not exist. You can create these files according to your preferences, but if you don't need them and just want to avoid the performance penalty and resource cost of having requests for them return 404 errors, it's well worth creating two empty files via ssh command line in the root directory of your site:

    touch robots.txt
    touch favicon.ico
* wordpress core APIs
https://make.wordpress.org/core/handbook/best-practices/core-apis/
- widgets
- database
- filesystem
- HTTP
- metadata
- options
- plugin
- quick tags
  Allow a wordpress developer to add additional buttons to the HTML mode of the Wordpress Editor
- shortcode [some shortcode]
  Allow people to add some functionality in a theme
- theme customization
- widgets API
* graph paper press  starter themes
* REST API
adding rest to custom post types
http://v2.wp-api.org/extending/custom-content-types/
https://developer.wordpress.org/rest-api/glossary/
https://developer.wordpress.org/rest-api/

Get a post by a post ID

headturningfitness.com/wp-json/wp/v2/posts/<ID>
* learning wordpress
https://premium.wpmudev.org/blog/35-resources-for-kick-ass-wordpress-developers/?wpcv=b&utm_expid=3606929-93.spVh-aR3SwGklKzL4HJQQg.1&utm_referrer=https%3A%2F%2Fduckduckgo.com%2F
** theme development
https://codex.wordpress.org/Theme_Development
* updating wordpress

Wordpress can update itself if the user running the webserver ownes those files.

I need to figure out what user is running nginx, and then make the html files owned by that person.
* nginx configuration
https://codex.wordpress.org/Nginx#Per_Site_configuration
* how to properly add js and css files
- js
   This is actually a php script...obviously.  Put this in your functions.php file.
   #+BEGIN_SRC js
   function adding_matoma () {
       wp_register_script('matomo', '/wp-content/themes/author-landing-page-child/js/matomo.js', '', '1.1', false);
       wp_enqueue_script ('matomo');
   }
   add_action ('wp_enqueue_scripts', 'adding_matoma');
   #+END_SRC
- css

   This script is obviously a php script.  Put this inside your functions.php file.
   #+BEGIN_SRC js
   function adding_loading_css () {
       wp_register_style ('my_loading_css', '/wp-content/themes/author-landing-page-child/css/my-loading.css', '1.1');
       wp_enqueue_style ('my_loading_css');
   }
   add_action ('wp_enqueue_scripts', 'adding_loading_css');
   #+END_SRC


code:
#+TITLE:X15 EZ Manual
#+AUTHOR:Joshua Branson
#+LATEX_HEADER: \usepackage{lmodern}
#+LATEX_HEADER: \usepackage[QX]{fontenc}
#+OPTIONS: H:10 toc:nil

https://www.gnu.org/software/hurd/microkernel/mach/deficiencies.html
https://git.sceen.net/rbraun/x15.git/


code:
#+TITLE:Yasnippet Cheatsheat
#+AUTHOR:Joshua Branson
#+OPTIONS: H:10

* Embedding elisp inside yasnippets
** Make a yasnippet expand around selected text.
#+BEGIN_EXAMPLE
  # -*- mode: snippet -*-
  # name: <example
  # key: <example
  # --
   `(if (region-active-p)
   (concat "#+BEGIN_EXAMPLE\n" yas-selected-text "#+END_EXAMPLE") )
   (concat "#+BEGIN_EXAMPLE\n$0\n#+END_EXAMPLE" )`
#+END_EXAMPLE


code:
/www/
*.sha1sum
*.vim
*.epoch

repo_name: Ghosta/ghosta

path: .gitignore


code:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>CLIENT_ID</key>
	<string>560632068750-1tk2rrg13j70al9mm4e2eo438p45jdp6.apps.googleusercontent.com</string>
	<key>REVERSED_CLIENT_ID</key>
	<string>com.googleusercontent.apps.560632068750-1tk2rrg13j70al9mm4e2eo438p45jdp6</string>
	<key>PLIST_VERSION</key>
	<string>1</string>
	<key>BUNDLE_ID</key>
	<string>dev.ghosta.dev</string>
</dict>
</plist>