Add a few more tips and notes to the manual

3 files changed, 30 insertions, 16 deletions

diff --git a/doc/index.md b/doc/index.md
index c748768e..c7943bc6 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -52,9 +52,14 @@ CIDER's basic architecture looks something like this:
 Clojure code gets executed by an nREPL server. CIDER sends requests to the
 server and processes its responses. The server's functionality is augmented by
 additional nREPL middleware, designed specifically to address the needs of an
-interactive development environment like CIDER. Much of the middleware we
-developed for CIDER is editor-agnostic and is being used by other Clojure
-development environments as well (e.g. [vim-fireplace][] & [CCW][]).
+interactive development environment like CIDER.
+
+
+!!! Note
+
+    Much of the middleware we originally
+    developed for CIDER is editor-agnostic and is being used by other Clojure
+    development environments as well (e.g. [vim-fireplace][] & [CCW][]).
 
 CIDER packs plenty of features. Here are some of them (in no particular order):
 
diff --git a/doc/interactive_programming.md b/doc/interactive_programming.md
index 335715c4..d9f171bc 100644
--- a/doc/interactive_programming.md
+++ b/doc/interactive_programming.md
@@ -68,18 +68,23 @@ Here's a list of `cider-mode`'s keybindings:
 `complete-symbol`                             |<kbd>M-TAB</kbd>                     | Complete the symbol at point.
 `cider-quit`                                  |<kbd>C-c C-q</kbd>                   | Quit the current nREPL connection.
 
-There's no need to memorize this list. In any Clojure buffer with `cider-mode`
-active you'll have a CIDER menu available, which lists all the most important
-commands and their keybindings. You can also invoke `C-h f RET cider-mode` to
-get a list of the keybindings for `cider-mode`.
+!!! Tip
+
+    There's no need to memorize this list. In any Clojure buffer with `cider-mode`
+    active you'll have a CIDER menu available, which lists all the most important
+    commands and their keybindings. You can also invoke `C-h f RET cider-mode` to
+    get a list of the keybindings for `cider-mode`.
 
 ![CIDER interactions menu](images/menu_example.png)
 
-An even better solution would be to install [which-key][], which will
-automatically show you a list of available keybindings as you start typing some
-keys. This will simplify your interactions with CIDER quite a lot (especially in
-the beginning). Here's what you'd see if you typed <kbd>C-c C-d</kbd> in a
-Clojure buffer:
+
+!!! Tip
+
+    An even better solution would be to install [which-key][], which will
+    automatically show you a list of available keybindings as you start typing some
+    keys. This will simplify your interactions with CIDER quite a lot (especially in
+    the beginning). Here's what you'd see if you typed <kbd>C-c C-d</kbd> in a
+    Clojure buffer:
 
 ![CIDER which-key](images/cider-which-key.png)
 
diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md
index 86aecf7b..00f3e070 100644
--- a/doc/troubleshooting.md
+++ b/doc/troubleshooting.md
@@ -15,8 +15,10 @@ Emacs features a super powerful built-in
 [Emacs Lisp debugger](http://www.gnu.org/software/emacs/manual/html_node/elisp/Edebug.html)
 and using it is the best way to diagnose problems of any kind.
 
-Here's a [great crash course](https://www.youtube.com/watch?v=odkYXXYOxpo) on
-using the debugger.
+!!! Tip
+
+    Here's a [great crash course](https://www.youtube.com/watch?v=odkYXXYOxpo) on
+    using the debugger.
 
 To debug some command you need to do the following:
 
@@ -40,8 +42,10 @@ it is pretty simple:
 2. Invoke some commands.
 3. Get the report with <kbd>M-x</kbd> `profiler-report`.
 
-If you intend to share the profiling results with someone it's a good idea to
-save the report buffer to a file with <kbd>C-x C-w</kbd>.
+!!! Tip
+
+    If you intend to share the profiling results with someone it's a good idea to
+    save the report buffer to a file with <kbd>C-x C-w</kbd>.
 
 ## Commonly encountered problems (and how to solve them)