be2c471397
Add zero-width space because emphasis blocks can't start/end with a comma, an apostrophe or a quote.
165 lines
6.1 KiB
Org Mode
165 lines
6.1 KiB
Org Mode
#+TITLE: Quick start
|
||
#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../css/readtheorg.css" />
|
||
|
||
* Configuration :TOC_4_org:noexport:
|
||
- [[Configuration layers][Configuration layers]]
|
||
- [[Dotfile (.spacemacs)][Dotfile (.spacemacs)]]
|
||
- [[Dotdirectory (~/.spacemacs.d)][Dotdirectory (~/.spacemacs.d)]]
|
||
- [[Learning Spacemacs][Learning Spacemacs]]
|
||
- [[Editing Styles][Editing Styles]]
|
||
- [[The leader keys][The leader keys]]
|
||
- [[Evil-tutor][Evil-tutor]]
|
||
- [[Universal argument][Universal argument]]
|
||
- [[Configuration layers and Package discovery][Configuration layers and Package discovery]]
|
||
- [[Key bindings discovery][Key bindings discovery]]
|
||
- [[Describe functions][Describe functions]]
|
||
- [[How-To's][How-To's]]
|
||
|
||
* Configuration layers
|
||
Spacemacs divides its configuration into self-contained units called
|
||
=configuration layers=. These layers are stacked on top of each other
|
||
to achieve a custom configuration.
|
||
|
||
By default Spacemacs uses a dotfile called =~/.spacemacs= to control which
|
||
layers to load. Within this file you can also configure certain features.
|
||
|
||
A configuration layer is a directory containing at least a =packages.el=
|
||
file which defines and configures packages to be downloaded from Emacs
|
||
package repositories using the =package.el= built-in feature of Emacs.
|
||
|
||
If you already have your own =Emacs= configuration you can move it to your
|
||
own layer.
|
||
|
||
The following command creates a layer in the =private= directory:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
<SPC> : configuration-layer/create-layer RET
|
||
#+END_EXAMPLE
|
||
|
||
Any configuration layers you create must be explicitly loaded in =~/.spacemacs=.
|
||
|
||
Note: For your privacy, the contents of the =private= directory are not
|
||
under source control. See the section on private configuration management in
|
||
the [[file:DOCUMENTATION.org][documentation]].
|
||
|
||
* Dotfile (.spacemacs)
|
||
As mentioned =.spacemacs= controls which configuration layers to load and
|
||
is also a means to customizing Spacemacs.
|
||
|
||
The following command will create a =.spacemacs= file in your home directory:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
<SPC> : dotspacemacs/install RET
|
||
#+END_EXAMPLE
|
||
|
||
To open the installed dotfile:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
<SPC> f e d
|
||
#+END_EXAMPLE
|
||
|
||
To load some configuration layers using the variable
|
||
=dotspacemacs-configuration-layers=:
|
||
|
||
#+BEGIN_SRC elisp
|
||
;; List of configuration layers to load.
|
||
dotspacemacs-configuration-layers '(auto-completion smex)
|
||
#+END_SRC
|
||
|
||
Some configuration layers support configuration variables to expose granular
|
||
control over layer-specific features, [[file:../layers/+source-control/git/README.org][git layer]] being one such example.
|
||
Variables can be directly set within =dotspacemacs-configuration-layers= like so:
|
||
|
||
#+BEGIN_SRC elisp
|
||
;; List of configuration layers to load.
|
||
dotspacemacs-configuration-layers '(auto-completion
|
||
(git :variables
|
||
git-magit-status-fullscreen t)
|
||
smex)
|
||
#+END_SRC
|
||
|
||
At anytime you can apply the changes made to the dotfile or layers
|
||
_without restarting_ Spacemacs by pressing ~SPC f e R~.
|
||
|
||
The [[file:../core/templates/.spacemacs.template][dotfile template]] contain further information about how to customize
|
||
Spacemacs. See the dotfile configuration section of the [[file:DOCUMENTATION.org][documentation]] for
|
||
more details.
|
||
|
||
* Dotdirectory (~/.spacemacs.d)
|
||
Like =Emacs=, Spacemacs initialization can also be contained in an =init.el= file
|
||
in a special directory =~/.spacemacs.d=. The contents of the dotfile should be
|
||
then copied in the =init.el= file.
|
||
|
||
* Learning Spacemacs
|
||
** Editing Styles
|
||
Spacemacs can be used by Vim users or Emacs users by setting the
|
||
=dotspacemacs-editing-style= variable to =vim=, =emacs= or even =hybrid=
|
||
in the dotfile =~/.spacemacs=.
|
||
|
||
** The leader keys
|
||
Spacemacs key bindings use a leader key which is by default bound to
|
||
~SPC~ (space bar) in =vim= or =hybrid= editing styles and ~M-m~ in =emacs=
|
||
style.
|
||
|
||
You can change it by setting the variable =dotspacemacs-leader-key= if
|
||
you use the =vim= style or =dotspacemacs-emacs-leader-key= if you use
|
||
the =emacs= style (these variables must be set in the file =~/.spacemacs=).
|
||
|
||
For simplicity the documentation always refers to the leader key as
|
||
~SPC~.
|
||
|
||
There is secondary leader key called the major-mode leader key which is
|
||
set to ~,~ by default. This key is a shortcut for ~SPC m~
|
||
where all the major-mode specific commands are bound.
|
||
|
||
** Evil-tutor
|
||
If you are willing to learn the Vim key bindings (highly recommended since
|
||
you can benefit from them even in =emacs= style), press ~SPC h T~
|
||
to begin an Evil-adapted Vimtutor.
|
||
|
||
** Universal argument
|
||
In =vim= editing style the universal argument defaults to ~SPC u~
|
||
instead of ~C-u~ because the latter is used to scroll up as in Vim.
|
||
|
||
** Configuration layers and Package discovery
|
||
By using =helm-spacemacs-help= with ~SPC h SPC~ you can quickly search
|
||
for a package and get the name of the layers using it.
|
||
|
||
You can also easily go to the =README.org= of a layer or go to the initialization
|
||
function of a package.
|
||
|
||
** Key bindings discovery
|
||
Thanks to [[https://github.com/justbur/emacs-which-key][which-key]], whenever a prefix command is pressed (like ~SPC~)
|
||
a buffer appears after one second listing the possible keys for this prefix.
|
||
|
||
It is also possible to search for specific key bindings by pressing:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
SPC ?
|
||
#+END_EXAMPLE
|
||
|
||
To narrow the bindings list to those prefixed with =SPC=,
|
||
type a pattern like this regular expression:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
SPC\ b
|
||
#+END_EXAMPLE
|
||
|
||
which would list all =buffer= related bindings. *Note:* You are at the
|
||
/HELM-Descbind/ prompt, the pattern consists of 6 letters: uppercase ~SPC~, a
|
||
backslash, an actual space and a lowercase ~b~.
|
||
|
||
** Describe functions
|
||
=Describe functions= are powerful Emacs introspection commands to get information
|
||
about functions, variables, modes etc. These commands are bound thusly:
|
||
|
||
| Key Binding | Description |
|
||
|-------------+-------------------|
|
||
| ~SPC h d f~ | describe-function |
|
||
| ~SPC h d k~ | describe-key |
|
||
| ~SPC h d m~ | describe-mode |
|
||
| ~SPC h d v~ | describe-variable |
|
||
|
||
* How-To's
|
||
Some quick =how-to's= are compiled in the [[file:FAQ.org::How%20do%20I...][FAQ.org]] file.
|