diff --git a/README.md b/README.md
index a734ebb..a0b8e81 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,23 @@
 # tagbar markdown extension
 
-### Intro
+## Intro
 tagbar-markdown is a tagbar extension for markdown.
 
-### Screenshot
+## Screenshot
 ![2017-02-01_1359x723](https://cloud.githubusercontent.com/assets/13142418/22514376/12f8a792-e8da-11e6-9897-fb0136732a31.png)
 
-### Install
+## Install
+
+**Prerequisites:**
+* ensure _PHP_ is installed, and in your `$PATH`.
+* `bin/mdctags` is executable. The install method for `vim-plug` below does this automatically.
+
+**Installing the plugin**
+
 - [vim-plug]
 ```viml
 Plug 'majutsushi/tagbar'
-Plug 'lvht/tagbar-markdown'
+Plug 'lvht/tagbar-markdown', { 'do': 'chmod +x ./bin/mdctags' }
 ```
 - Use [dein.vim] to lazy load plugin, and check the requirements.
 ```viml
@@ -18,11 +25,78 @@ call dein#add('', {'on_cmd' : 'TagbarToggle'})
 call dein#add('', {'on_ft' : 'markdown', 'if' : executable('php')})
 ```
 
-Please make sure **php** is in your `$PATH` and the `bin/mdctags` has execute permission.
+## Configuration
+
+There's one variable that determines what the generated table of contents looks like:
+
+```
+let g:mktagbar_content_format=3
+```
+
+ - Value `3` will generate a table-like list, where line-breaks (`---` in markdown) from the document will be added, this allows you to divide the document, and ToC into sections more easily. [DEFAULT]
+ - Value `2` will generate the same table-like ToC, omitting the lines
+ - Value `1` (or any other value) will generate a simple list containing only the titles.
+
+Examples of each of these formats below
+
+In future, we ought to switch to more intuitively named `const` variables for each layout option (once vim9 is guaranteed to be available to all).
+
+## Generate ToC
 
-execute ':MDAgenda' to insert content agenda in the current line.
+Simply executing the command `:MDAgenda` will insert the ToC, as per configured layout.
 
 Enjoy :)
 
+---
+
+## Examples:
+
+### content_format 3
+
+Neatly padded table, with line-breaks.
+
+ +==========================================+
+ | - [Intro](#Intro)                        |
+ | - [Screenshot](#Screenshot)              |
+ | - [Install](#Install)                    |
+ | - [Configuration](#Configuration)        |
+ | - [Generate ToC](#Generate ToC)          |
+ | ---------------------------------------- |
+ | - [Examples:](#Examples:)                |
+ |  - [content_format 3](#content_format 3) |
+ |  - [content_format 2](#content_format 2) |
+ |  - [content_format 1](#content_format 1) |
+ +==========================================+
+
+### content_format 2
+
+Neatly padded table, titles only
+
+ +==========================================+
+ | - [Intro](#Intro)                        |
+ | - [Screenshot](#Screenshot)              |
+ | - [Install](#Install)                    |
+ | - [Configuration](#Configuration)        |
+ | - [Generate ToC](#Generate ToC)          |
+ | - [Examples:](#Examples:)                |
+ |  - [content_format 3](#content_format 3) |
+ |  - [content_format 2](#content_format 2) |
+ |  - [content_format 1](#content_format 1) |
+ +==========================================+
+
+### content_format 1
+
+Titles only
+
+- [Intro](#Intro)
+- [Screenshot](#Screenshot)
+- [Install](#Install)
+- [Configuration](#Configuration)
+- [Generate ToC](#Generate ToC)
+- [Examples:](#Examples:)
+ - [content_format 3](#content_format 3)
+ - [content_format 2](#content_format 2)
+ - [content_format 1](#content_format 1)
+
 [vim-plug]: https://github.com/junegunn/vim-plug
 [dein.vim]: https://github.com/Shougo/dein.vim
diff --git a/bin/mdctags b/bin/mdctags
index b38939d..0aa2180 100755
--- a/bin/mdctags
+++ b/bin/mdctags
@@ -17,21 +17,40 @@ if (isset($argv[1])) {
 
     $path = $f->getRealPath();
     $stack = [];
-    $in_code = false;
+    $inCode = false;
+    $ln = ""; // last line printed
+    $ctLines = [];
+    $longest = 0;
+    $toc = 0;
+    if (isset($argv[2])) {
+        switch ($argv[2]) {
+        case '3':
+            $toc = 3;
+            break;
+        case '2':
+            $toc = 2;
+            break;
+        default:
+            $toc = 1;
+        }
+    }
 
     $lineNo = 0;
     foreach ($f as $line) {
         ++$lineNo;
         if (preg_match('/^```/', $line)) {
-            $in_code = !$in_code;
+            $inCode = !$inCode;
+        }
+        if ($inCode) {
+            continue;
         }
-        if (!$in_code && preg_match('/^(#+)\s+(\S.*)$/', rtrim($line), $matches)) {
+        if (preg_match('/^(#+)\s+(\S.*)$/', rtrim($line), $matches)) {
             $title = $matches[2];
             $anchor = $matches[0];
 
             $line = [
                 'title' => $matches[2],
-                'level' => strlen($matches[1]),
+                'level' => mb_strlen($matches[1]),
             ];
 
             if (count($stack) == 0) {
@@ -58,14 +77,36 @@ if (isset($argv[1])) {
             $scope = $scopesStr ? "h$plevel:$scopesStr" : '';
             $type = chr(0x60 + $level);
 
-            if (isset($argv[2])) {
+            if ($toc) {
                 if ($level > 1) {
                     $title = $matches[2];
-                    echo str_pad('', strlen($matches[1])-2, ' ')."- [$title](#$title)\n";
+                    $ln = str_pad('', $line['level'] -2, ' ') . "- [$title](#$title)";
+                    if ($toc === 1) {
+                        echo $ln, "\n";
+                    } else {
+                        // keep track of longest line
+                        $longest = max($longest, mb_strlen($ln));
+                        $ctLines[] = $ln;
+                    }
                 }
             } else {
                 echo "$title\t$path\t/^$anchor\$/;\"\t$type\tline:$lineNo\t$scope\n";
             }
+        } else if ($toc === 3 && preg_match('/^-{3,}\s*$/', rtrim($line), $matches)) {
+            // markdown for a line, and lines are included
+            $ctLines[] = null;
+        }
+    }
+    // print out the nicely formatted table of contents
+    if (!empty($ctLines)) {
+        echo ' +', str_pad('', $longest+2, '='), "+\n";
+        for ($i = 0; $i < count($ctLines); $i++) {
+            if ($ctLines[$i] === null) {
+                $ctLines[$i] = str_pad('',$longest, '-'); // add dashes
+            }
+            // print out formatted line
+            printf(" | %-{$longest}s |\n", $ctLines[$i]); // padding for all entries so the table looks nice
         }
+        echo ' +', str_pad('', $longest+2, '='), "+\n";
     }
 }
diff --git a/plugin/markdown_tagbar.vim b/plugin/markdown_tagbar.vim
index 8f78b0f..4a82fa2 100644
--- a/plugin/markdown_tagbar.vim
+++ b/plugin/markdown_tagbar.vim
@@ -9,7 +9,7 @@ let s:bin_path = expand('<sfile>:p:h:h').'/bin/mdctags'
 
 function! s:insertAgenda()
 	let md_path = expand('%:p')
-	execute "read !".s:bin_path.' '.md_path.' 1'
+	execute "read !".s:bin_path.' '.md_path.' '.g:mktagbar_content_format
 endfunction
 
 command! -nargs=0 MDAgenda call s:insertAgenda()
@@ -49,6 +49,11 @@ endif
 let g:tagbar_type_ghmarkdown = g:tagbar_type_markdown
 let g:tagbar_type_rmd = g:tagbar_type_markdown
 
+"" Set to values 1 through 3. 1 is plain format (just titles)
+"" 2 is titles in a nice table/frame
+"" 3 includes lines (---) in the ToC
+let g:mktagbar_content_format=3
+
 let &cpo = s:save_cpo
 unlet s:save_cpo