diff --git a/docs/guides/main.rst b/docs/guides/main.rst
index ec4986ec4..f900bbaad 100644
--- a/docs/guides/main.rst
+++ b/docs/guides/main.rst
@@ -96,12 +96,12 @@ Configuring
 -----------
 
 You'll want to set a few basic options before you start using beets. The
-configuration is stored in a text file: on Unix-like OSes, the config file is at
-``~/.beetsconfig``; on Windows, it's at ``%APPDATA%\beetsconfig.ini``. Create
-and edit the appropriate file with your favorite text editor. This file will
-start out empty, but here's good place to start::
+configuration is stored in a text file: on Unix-like OSes, the config file is
+at ``~/.config/beets/config.yaml``; on Windows, it's at
+``%APPDATA%\beets\config.yaml``. Create and edit the appropriate file with your
+favorite text editor. This file will start out empty, but here's good place to
+start::
 
-    [beets]
     directory: ~/music
     library: ~/data/musiclibrary.blb
 
@@ -115,16 +115,27 @@ empty folder using beets' ``import`` command (see below). But you can configure
 beets to behave many other ways:
 
 * Start with a new empty directory, but *move* new music in instead of copying
-  it (saving disk space). Put ``import_move: yes`` in your config file.
+  it (saving disk space). Put this in your config file::
+
+        import:
+            move: yes
+
 * Keep your current directory structure; importing should never move or copy
-  files but instead just correct the tags on music. Put the line ``import_copy:
-  no`` in your config file to disable any copying or renaming. Make sure to
-  point ``directory`` at the place where your music is currently stored.
+  files but instead just correct the tags on music. Put the line ``copy: no``
+  under the ``import:`` heading in your config file to disable any copying or
+  renaming. Make sure to point ``directory`` at the place where your music is
+  currently stored.
+
 * Keep your current directory structure and *do not* correct files' tags: leave
   files completely unmodified on your disk. (Corrected tags will still be stored
   in beets' database, and you can use them to do renaming or tag changes later.)
-  Add both ``import_copy: no`` and ``import_write: no`` to your config file to
-  disable renaming and tag-writing.
+  Put this in your config file::
+
+        import:
+            copy: no
+            write: no
+
+  to disable renaming and tag-writing.
 
 There are approximately six million other configuration options you can set
 here, including the directory and file naming scheme. See
@@ -151,7 +162,7 @@ this::
 
 (Note that by default, this command will *copy music into the directory you
 specified above*. If you want to use your current directory structure, set the
-``import_copy`` config option.) To take the fast,
+``import.copy`` config option.) To take the fast,
 un-autotagged path, just say::
 
     $ beet import -A /my/huge/mp3/library
diff --git a/docs/plugins/bpd.rst b/docs/plugins/bpd.rst
index 95bcd1e9a..4f67dd6f6 100644
--- a/docs/plugins/bpd.rst
+++ b/docs/plugins/bpd.rst
@@ -35,12 +35,9 @@ with its Python bindings) on your system.
 Using and Configuring
 ---------------------
 
-BPD is a plugin for beets. It comes with beets, but it's disabled by default. To
-enable it, you'll need to edit your ``.beetsconfig`` file and add the line
-``plugins: bpd``. Like so::
-
-    [beets]
-    plugins: bpd
+BPD is a plugin for beets. It comes with beets, but it's disabled by default.
+To enable it, you'll need to edit your :doc:`configuration file
+</reference/config>` and add ``bpd`` to your ``plugins:`` line.
 
 Then, you can run BPD by invoking::
 
@@ -66,14 +63,14 @@ the client can just as easily on a different computer from the server as it can
 be run locally. Control your music from your laptop (or phone!) while it plays
 on your headless server box. Rad!
 
-To configure the BPD server, add a ``[bpd]`` section to your ``.beetsconfig``
+To configure the BPD server, add a ``bpd:`` section to your ``config.yaml``
 file. The configuration values, which are pretty self-explanatory, are ``host``,
 ``port``, and ``password``. Here's an example::
 
-    [bpd]
-    host: 127.0.0.1
-    port: 6600
-    password: seekrit
+    bpd:
+        host: 127.0.0.1
+        port: 6600
+        password: seekrit
 
 Implementation Notes
 --------------------
diff --git a/docs/plugins/chroma.rst b/docs/plugins/chroma.rst
index 1907e2fde..b24a4816a 100644
--- a/docs/plugins/chroma.rst
+++ b/docs/plugins/chroma.rst
@@ -74,14 +74,9 @@ Using
 -----
 
 Once you have all the dependencies sorted out, you can enable fingerprinting by
-editing your :doc:`/reference/config`. Put ``chroma`` on your ``plugins:``
-line. Your config file should contain something like this::
-
-    [beets]
-    plugins: chroma
-
-With that, beets will use fingerprinting the next time you run ``beet import``.
-
+editing your :doc:`configuration file </reference/config>`. Put ``chroma`` on
+your ``plugins:`` line. With that, beets will use fingerprinting the next time
+you run ``beet import``.
 
 .. _submitfp:
 
@@ -91,11 +86,11 @@ Submitting Fingerprints
 You can help expand the `Acoustid`_ database by submitting fingerprints for the
 music in your collection. To do this, first `get an API key`_ from the Acoustid
 service. Just use an OpenID or MusicBrainz account to log in and you'll get a
-short token string. Then, add the key to your :doc:`/reference/config` as the
+short token string. Then, add the key to your ``config.yaml`` as the
 value ``apikey`` in a section called ``acoustid`` like so::
 
-    [acoustid]
-    apikey=AbCd1234
+    acoustid:
+        apikey: AbCd1234
 
 Then, run ``beet submit``. (You can also provide a query to submit a subset of
 your library.) The command will use stored fingerprints if they're available;
diff --git a/docs/plugins/convert.rst b/docs/plugins/convert.rst
index 37345bb75..1295b6a04 100644
--- a/docs/plugins/convert.rst
+++ b/docs/plugins/convert.rst
@@ -17,8 +17,8 @@ To transcode music, this plugin requires the ``ffmpeg`` command-line
 tool. If its executable is in your path, it  will be found automatically
 by the plugin. Otherwise, configure the plugin to locate the executable::
 
-    [convert]
-    ffmpeg: /usr/bin/ffmpeg
+    convert:
+        ffmpeg: /usr/bin/ffmpeg
 
 Usage
 -----
@@ -35,7 +35,7 @@ Configuration
 -------------
 
 The plugin offers several configuration options, all of which live under the
-``[convert]`` section:
+``convert:`` section:
 
 * ``dest`` sets the directory the files will be converted (or copied) to.
   A destination is required---you either have to provide it in the config file
@@ -57,9 +57,9 @@ The plugin offers several configuration options, all of which live under the
 
 Here's an example configuration::
 
-    [convert]
-    embed: false
-    max_bitrate: 200
-    opts: -aq 4
-    dest: /home/user/MusicForPhone
-    threads: 4
+    convert:
+        embed: false
+        max_bitrate: 200
+        opts: -aq 4
+        dest: /home/user/MusicForPhone
+        threads: 4
diff --git a/docs/plugins/echonest_tempo.rst b/docs/plugins/echonest_tempo.rst
index 0b1df07ee..d30a73154 100644
--- a/docs/plugins/echonest_tempo.rst
+++ b/docs/plugins/echonest_tempo.rst
@@ -25,30 +25,29 @@ Configuring
 
 Beets includes its own Echo Nest API key, but you can `apply for your own`_ for
 free from the EchoNest.  To specify your own API key, add the key to your
-:doc:`/reference/config` as the value ``apikey`` in a section called
-``echonest_tempo`` like so::
+:doc:`configuration file </reference/config>` as the value for ``apikey`` under
+the key ``echonest_tempo`` like so::
 
-    [echonest_tempo]
-    apikey=YOUR_API_KEY
+    echonest_temo:
+        apikey: YOUR_API_KEY
 
 In addition, the ``autofetch`` config option lets you disable automatic tempo
-fetching during import. To do so, add this to your ``~/.beetsconfig``::
+fetching during import. To do so, add this to your ``config.yaml``::
 
-    [echonest_tempo]
-    autofetch: no
+    echonest_tempo:
+        auto: no
 
 .. _apply for your own: http://developer.echonest.com/account/register
 
 Fetch Tempo During Import
 -------------------------
 
-To automatically fetch the tempo for songs you import, just enable the plugin 
+To automatically fetch the tempo for songs you import, just enable the plugin
 by putting ``echonest_tempo`` on your config file's ``plugins`` line (see
-:doc:`/plugins/index`), along with adding your EchoNest API key to your
-``~/.beetsconfig``.  When importing new files, beets will now fetch the 
-tempo for files that don't already have them. The bpm field will be stored in 
-the beets database. If the ``import_write`` config option is on, then the 
-tempo will also be written to the files' tags.
+:doc:`/plugins/index`). When importing new files, beets will now fetch the
+tempo for files that don't already have them. The bpm field will be stored in
+the beets database. If the ``import.write`` config option is on, then the tempo
+will also be written to the files' tags.
 
 This behavior can be disabled with the ``autofetch`` config option (see below).
 
@@ -61,7 +60,7 @@ items that match a query (see :doc:`/reference/query`). For example,
 appropriate Magnetic Fields song, ``beet tempo magnetic fields`` will get 
 tempos for all my tracks by that band, and ``beet tempo`` will get tempos for 
 my entire library. The tempos will be added to the beets database and, if 
-``import_write`` is on, embedded into files' metadata.
+``import.write`` is on, embedded into files' metadata.
 
 The ``-p`` option to the ``tempo`` command makes it print tempos out to the
 console so you can view the fetched (or previously-stored) tempos.
diff --git a/docs/plugins/embedart.rst b/docs/plugins/embedart.rst
index 46b66913f..9ce3f7257 100644
--- a/docs/plugins/embedart.rst
+++ b/docs/plugins/embedart.rst
@@ -17,7 +17,7 @@ plugin (see :doc:`/plugins/index`). You'll also want to enable the
 :doc:`/plugins/fetchart` to obtain the images to be embedded. Art will be
 embedded after each album is added to the library.
 
-This behavior can be disabled with the ``autoembed`` config option (see below).
+This behavior can be disabled with the ``auto`` config option (see below).
 
 Manually Embedding and Extracting Art
 -------------------------------------
@@ -40,11 +40,11 @@ embedded album art:
 Configuring
 -----------
 
-``autoembed`` option  lets you disable automatic album art embedding. 
-To do so, add this to your ``~/.beetsconfig``::
+The ``auto`` option  lets you disable automatic album art embedding. 
+To do so, add this to your ``config.yaml``::
 
-    [embedart]
-    autoembed: no
+    embedart:
+        auto: no
 
 A maximum image width can be configured as ``maxwidth`` to downscale images
 before embedding them (the original image file is not altered). The resize
diff --git a/docs/plugins/fetchart.rst b/docs/plugins/fetchart.rst
index 518c1eac3..7af1cd1c1 100644
--- a/docs/plugins/fetchart.rst
+++ b/docs/plugins/fetchart.rst
@@ -19,8 +19,8 @@ the :ref:`art-filename` config option.
 To disable automatic art downloading, just put this in your configuration
 file::
 
-    [fetchart]
-    autofetch: no
+    fetchart:
+        auto: no
 
 Manually Fetching Album Art
 ---------------------------
diff --git a/docs/plugins/fuzzy_search.rst b/docs/plugins/fuzzy_search.rst
index 9c9720af9..64ddf8edf 100644
--- a/docs/plugins/fuzzy_search.rst
+++ b/docs/plugins/fuzzy_search.rst
@@ -19,7 +19,7 @@ The ``-t NUMBER`` option lets you specify how precise the fuzzy match has to be
 (default is 0.7). To make a fuzzier search, try ``beet fuzzy -t 0.5 Varoeldur``.
 A value of ``1`` will show only perfect matches and a value of ``0`` will match everything.
 
-The default threshold can also be set from the config file.::
+The default threshold can also be set in the config file::
 
-    [fuzzy]
-    threshold: 0.8
+    fuzzy:
+        threshold: 0.8
diff --git a/docs/plugins/ihate.rst b/docs/plugins/ihate.rst
index 0d8e9e3b4..7fc9f0050 100644
--- a/docs/plugins/ihate.rst
+++ b/docs/plugins/ihate.rst
@@ -8,28 +8,21 @@ groups: warn and skip. The skip group is checked first. Whitelist overrides any
 other patterns.
 
 To use the plugin, enable it by including ``ihate`` in the ``plugins`` line of
-your beets config::
+your beets config. Then, add an ``ihate:`` section to your configuration file::
 
-    [beets]
-    plugins = ihate
-
-You need to configure the plugin before use, so add the following section into 
-your config file and adjust it to your needs::
-
-    [ihate]
-    # you will be warned about these suspicious genres/artists (regexps):
-    warn_genre=rnb soul power\smetal
-    warn_artist=bad\band another\sbad\sband
-    warn_album=tribute\sto
-    # if you don't like a genre in general, but accept some band playing it,
-    # add exceptions here:
-    warn_whitelist=hate\sexception
-    # never import any of this:
-    skip_genre=russian\srock polka
-    skip_artist=manowar
-    skip_album=christmas
-    # but import this:
-    skip_whitelist=
+    ihate:
+        # you will be warned about these suspicious genres/artists (regexps):
+        warn_genre=rnb soul power\smetal
+        warn_artist=bad\band another\sbad\sband
+        warn_album=tribute\sto
+        # if you don't like a genre in general, but accept some band playing it,
+        # add exceptions here:
+        warn_whitelist=hate\sexception
+        # never import any of this:
+        skip_genre=russian\srock polka
+        skip_artist=manowar
+        skip_album=christmas
+        # but import this:
+        skip_whitelist=
 
 Note: The plugin will trust your decision in 'as-is' mode.
-  
\ No newline at end of file
diff --git a/docs/plugins/importfeeds.rst b/docs/plugins/importfeeds.rst
index dcc2cf557..6e0662b4e 100644
--- a/docs/plugins/importfeeds.rst
+++ b/docs/plugins/importfeeds.rst
@@ -4,21 +4,20 @@ ImportFeeds Plugin
 The ``importfeeds`` plugin helps you keep track of newly imported music in your library.
 
 To use the plugin, just put ``importfeeds`` on the ``plugins`` line in your
-:doc:`/reference/config`::
+:doc:`configuration file </reference/config>`. Then set a few options under the
+``importfeeds:`` section in the config file.
 
-    [beets]
-    plugins: importfeeds
-
-The ``feeds_dir`` parameter can be set to specify another folder than the default library directory.
-Three different types of outputs coexist, specify the ones you want to use by setting the ``feeds_formats`` parameter: 
+The ``feeds_dir`` configuration option can be set to specify another folder
+than the default library directory. Three different types of outputs coexist,
+specify the ones you want to use by setting the ``feeds_formats`` parameter: 
 
 - ``m3u``: catalog the imports in a centralized playlist. By default, the playlist is named ``imported.m3u``. To use a different file, just set the ``m3u_name`` parameter inside the ``importfeeds`` config section.
 - ``m3u_multi``: create a new playlist for each import (uniquely named by appending the date and track/album name). 
 - ``link``: create a symlink for each imported item. This is the recommended setting to propagate beets imports to your iTunes library: just drag and drop the ``feeds_dir`` folder on the iTunes dock icon.
 
-An example of ``importfeeds`` configuration::
+Here's an example configuration for this plugin::
 
-    [importfeeds]
-    feeds_formats: m3u link
-    feeds_dir: ~/imports/
-    m3u_name: newfiles.m3u
+    importfeeds:
+        feeds_formats: m3u link
+        feeds_dir: ~/imports/
+        m3u_name: newfiles.m3u
diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst
index 1fd497a81..50a073bdd 100644
--- a/docs/plugins/index.rst
+++ b/docs/plugins/index.rst
@@ -14,15 +14,17 @@ To use a plugin, you have two options:
   just means the plugin has to be installed on your system (e.g., with a
   `setup.py` script or a command like `pip` or `easy_install`).
 
-* Set the `pythonpath` config variable to point to the directory containing the
+* Set the `pluginpath` config variable to point to the directory containing the
   plugin. (See :doc:`/reference/cli`.)
 
-Then, set the `plugins` option in your `~/.beetsconfig` file, like so::
+Then, set the `plugins` option in your `config.yaml` file, like so::
 
-    [beets]
-    plugins = mygreatplugin someotherplugin
+    plugins: mygreatplugin someotherplugin
 
-The value for `plugins` should be a space-separated list of plugin module names.
+The value for `plugins` can be a space-separated list of plugin names or
+a YAML list like ``[foo, bar]``.
+
+You can see which plugins are currently enabled by typing ``beet version``.
 
 .. _included-plugins:
 
diff --git a/docs/plugins/inline.rst b/docs/plugins/inline.rst
index 395c86600..02d5510d3 100644
--- a/docs/plugins/inline.rst
+++ b/docs/plugins/inline.rst
@@ -7,26 +7,22 @@ file and refer to them from your template strings in the ``[paths]`` section
 (see :doc:`/reference/config/`).
 
 To use inline field definitions, first enable the plugin by putting ``inline``
-on your ``plugins`` line, like so::
-
-    [beets]
-    plugins: inline
-
-Then, make a ``[pathfields]`` section in your config file. In this section,
-every line defines a new template field; the key is the name of the field
-(you'll use the name to refer to the field in your templates) and the value is a
-Python expression. The expression has all of a track's fields in scope, so you
-can refer to any normal attributes (such as ``artist`` or ``title``) as Python
+on your ``plugins`` line in your configuration file. Then, make a
+``pathfields:`` block in your config file. Under this key, every line
+defines a new template field; the key is the name of the field (you'll use the
+name to refer to the field in your templates) and the value is a Python
+expression. The expression has all of a track's fields in scope, so you can
+refer to any normal attributes (such as ``artist`` or ``title``) as Python
 variables. Here are a couple of examples::
 
-    [pathfields]
-    initial: albumartist[0].upper() + u'.'
-    disc_and_track: u'%02i.%02i' % (disc, track) if
-                    disctotal > 1 else u'%02i' % (track)
+    pathfields:
+        initial: albumartist[0].upper() + u'.'
+        disc_and_track: u'%02i.%02i' % (disc, track) if
+                        disctotal > 1 else u'%02i' % (track)
 
-(Note that the config file's syntax allows newlines in values if the subsequent
-lines are indented.) These examples define ``$initial`` and
+Note that YAML syntax allows newlines in values if the subsequent
+lines are indented. These examples define ``$initial`` and
 ``$disc_and_track`` fields that can be referenced in path templates like so::
 
-    [paths]
-    default: $initial/$artist/$album%aunique{}/$disc_and_track $title
+    paths:
+        default: $initial/$artist/$album%aunique{}/$disc_and_track $title
diff --git a/docs/plugins/lastgenre.rst b/docs/plugins/lastgenre.rst
index aad040076..b8df9eed6 100644
--- a/docs/plugins/lastgenre.rst
+++ b/docs/plugins/lastgenre.rst
@@ -16,19 +16,16 @@ The plugin requires `pylast`_, which you can install using `pip`_ by typing::
     pip install pylast
 
 After you have pylast installed, enable the plugin by putting ``lastgenre`` on
-your ``plugins`` line in :doc:`/reference/config`, like so::
+your ``plugins`` line in :doc:`config file </reference/config>`.
 
-    [beets]
-    plugins: lastgenre
+The plugin chooses genres based on a *whitelist*, meaning that only certain
+tags can be considered genres. This way, tags like "my favorite music" or "seen
+live" won't be considered genres. The plugin ships with a fairly extensive
+internal whitelist, but you can set your own in the config file using the
+``whitelist`` configuration value::
 
-The plugin chooses genres based on a *whitelist*, meaning that only certain tags
-can be considered genres. This way, tags like "my favorite music" or "seen live"
-won't be considered genres. The plugin ships with a fairly extensive internal
-whitelist, but you can set your own in the config file using the ``whitelist``
-configuration value::
-
-    [lastgenre]
-    whitelist: /path/to/genres.txt
+    lastgenre:
+        whitelist: /path/to/genres.txt
 
 The genre list file should contain one genre per line. Blank lines are ignored.
 For the curious, the default genre list is generated by a `script that scrapes
@@ -38,11 +35,12 @@ Wikipedia`_.
 .. _pylast: http://code.google.com/p/pylast/
 .. _script that scrapes Wikipedia: https://gist.github.com/1241307
 
-If no genre is found, you have the opportunity to specify a fixed string instead
-(declare *fallback_str* with no value to blank the genre field)::
+If no genre is found, the file will be left unchanged. To instead specify a
+fallback genre, use the ``fallback`` configuration option. You can, of
+course, use the empty string as a fallback, like so::
 
-    [lastgenre]
-    fallback_str:
+    lastgenre:
+        fallback: ''
 
 
 Canonicalization
@@ -56,12 +54,12 @@ leaves of the tree represent the most specific genres.
 To enable canonicalization, first install the `pyyaml`_ module (``pip install
 pyyaml``). Then set the ``canonical`` configuration value::
 
-    [lastgenre]
-    canonical:
+    lastgenre:
+        canonical: ''
 
-Leaving this value blank will use a built-in canonicalization tree. You can also
-set it to a path, just like the ``whitelist`` config value, to use your own
-tree.
+Setting this value to the empty string will use a built-in canonicalization
+tree. You can also set it to a path, just like the ``whitelist`` config value,
+to use your own tree.
 
 .. _YAML: http://www.yaml.org/
 .. _pyyaml: http://pyyaml.org/
diff --git a/docs/plugins/lyrics.rst b/docs/plugins/lyrics.rst
index 417729fb1..e6a348133 100644
--- a/docs/plugins/lyrics.rst
+++ b/docs/plugins/lyrics.rst
@@ -14,10 +14,10 @@ To automatically fetch lyrics for songs you import, just enable the plugin by
 putting ``lyrics`` on your config file's ``plugins`` line (see
 :doc:`/plugins/index`).  When importing new files, beets will now fetch lyrics
 for files that don't already have them. The lyrics will be stored in the beets
-database. If the ``import_write`` config option is on, then the lyrics will also
+database. If the ``import.write`` config option is on, then the lyrics will also
 be written to the files' tags.
 
-This behavior can be disabled with the ``autofetch`` config option (see below).
+This behavior can be disabled with the ``auto`` config option (see below).
 
 Fetching Lyrics Manually
 ------------------------
@@ -27,7 +27,7 @@ match a query (see :doc:`/reference/query`). For example, ``beet lyrics magnetic
 fields absolutely cuckoo`` will get the lyrics for the appropriate Magnetic
 Fields song, ``beet lyrics magnetic fields`` will get lyrics for all my tracks
 by that band, and ``beet lyrics`` will get lyrics for my entire library. The
-lyrics will be added to the beets database and, if ``import_write`` is on,
+lyrics will be added to the beets database and, if ``import.write`` is on,
 embedded into files' metadata.
 
 The ``-p`` option to the ``lyrics`` command makes it print lyrics out to the
@@ -36,9 +36,9 @@ console so you can view the fetched (or previously-stored) lyrics.
 Configuring
 -----------
 
-The plugin has one configuration option, ``autofetch``, which lets you disable
+The plugin has one configuration option, ``auto``, which lets you disable
 automatic lyrics fetching during import. To do so, add this to your
-``~/.beetsconfig``::
+``config.yaml``::
 
-    [lyrics]
-    autofetch: no
+    lyrics:
+        auto: no
diff --git a/docs/plugins/mbcollection.rst b/docs/plugins/mbcollection.rst
index 579cb2d2a..f5a6df130 100644
--- a/docs/plugins/mbcollection.rst
+++ b/docs/plugins/mbcollection.rst
@@ -8,11 +8,11 @@ maintain your `music collection`_ list there.
 
 To begin, just enable the ``mbcollection`` plugin (see :doc:`/plugins/index`).
 Then, add your MusicBrainz username and password to your
-:doc:`/reference/config` in a ``musicbrainz`` section::
+:doc:`configuration file </reference/config>` under a ``musicbrainz`` section::
 
-    [musicbrainz]
-    user: USERNAME
-    pass: PASSWORD
+    musicbrainz:
+        user: you
+        pass: seekrit
 
 Then, use the ``beet mbupdate`` command to send your albums to MusicBrainz. The
 command automatically adds all of your albums to the first collection it finds.
diff --git a/docs/plugins/mpdupdate.rst b/docs/plugins/mpdupdate.rst
index d9513c8f0..492660106 100644
--- a/docs/plugins/mpdupdate.rst
+++ b/docs/plugins/mpdupdate.rst
@@ -6,18 +6,14 @@ update `MPD`_'s index whenever you change your beets library.
 
 .. _MPD: http://mpd.wikia.com/wiki/Music_Player_Daemon_Wiki
 
-To use it, enable it in your ``.beetsconfig`` by putting ``mpdupdate`` on your ``plugins`` line. Your ``.beetsconfig`` should look like this::
+To use it, enable it in your ``config.yaml`` by putting ``mpdupdate`` on your
+``plugins`` line. Then, you'll probably want to configure the specifics of your
+MPD server. You can do that using an ``mpdupdate:`` section in your
+``config.yaml``, which looks like this::
 
-    [beets]
-    plugins: mpdupdate
-
-Then, you'll probably want to configure the specifics of your MPD server. You
-can do that using an ``[mpdupdate]`` section in your ``.beetsconfig``, which
-looks like this::
-
-    [mpdupdate]
-    host = localhost
-    port = 6600
-    password = seekrit
+    mpdupdate:
+        host: localhost
+        port: 6600
+        password: seekrit
 
 With that all in place, you'll see beets send the "update" command to your MPD server every time you change your beets library.
diff --git a/docs/plugins/replaygain.rst b/docs/plugins/replaygain.rst
index 9b83765f6..dc88cd9a1 100644
--- a/docs/plugins/replaygain.rst
+++ b/docs/plugins/replaygain.rst
@@ -25,8 +25,8 @@ Then enable the ``replaygain`` plugin (see :doc:`/reference/config`). If beets
 doesn't automatically find the ``mp3gain`` or ``aacgain`` executable, you can
 configure the path explicitly like so::
 
-    [replaygain]
-    command: /Applications/MacMP3Gain.app/Contents/Resources/aacgain
+    replaygain:
+        command: /Applications/MacMP3Gain.app/Contents/Resources/aacgain
 
 Usage & Configuration
 ---------------------
@@ -37,10 +37,10 @@ if your player supports these tags, it can use them to do level adjustment.
 
 By default, files that already have ReplayGain tags will not be re-analyzed. If
 you want to analyze *every* file on import, you can set the ``overwrite`` option
-for the plugin in your :doc:`/reference/config`, like so::
+for the plugin in your :doc:`configuration file </reference/config>`, like so::
 
-    [replaygain]
-    overwrite: yes
+    replaygain:
+        overwrite: yes
 
 The target level can be modified to any target dB with the ``targetlevel``
 option (default: 89 dB).
@@ -75,7 +75,7 @@ query (see :doc:`/reference/query`) to indicate which items or albums to
 analyze.
 
 ReplayGain analysis is not fast, so you may want to disable it during import.
-Use the ``automatic`` config option to control this::
+Use the ``auto`` config option to control this::
 
-    [replaygain]
-    automatic: no
+    replaygain:
+        auto: no
diff --git a/docs/plugins/rewrite.rst b/docs/plugins/rewrite.rst
index 7f954d93b..c1bdecb9b 100644
--- a/docs/plugins/rewrite.rst
+++ b/docs/plugins/rewrite.rst
@@ -6,19 +6,15 @@ Specifically, it is intended to let you *canonicalize* names such as artists:
 for example, perhaps you want albums from The Jimi Hendrix Experience to be
 sorted into the same folder as solo Hendrix albums.
 
-To use field rewriting, first enable the plugin by putting ``rewrite``
-on your ``plugins`` line::
+To use field rewriting, first enable the plugin by putting ``rewrite`` on your
+``plugins`` line. Then, make a ``rewrite:`` section in your config file to
+contain your rewrite rules. Each rule consists of a field name, a regular
+expression pattern, and a replacement value. Rules are written ``fieldname
+regex: replacement``. For example, this line implements the Jimi Hendrix
+example above::
 
-    [beets]
-    plugins: rewrite
-
-Then, make a ``[rewrite]`` section in your config file to contain your rewrite
-rules. Each rule consists of a field name, a regular expression pattern, and a
-replacement value. Rules are written ``fieldname regex: replacement``. For
-example, this line implements the Jimi Hendrix example above::
-
-    [rewrite]
-    artist The Jimi Hendrix Experience: Jimi Hendrix
+    rewrite:
+        artist The Jimi Hendrix Experience: Jimi Hendrix
 
 This will make ``$artist`` in your path formats expand to "Jimi Henrix" where it
 would otherwise be "The Jimi Hendrix Experience".
@@ -27,8 +23,8 @@ The pattern is a case-insensitive regular expression. This means you can use
 ordinary regular expression syntax to match multiple artists. For example, you
 might use::
 
-    [rewrite]
-    artist .*jimi hendrix.*: Jimi Hendrix
+    rewrite:
+        artist .*jimi hendrix.*: Jimi Hendrix
 
 As a convenience, the plugin applies patterns for the ``artist`` field to the
 ``albumartist`` field as well. (Otherwise, you would probably want to duplicate
diff --git a/docs/plugins/scrub.rst b/docs/plugins/scrub.rst
index 4c4ca9ff7..f316bdfc4 100644
--- a/docs/plugins/scrub.rst
+++ b/docs/plugins/scrub.rst
@@ -12,11 +12,11 @@ Automatic Scrubbing
 
 To automatically remove files' tags before writing new ones, just
 enable the plugin (see :doc:`/plugins/index`). When importing new files (with
-``import_write`` turned on) or modifying files' tags with the ``beet modify``
+``import.write`` turned on) or modifying files' tags with the ``beet modify``
 command, beets will first strip all types of tags entirely and then write the
 database-tracked metadata to the file.
 
-This behavior can be disabled with the ``autoscrub`` config option (see below).
+This behavior can be disabled with the ``auto`` config option (see below).
 
 Manual Scrubbing
 ----------------
@@ -35,7 +35,7 @@ Configuring
 -----------
 
 The plugin has one configuration option, ``autoscrub``, which lets you disable
-automatic metadata stripping. To do so, add this to your ``~/.beetsconfig``::
+automatic metadata stripping. To do so, add this to your ``config.yaml``::
 
-    [scrub]
-    autoscrub: no
+    scrub:
+        auto: no
diff --git a/docs/plugins/the.rst b/docs/plugins/the.rst
index 7fb1903de..32f9ece33 100644
--- a/docs/plugins/the.rst
+++ b/docs/plugins/the.rst
@@ -11,35 +11,30 @@ regexp patterns can be added by user. How it works::
     A Band -> Band, A
     An Orchestra -> Orchestra, An
 
-To use plugin, enable it by including ``the`` into ``plugins`` line of
-your beets config::
+To use plugin, enable it by including ``the`` into ``plugins`` line of your
+beets config. The plugin provides a template function called ``%the`` for use
+in path format expressions::
 
-    [beets]
-    plugins = the
+    paths:
+        default: %the{$albumartist}/($year) $album/$track $title
 
-Plugin provides template function %the, so you can use it on $albumartist or $artist::
+The default configuration moves all English articles to the end of the string,
+but you can override these defaults to make more complex changes::
 
-    [paths]
-    default: %the{$albumartist}/($year) $album/$track $title
+    the:
+        # handle The, default is on
+        the=yes
+        # handle A/An, default is on
+        a=yes
+        # format string, {0} - part w/o article, {1} - article
+        # spaces already trimmed from ends of both parts
+        # default is '{0}, {1}'
+        format={0}, {1}
+        # strip instead of moving to the end, default is off
+        strip=no
+        # custom regexp patterns, separated by space
+        patterns=
 
-Default options are acceptable (moves all English articles to the end), but you
-can add plugin section into config file::
-
-    [the]
-    # handle The, default is on
-    the=yes
-    # handle A/An, default is on
-    a=yes
-    # format string, {0} - part w/o article, {1} - article
-    # spaces already trimmed from ends of both parts
-    # default is '{0}, {1}'
-    format={0}, {1}
-    # strip instead of moving to the end, default is off
-    strip=no
-    # custom regexp patterns, separated by space
-    patterns=
-
-Custom patterns are usual regular expressions. Ignore case is turned on, but ^ is not added 
-automatically, so be careful. Actually, you can swap arguments in format option and write
-regexp to match end of the string, so things will be moved from the end of the string to 
-start.
+Custom patterns are case-insensitive regular expressions. Patterns can be
+matched anywhere in the string (not just the beginning), so use ``^`` if you
+intend to match leading words.
diff --git a/docs/plugins/web.rst b/docs/plugins/web.rst
index 87cb72162..299b75373 100644
--- a/docs/plugins/web.rst
+++ b/docs/plugins/web.rst
@@ -20,7 +20,8 @@ flask``.
 
 .. _Flask: http://flask.pocoo.org/
 
-Put ``plugins=web`` in your ``.beetsconfig`` to enable the plugin.
+Put ``web`` on your ``plugins`` line in your configuration file to enable the
+plugin.
 
 Run the Server
 --------------
@@ -32,14 +33,14 @@ http://localhost:8337/. This is what it looks like:
 
 You can also specify the hostname and port number used by the Web server. These
 can be specified on the command line or in the ``[web]`` section of your
-:doc:`/reference/config`.
+:doc:`configuration file </reference/config>`.
 
 On the command line, use ``beet web [HOSTNAME] [PORT]``. In the config file, use
 something like this::
 
-    [web]
-    host=127.0.0.1
-    port=8888
+    web:
+        host: 127.0.0.1
+        port: 8888
 
 Usage
 -----
diff --git a/docs/plugins/writing.rst b/docs/plugins/writing.rst
index 4d2f83217..2a94bbda6 100644
--- a/docs/plugins/writing.rst
+++ b/docs/plugins/writing.rst
@@ -38,8 +38,8 @@ plugin can do. (Read on!)
 
 To use your new plugin, make sure your ``beetsplug`` directory is in the Python
 path (using ``PYTHONPATH`` or by installing in a `virtualenv`_, for example).
-Then, as described above, edit your ``.beetsconfig`` to include
-``plugins=myawesomeplugin`` (substituting the name of the Python module
+Then, as described above, edit your ``config.yaml`` to include
+``plugins: myawesomeplugin`` (substituting the name of the Python module
 containing your plugin).
 
 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
@@ -75,8 +75,7 @@ your command name.
 
 You'll need to add a function to your command by saying ``mycommand.func =
 myfunction``. This function should take the following parameters: ``lib`` (a
-beets ``Library`` object), ``config`` (a `ConfigParser object`_ containing the
-configuration values), and ``opts`` and ``args`` (command-line options and
+beets ``Library`` object) and ``opts`` and ``args`` (command-line options and
 arguments as returned by `OptionParser.parse_args`_).
 
 .. _ConfigParser object: http://docs.python.org/library/configparser.html
@@ -191,17 +190,28 @@ which have somewhat helpful docstrings.
 Read Configuration Options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Plugins can configure themselves using the ``.beetsconfig`` file. Define a
-``configure`` method on your plugin that takes an ``OptionParser`` object as an
-argument. Then use the ``beets.ui.config_val`` convenience function to access
-values from the config file. Like so::
+Plugins can configure themselves using the ``config.yaml`` file. You can read
+configuration values in two ways. The first is to use `self.config` within
+your plugin class. This gives you a view onto the configuration values in a
+section with the same name as your plugin's module. For example, if your plugin
+is in ``greatplugin.py``, then `self.config` will refer to options under the
+``greatplugin:`` section of the config file.
 
-    class MyPlugin(BeetsPlugin):
-        def configure(self, config):
-            number_of_goats = beets.ui.config_val(config, 'myplug', 'goats', '42')
+For example, if you have a configuration value called "foo", then users can put
+this in their ``config.yaml``::
 
-Try looking at the ``mpdupdate`` plugin (included with beets) for an example of
-real-world use of this API.
+    greatplugin:
+        foo: bar
+
+To access this value, say ``self.config['foo'].get()`` at any point in your
+plugin's code. The `self.config` object is a *view* as defined by the `Confit`_
+library.
+
+.. _Confit: http://confit.readthedocs.org/
+
+If you want to access configuration values *outside* of your plugin's section,
+import the `config` object from the `beets` module. That is, just put ``from
+beets import config`` at the top of your plugin and access values from there.
 
 Add Path Format Functions and Fields
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/plugins/zero.rst b/docs/plugins/zero.rst
index 572f90f7a..19ce28d09 100644
--- a/docs/plugins/zero.rst
+++ b/docs/plugins/zero.rst
@@ -1,29 +1,26 @@
 Zero Plugin
 ===========
 
-The ``zero`` plugin allows you to null fields before writing tags to files.
-Fields can be nulled unconditionally or by pattern match. For example, it can
-be used to strip useless comments like "ripped by" etc or any other stuff you
-hate. Library is not modified.
+The ``zero`` plugin allows you to null fields in files' metadata tags. Fields
+can be nulled unconditionally or conditioned on a pattern match. For example,
+the plugin can strip useless comments like "ripped by MyGreatRipper." This
+plugin only affects files' tags; the beets database is unchanged.
 
-To use plugin, enable it by including ``zero`` into ``plugins`` line of
-your beets config::
-
-    [beets]
-    plugins = zero
-
-To configure the plugin, use a ``[zero]`` section in your configuration file.
-Set ``fields`` to the (whitespace-separated) list of fields to null. You can get
-the list of available fields by running ``beet fields``. To conditionally filter
-a field, use ``field=regexp regexp`` to specify regular expressions.
+To use plugin, enable it by including ``zero`` into ``plugins`` line of your
+configuration file. To configure the plugin, use a ``zero:`` section in your
+configuration file. Set ``fields`` to the (whitespace-separated) list of fields
+to change. You can get the list of available fields by running ``beet fields``.
+To conditionally filter a field, use ``field: [regexp, regexp]`` to specify
+regular expressions.
 
 For example::
 
-    [zero]
-    fields=month day genre comments
-    # Custom regexp patterns for each field, separated by spaces:
-    comments=EAC LAME from.+collection ripped\sby
-    genre=rnb power\smetal
+    zero:
+        fields: month day genre comments
+        comments: [EAC, LAME, from.+collection, 'ripped by']
+        genre: [rnb, 'power metal']
 
-If custom pattern is not defined, field will be nulled unconditionally. Note
-that the plugin currently does not zero fields when importing "as-is".
+If custom pattern is not defined for a given field, the field will be nulled
+unconditionally.
+
+Note that the plugin currently does not zero fields when importing "as-is".
diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst
index cd588ea38..ca718cea5 100644
--- a/docs/reference/cli.rst
+++ b/docs/reference/cli.rst
@@ -24,6 +24,8 @@ Command-Line Interface
 Commands
 --------
 
+.. _import-cmd:
+
 import
 ``````
 ::
@@ -81,7 +83,7 @@ right now; this is something we need to work on. Read the
   To get this to work correctly, you'll need to use an incremental import *every
   time* you run an import on the directory in question---including the first
   time, when no subdirectories will be skipped. So consider enabling the
-  ``import_incremental`` configuration option.
+  ``incremental`` configuration option.
 
 * By default, beets will proceed without asking if it finds a very close
   metadata match. To disable this and have the importer as you every time,
@@ -105,10 +107,10 @@ right now; this is something we need to work on. Read the
     Just point the ``beet import`` command at a directory of files that are
     already catalogged in your library. Beets will automatically detect this
     situation and avoid duplicating any items. In this situation, the "copy
-    files" option (``-c``/``-C`` on the command line or ``import_copy`` in the
+    files" option (``-c``/``-C`` on the command line or ``copy`` in the
     config file) has slightly different behavior: it causes files to be *moved*,
     rather than duplicated, if they're already in your library. (The same is
-    true, of course, if ``import_move`` is enabled.) That is, your directory
+    true, of course, if ``move`` is enabled.) That is, your directory
     structure will be updated to reflect the new tags if copying is enabled; you
     never end up with two copies of the file.
 
diff --git a/docs/reference/config.rst b/docs/reference/config.rst
index 102d7ef2b..265b29d21 100644
--- a/docs/reference/config.rst
+++ b/docs/reference/config.rst
@@ -1,100 +1,62 @@
-.beetsconfig
-============
+Configuration
+=============
 
-The ``beet`` command reads configuration information from ``~/.beetsconfig`` on
-Unix-like OSes (inluding Mac OS X) and ``%APPDATA%\beetsconfig.ini`` on Windows.
-The file is in INI format.
+Beets has an extensive configuration system that lets you customize nearly
+every aspect of its operation. To configure beets, you'll edit a file called
+``config.yaml``. The location of this file depends on your OS:
 
-Options
--------
+* On Unix-like OSes (including OS X), you want ``~/.config/beets/config.yaml``.
+* On Windows, use ``%APPDATA%\beets\config.yaml``. This is usually in a
+  directory like ``C:\Users\You\AppData\Roaming``.
+* On OS X, you can also use ``~/Library/Application Support/beets/config.yaml``
+  if you prefer that over the Unix-like ``~/.config``.
+* If you prefer a different location, set the ``BEETSDIR`` environment variable
+  to a path; beets will then look for a ``config.yaml`` in that directory.
 
-These options are available, all of which must appear under the ``[beets]``
-section header:
+The config file uses `YAML`_ syntax. You can use the full power of YAML, but
+most configuration options are simple key/value pairs. This means your config
+file will look like this::
+
+    option: value
+    another_option: foo
+    bigger_option:
+        key: value
+        foo: bar
+
+If you have questions about more sophisticated syntax, take a look at the
+`YAML`_ documentation.
+
+.. _YAML: http://yaml.org/
+
+Global Options
+--------------
+
+These options control beets' global operation.
 
 library
 ~~~~~~~
 
-Path to the beets library file. Defaults to ``~/.beetsmusic.blb`` on Unix
-and ``%APPDATA\beetsmusic.blb`` on Windows.
+Path to the beets library file. By default, beets will use a file called
+``beetsmusic.blb`` alongside your configuration file.
 
 directory
 ~~~~~~~~~
 
 The directory to which files will be copied/moved when adding them to the
-library. Defaults to ``~/Music``.
+library. Defaults to a folder called ``Music`` in your home directory.
 
-import_write
-~~~~~~~~~~~~
+plugins
+~~~~~~~
 
-Either ``yes`` or ``no``, controlling whether metadata (e.g., ID3) tags are
-written to files when using ``beet import``. Defaults to ``yes``. The ``-w``
-and ``-W`` command-line options override this setting.
+A space-separated list of plugin module names to load. For instance, beets
+includes the BPD plugin for playing music.
 
-import_copy
-~~~~~~~~~~~
-
-Either ``yes`` or ``no``, indicating whether to **copy** files into the
-library directory when using ``beet import``. Defaults to ``yes``.  Can be
-overridden with the ``-c`` and ``-C`` command-line options.
-    
-The option is ignored if ``import_move`` is enabled (i.e., beets can move or
-copy files but it doesn't make sense to do both).
-
-import_move
-~~~~~~~~~~~
-
-Either ``yes`` or ``no``, indicating whether to **move** files into the
-library directory when using ``beet import``.
-Defaults to ``no``. 
-
-The effect is similar to the ``import_copy`` option but you end up with only
-one copy of the imported file. ("Moving" works even across filesystems; if
-necessary, beets will copy and then delete when a simple rename is
-impossible.) Moving files can be risky—it's a good idea to keep a backup in
-case beets doesn't do what you expect with your files.
-
-This option *overrides* ``import_copy``, so enabling it will always move
-(and not copy) files. The ``-c`` switch to the ``beet import`` command,
-however, still takes precedence.
-
-import_resume
-~~~~~~~~~~~~~
-
-Either ``yes``, ``no``, or ``ask``. Controls whether interrupted imports
-should be resumed. "Yes" means that imports are always resumed when
-possible; "no" means resuming is disabled entirely; "ask" (the default)
-means that the user should be prompted when resuming is possible. The ``-p``
-and ``-P`` flags correspond to the "yes" and "no" settings and override this
-option.
-
-import_incremental
-~~~~~~~~~~~~~~~~~~
-
-Either ``yes`` or ``no``, controlling whether imported directories are
-recorded and whether these recorded directories are skipped.  This
-corresponds to the ``-i`` flag to ``beet import``.
-
-import_quiet_fallback
-~~~~~~~~~~~~~~~~~~~~~
-
-Either ``skip`` (default) or ``asis``, specifying what should happen in
-quiet mode (see the ``-q`` flag to ``import``, above) when there is no
-strong recommendation.
-
-import_timid
-~~~~~~~~~~~~
-
-Either ``yes`` or ``no``, controlling whether the importer runs in *timid*
-mode, in which it asks for confirmation on every autotagging match, even the
-ones that seem very close. Defaults to ``no``. The ``-t`` command-line flag
-controls the same setting.
-
-import_log
+pluginpath
 ~~~~~~~~~~
 
-Specifies a filename where the importer's log should be kept.  By default,
-no log is written. This can be overridden with the ``-l`` flag to
-``import``.
+A colon-separated list of directories to search for plugins.  These paths
+are just added to ``sys.path`` before the plugins are loaded. The plugins
+still have to be contained in a ``beetsplug`` namespace package.
 
 ignore
 ~~~~~~
@@ -110,25 +72,24 @@ replace
 
 A set of regular expression/replacement pairs to be applied to all filenames
 created by beets. Typically, these replacements are used to avoid confusing
-problems or errors with the filesystem (for example, leading ``.``
-characters are replaced on Unix and trailing whitespace is removed on
-Windows). To override these substitutions, specify a sequence of
-whitespace-separated terms; the first term is a regular expression and the
-second is a string that should replace anything matching that regex. For
-example, ``replace = [xy] z`` will make beets replace all instances of the
-characters ``x`` or ``y`` with the character ``z``.
+problems or errors with the filesystem (for example, leading dots, which hide
+files on Unix, and trailing whitespace, which is illegal on Windows). To
+override these substitutions, specify a mapping from regular expression to
+replacement strings. For example, ``[xy]: z`` will make beets replace all
+instances of the characters ``x`` or ``y`` with the character ``z``.
 
 If you do change this value, be certain that you include at least enough
 substitutions to avoid causing errors on your operating system. Here are
 the default substitutions used by beets, which are sufficient to avoid
 unexpected behavior on all popular platforms::
 
-    replace = [\\/] _
-                ^\. _
-                [\x00-\x1f] _
-                [<>:"\?\*\|] _
-                \.$ _
-                \s+$ <strip>
+    replace:
+        '[\\/]': _
+        '^\.': _
+        '[\x00-\x1f]': _
+        '[<>:"\?\*\|]': _
+        '\.$': _
+        '\s+$': ''
 
 These substitutions remove forward and back slashes, leading dots, and
 control characters—all of which is a good idea on any OS. The fourth line
@@ -137,20 +98,6 @@ compatibility with Windows-influenced network filesystems like Samba).
 Trailing dots and trailing whitespace, which can cause problems on Windows
 clients, are also removed.
 
-To replace space characters, use the ``\s`` (whitespace) entity::
-    
-    replace = \s _
-                ...
-
-This will avoid using a literal space and thus confusing beets. (``\s`` also
-matches tabs and newlines, but that is probably fine.)
-
-To remove characters entirely, use ``<strip>`` as the replacement. For
-example, to remove all vowels from your filenames::
-
-    replace = [aeiou] <strip>
-                ...
-
 .. _art-filename:
 
 art_filename
@@ -162,19 +109,6 @@ of the syntax available to :doc:`/reference/pathformat`. Defaults to ``cover``
 (i.e., images will be named ``cover.jpg`` or ``cover.png`` and placed in the
 album's directory).
 
-plugins
-~~~~~~~
-
-A space-separated list of plugin module names to load. For instance, beets
-includes the BPD plugin for playing music.
-
-pluginpath
-~~~~~~~~~~
-
-A colon-separated list of directories to search for plugins.  These paths
-are just added to ``sys.path`` before the plugins are loaded. The plugins
-still have to be contained in a ``beetsplug`` namespace package.
-
 threaded
 ~~~~~~~~
 
@@ -231,38 +165,113 @@ If you enable ``per_disc_numbering``, you will likely want to change your
 filenames sort correctly in album directories. For example, you might want to
 use a path format like this::
 
-    [paths]
-    default: $albumartist/$album%aunique{}/$disc-$track $title
+    paths:
+        default: $albumartist/$album%aunique{}/$disc-$track $title
 
-import_delete
-~~~~~~~~~~~~~
+Importer Options
+----------------
 
-Either ``yes`` or ``no``. When enabled in conjunction with ``import_copy``,
-deletes original files after they are copied into your library. Has no
-effect if the importer is in ``import_move`` mode or "leave files in place"
-mode. Defaults to ``no``.
+The options that control the :ref:`import-cmd` command are indented under the
+``import:`` key. For example, you might have a section in your configuration
+file that looks like this::
 
-This option is historical and deprecated: it's almost always more
-appropriate to use ``import_move`` instead.
+    import:
+        write: yes
+        copy: yes
+        resume: no
 
+These options are available in this section:
+
+write
+~~~~~
+
+Either ``yes`` or ``no``, controlling whether metadata (e.g., ID3) tags are
+written to files when using ``beet import``. Defaults to ``yes``. The ``-w``
+and ``-W`` command-line options override this setting.
+
+copy
+~~~~
+
+Either ``yes`` or ``no``, indicating whether to **copy** files into the
+library directory when using ``beet import``. Defaults to ``yes``.  Can be
+overridden with the ``-c`` and ``-C`` command-line options.
+    
+The option is ignored if ``move`` is enabled (i.e., beets can move or
+copy files but it doesn't make sense to do both).
+
+move
+~~~~
+
+Either ``yes`` or ``no``, indicating whether to **move** files into the
+library directory when using ``beet import``.
+Defaults to ``no``. 
+
+The effect is similar to the ``copy`` option but you end up with only
+one copy of the imported file. ("Moving" works even across filesystems; if
+necessary, beets will copy and then delete when a simple rename is
+impossible.) Moving files can be risky—it's a good idea to keep a backup in
+case beets doesn't do what you expect with your files.
+
+This option *overrides* ``copy``, so enabling it will always move
+(and not copy) files. The ``-c`` switch to the ``beet import`` command,
+however, still takes precedence.
+
+resume
+~~~~~~
+
+Either ``yes``, ``no``, or ``ask``. Controls whether interrupted imports
+should be resumed. "Yes" means that imports are always resumed when
+possible; "no" means resuming is disabled entirely; "ask" (the default)
+means that the user should be prompted when resuming is possible. The ``-p``
+and ``-P`` flags correspond to the "yes" and "no" settings and override this
+option.
+
+incremental
+~~~~~~~~~~~
+
+Either ``yes`` or ``no``, controlling whether imported directories are
+recorded and whether these recorded directories are skipped.  This
+corresponds to the ``-i`` flag to ``beet import``.
+
+quiet_fallback
+~~~~~~~~~~~~~~
+
+Either ``skip`` (default) or ``asis``, specifying what should happen in
+quiet mode (see the ``-q`` flag to ``import``, above) when there is no
+strong recommendation.
+
+timid
+~~~~~
+
+Either ``yes`` or ``no``, controlling whether the importer runs in *timid*
+mode, in which it asks for confirmation on every autotagging match, even the
+ones that seem very close. Defaults to ``no``. The ``-t`` command-line flag
+controls the same setting.
+
+log
+~~~
+
+Specifies a filename where the importer's log should be kept.  By default,
+no log is written. This can be overridden with the ``-l`` flag to
+``import``.
 
 .. _path-format-config:
 
 Path Format Configuration
 -------------------------
 
-You can also configure the directory hierarchy beets uses to store music.  These
-settings appear under the ``[paths]`` section (rather than the main ``[beets]``
-section we used above).  Each string is a template string that can refer to
-metadata fields like ``$artist`` or ``$title``. The filename extension is added
-automatically. At the moment, you can specify three special paths: ``default``
-for most releases, ``comp`` for "various artist" releases with no dominant
-artist, and ``singleton`` for non-album tracks. The defaults look like this::
+You can also configure the directory hierarchy beets uses to store music.
+These settings appear under the ``paths:`` key. Each string is a template
+string that can refer to metadata fields like ``$artist`` or ``$title``. The
+filename extension is added automatically. At the moment, you can specify three
+special paths: ``default`` for most releases, ``comp`` for "various artist"
+releases with no dominant artist, and ``singleton`` for non-album tracks. The
+defaults look like this::
 
-    [paths]
-    default: $albumartist/$album%aunique{}/$track $title
-    singleton: Non-Album/$artist/$title
-    comp: Compilations/$album%aunique{}/$track $title
+    paths:
+        default: $albumartist/$album%aunique{}/$track $title
+        singleton: Non-Album/$artist/$title
+        comp: Compilations/$album%aunique{}/$track $title
 
 Note the use of ``$albumartist`` instead of ``$artist``; this ensure that albums
 will be well-organized. For more about these format strings, see
@@ -270,21 +279,19 @@ will be well-organized. For more about these format strings, see
 albums are placed in different directories; see :ref:`aunique` for details.
 
 In addition to ``default``, ``comp``, and ``singleton``, you can condition path
-queries based on beets queries (see :doc:`/reference/query`). There's one catch:
-because the ``:`` character is reserved for separating the query from the
-template string, the ``_`` character is substituted for ``:`` in these queries.
-This means that a config file like this::
+queries based on beets queries (see :doc:`/reference/query`). This means that a
+config file like this::
 
-    [paths]
-    albumtype_soundtrack: Soundtracks/$album/$track $title
+    paths:
+        albumtype:soundtrack: Soundtracks/$album/$track $title
 
 will place soundtrack albums in a separate directory. The queries are tested in
 the order they appear in the configuration file, meaning that if an item matches
 multiple queries, beets will use the path format for the *first* matching query.
 
 Note that the special ``singleton`` and ``comp`` path format conditions are, in
-fact, just shorthand for the explicit queries ``singleton_true`` and
-``comp_true``. In contrast, ``default`` is special and has no query equivalent:
+fact, just shorthand for the explicit queries ``singleton:true`` and
+``comp:true``. In contrast, ``default`` is special and has no query equivalent:
 the ``default`` format is only used if no queries match.
 
 Example
@@ -292,17 +299,17 @@ Example
 
 Here's an example file::
 
-    [beets]
     library: /var/music.blb
     directory: /var/mp3
     path_format: $genre/$artist/$album/$track $title
-    import_copy: yes
-    import_write: yes
-    import_resume: ask
-    import_art: yes
-    import_quiet_fallback: skip
-    import_timid: no
-    import_log: beetslog.txt
+    import:
+        copy: yes
+        write: yes
+        resume: ask
+        art: yes
+        quiet_fallback: skip
+        timid: no
+        log: beetslog.txt
     ignore: .AppleDouble ._* *~ .DS_Store
     art_filename: albumart
     plugins: bpd
@@ -310,27 +317,20 @@ Here's an example file::
     threaded: yes
     color: yes
 
-    [paths]
-    default: $genre/$albumartist/$album/$track $title
-    singleton: Singletons/$artist - $title
-    comp: $genre/$album/$track $title
-    albumtype_soundtrack: Soundtracks/$album/$track $title
+    paths:
+        default: $genre/$albumartist/$album/$track $title
+        singleton: Singletons/$artist - $title
+        comp: $genre/$album/$track $title
+        albumtype:soundtrack: Soundtracks/$album/$track $title
 
-    [bpd]
-    host: 127.0.0.1
-    port: 6600
-    password: seekrit
+    bpd:
+        host: 127.0.0.1
+        port: 6600
+        password: seekrit
 
 (That ``[bpd]`` section configures the optional :doc:`BPD </plugins/bpd>`
 plugin.)
 
-Location
---------
-
-The configuration file is typically located at ``$HOME/.beetsconfig``. If you
-want to store your ``.beetsconfig`` file somewhere else for whatever reason, you
-can specify its path by setting the ``BEETSCONFIG`` environment variable.
-
 .. only:: man
 
     See Also