From b4c0cd2d158968b7b26914a1667589616dbaa120 Mon Sep 17 00:00:00 2001
From: JAremko <w3techplayground@gmail.com>
Date: Mon, 14 Mar 2016 16:34:27 +0200
Subject: [PATCH 1/8] fix typo

---
 core/core-documentation.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/core/core-documentation.el b/core/core-documentation.el
index b5ee897b0e87..61ac5ca36b95 100644
--- a/core/core-documentation.el
+++ b/core/core-documentation.el
@@ -88,7 +88,7 @@
       content)))
 
 (defun spacemacs/publish-doc ()
-  "Publishe the documentation to doc/export/."
+  "Publish the documentation to doc/export/."
   (interactive)
   (advice-add 'org-html-toc :filter-return #'spacemacs//format-toc)
   (advice-add 'org-html-template :filter-return #'spacemacs//format-content)

From d8b0e2054dcae70c4e963c086778b154187f292b Mon Sep 17 00:00:00 2001
From: JAremko <w3techplayground@gmail.com>
Date: Mon, 14 Mar 2016 16:37:46 +0200
Subject: [PATCH 2/8] Remove query.stickytableheaders.js (error 404)

---
 core/core-documentation.el | 2 --
 1 file changed, 2 deletions(-)

diff --git a/core/core-documentation.el b/core/core-documentation.el
index 61ac5ca36b95..5e6a7bc03ba4 100644
--- a/core/core-documentation.el
+++ b/core/core-documentation.el
@@ -97,8 +97,6 @@
                  href=\"http://www.pirilampo.org/styles/readtheorg/css/htmlize.css\"/>
           <script src=\"https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js\"></script>
           <script src=\"https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js\"></script>
-          <script type=\"text/javascript\"
-                  src=\"http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js\"></script>
           <script type=\"text/javascript\"
                   src=\"http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js\"></script>
           <script>

From c2388d058dea5d78431e7ada949de677f9898350 Mon Sep 17 00:00:00 2001
From: JAremko <w3techplayground@gmail.com>
Date: Mon, 14 Mar 2016 18:00:21 +0200
Subject: [PATCH 3/8] Insert the readtheorg.css links wth html export advice

It removes the need to clutter Spacemacs documentation with
Also it reduces the amount of bugs, because it's hard to get the path right.
---
 core/core-documentation.el | 42 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/core/core-documentation.el b/core/core-documentation.el
index 5e6a7bc03ba4..12ccd678a4e6 100644
--- a/core/core-documentation.el
+++ b/core/core-documentation.el
@@ -13,6 +13,7 @@
 (require 'ox-publish)
 (require 's)
 (require 'dash)
+(require 'f)
 
 (defvar spacemacs--category-names
   '(("config-files" . "Configuration files")
@@ -87,11 +88,49 @@
         (format "%s\n%s%s" beginning-of-content toc-string rest-of-content)
       content)))
 
+(defun spacemacs//add-org-meta-readtheorg-css (filename)
+  (let* ((head-css-extra-readtheorg-head (concat
+                                          "#+HTML_HEAD_EXTRA:"
+                                          "<link rel=\"stylesheet\" "
+                                          "type=\"text/css\" "
+                                          "href=\""))
+         (head-css-extra-readtheorg-tail "css/readtheorg.css\" />\n"))
+    (progn (goto-char (point-min))
+           (delete-matching-lines "\\+HTML_HEAD_EXTRA\\:.*\\/css\\/readtheorg\\.css")
+           (goto-char (point-min))
+           (if (search-forward "#+TITLE:" nil t nil)
+               (beginning-of-line 2)
+             (error "Can't find #+TITLE:"))
+           (insert (concat head-css-extra-readtheorg-head
+                           (f-relative user-emacs-directory
+                                       (file-name-directory filename))
+                           head-css-extra-readtheorg-tail)))))
+
+(defun spacemacs//pub-doc-html-advice (origfunc &rest args)
+  (save-current-buffer
+    (save-excursion
+      (let* ((filename (car (nthcdr 1 args)))
+             (visitingp (find-buffer-visiting filename)))
+        ;; Temporary "unvisit" the visited org files.
+        (when visitingp (with-current-buffer visitingp (setq buffer-file-name nil)))
+        (with-temp-buffer
+          (save-match-data
+            (insert-file-contents filename t)
+            (spacemacs//add-org-meta-readtheorg-css filename)
+
+
+
+            (apply origfunc args)
+            (not-modified)))
+        ;; Restore `buffer-file-name' for the buffers that previously visited the org files.
+        (when visitingp (with-current-buffer visitingp (setq buffer-file-name filename)))))))
+
 (defun spacemacs/publish-doc ()
   "Publish the documentation to doc/export/."
   (interactive)
   (advice-add 'org-html-toc :filter-return #'spacemacs//format-toc)
   (advice-add 'org-html-template :filter-return #'spacemacs//format-content)
+  (advice-add 'org-html-publish-to-html :around #'spacemacs//pub-doc-html-advice)
   (let* ((header
           "<link rel=\"stylesheet\" type=\"text/css\"
                  href=\"http://www.pirilampo.org/styles/readtheorg/css/htmlize.css\"/>
@@ -146,6 +185,7 @@
              :publishing-function org-publish-attachment))))
     (org-publish-project "spacemacs"))
   (advice-remove 'org-html-toc #'spacemacs//format-toc)
-  (advice-remove 'org-html-template #'spacemacs//format-content))
+  (advice-remove 'org-html-template #'spacemacs//format-content)
+  (advice-remove 'org-html-publish-to-html #'spacemacs//pub-doc-html-advice))
 
 (provide 'core-documentation)

From 50e9a1f789229f4f4383206d8b154ec815284d73 Mon Sep 17 00:00:00 2001
From: JAremko <w3techplayground@gmail.com>
Date: Mon, 14 Mar 2016 20:44:37 +0200
Subject: [PATCH 4/8] Make export to html compatible with GitHub and toc-org

Add new html preprocessors to the org-html-publish-to-html pipeline:
  - `spacemacs//toc-org-unhrefify-toc` - remove the `toc-org` modifications for the TOC
  - `spacemacs//org-heading-annotate-custom-id` - annotate org headings with the indexes that GitHub uses for linking. `org-html-publish-to-html` will use them instead of the default `#orgheadline{N}`. This way the GitHub links and the http://spacemacs.org/ links will be compatible."
  - `spacemacs//reroot-links` - find the links that start with https://github.com/syl20bnr/spacemacs/blob/ and end with .org{#an-optional-heading-link} (i.e the links between the local org files). Change their root to http://spacemacs.org/ so the links will point at files located on the site.

*For the "file to file" links to work properly the expor
---
 core/core-documentation.el | 57 +++++++++++++++++++++++++++++++++++---
 1 file changed, 53 insertions(+), 4 deletions(-)

diff --git a/core/core-documentation.el b/core/core-documentation.el
index 12ccd678a4e6..5057d06067fd 100644
--- a/core/core-documentation.el
+++ b/core/core-documentation.el
@@ -14,6 +14,8 @@
 (require 's)
 (require 'dash)
 (require 'f)
+(require 'toc-org)
+(require 'org-id)
 
 (defvar spacemacs--category-names
   '(("config-files" . "Configuration files")
@@ -88,6 +90,49 @@
         (format "%s\n%s%s" beginning-of-content toc-string rest-of-content)
       content)))
 
+(defun spacemacs//toc-org-unhrefify-toc ()
+  "Make TOC classical org-mode TOC."
+  (let ((toc-org-hrefify-default "org"))
+    (toc-org-insert-toc)))
+
+(defun spacemacs//org-heading-annotate-custom-id ()
+  "Annotate headings with the indexes that GitHub uses for linking.
+`org-html-publish-to-html' will use them instead of the default #orgheadline{N}.
+This way the GitHub links and the http://spacemacs.org/ links will be compatible."
+  (progn (goto-char (point-min))
+         (goto-char (point-min))
+         (while (re-search-forward "^[\\*]+\s\\(.*\\).*$" nil t)
+           (let ((heading (match-string 1)))
+             (progn (move-end-of-line nil)
+                    (open-line 1)
+                    (next-line 1)
+                    (insert (format (concat "  :PROPERTIES:\n"
+                                            "  :CUSTOM_ID: %s\n"
+                                            "  :END:\n")
+                                    (substring (toc-org-hrefify-gh
+                                                (replace-regexp-in-string
+                                                 toc-org-tags-regexp
+                                                 ""
+                                                 heading))
+                                               ;; Remove # prefix added by `toc-org-hrefify-gh'.
+                                               1))))))))
+
+(defun spacemacs//reroot-links ()
+  "Find the links that start with https://github.com/syl20bnr/spacemacs/blob/
+and end with .org{#an-optional-heading-link} (i.e the links between the local org files).
+Change their root to http://spacemacs.org/ so the links will point at files located on the site.
+For the file to file links to work properly the exported org files should be processed with
+the `spacemacs//org-heading-annotate-custom-id' function."
+  (let ((git-url-root-regexp
+         (concat "\\[\\[[\\s]*\\(https\\:\\/\\/github\\.com\\/syl20bnr"
+                 "\\/spacemacs\\/blob\\/[^/]+\\/\\)[^]]+\\(\\.org\\).*$"))
+        (site-url "http://spacemacs.org/")
+        (site-doc-postf ".html"))
+    (progn (goto-char (point-min))
+           (while (re-search-forward git-url-root-regexp nil t)
+             (progn (replace-match site-url nil t nil 1)
+                    (replace-match site-doc-postf nil t nil 2))))))
+
 (defun spacemacs//add-org-meta-readtheorg-css (filename)
   (let* ((head-css-extra-readtheorg-head (concat
                                           "#+HTML_HEAD_EXTRA:"
@@ -100,13 +145,16 @@
            (goto-char (point-min))
            (if (search-forward "#+TITLE:" nil t nil)
                (beginning-of-line 2)
-             (error "Can't find #+TITLE:"))
+             (error (format "Can't find #+TITLE: in %s"
+                            (buffer-file-name))))
            (insert (concat head-css-extra-readtheorg-head
                            (f-relative user-emacs-directory
                                        (file-name-directory filename))
                            head-css-extra-readtheorg-tail)))))
 
 (defun spacemacs//pub-doc-html-advice (origfunc &rest args)
+  "Wrapper for `org-html-publish-to-html' use it to insert
+preprocessors for the exported .org files."
   (save-current-buffer
     (save-excursion
       (let* ((filename (car (nthcdr 1 args)))
@@ -116,10 +164,11 @@
         (with-temp-buffer
           (save-match-data
             (insert-file-contents filename t)
+            ;; ===========Add preprocessors here===============
             (spacemacs//add-org-meta-readtheorg-css filename)
-
-
-
+            (spacemacs//toc-org-unhrefify-toc)
+            (spacemacs//reroot-links)
+            (spacemacs//org-heading-annotate-custom-id)
             (apply origfunc args)
             (not-modified)))
         ;; Restore `buffer-file-name' for the buffers that previously visited the org files.

From f6820c686c113d1205c6776d6cea35002afa5b30 Mon Sep 17 00:00:00 2001
From: JAremko <w3techplayground@gmail.com>
Date: Tue, 15 Mar 2016 13:14:27 +0200
Subject: [PATCH 5/8] Add Spacemacs docs minor mode to hide meta tags.

`space-doc-mode` - Buffer local minor mode for Spacemacs documentation files. The mode hides org meta tags.
Enabled when viewing documentation via `SPC` `h` `SPC`
---
 core/core-funcs.el                            |  1 +
 .../+emacs/org/local/space-doc/space-doc.el   | 46 +++++++++++++++++++
 layers/+emacs/org/packages.el                 |  4 ++
 3 files changed, 51 insertions(+)
 create mode 100644 layers/+emacs/org/local/space-doc/space-doc.el

diff --git a/core/core-funcs.el b/core/core-funcs.el
index 73216ddc9798..4cffcf022017 100644
--- a/core/core-funcs.el
+++ b/core/core-funcs.el
@@ -171,6 +171,7 @@ Supported properties:
   (find-file file)
   (org-indent-mode)
   (view-mode)
+  (when(and(boundp 'space-doc-mode)(fboundp 'space-doc-mode)(space-doc-mode)))
   (goto-char (point-min))
 
   (when anchor-text
diff --git a/layers/+emacs/org/local/space-doc/space-doc.el b/layers/+emacs/org/local/space-doc/space-doc.el
new file mode 100644
index 000000000000..63bc93a28383
--- /dev/null
+++ b/layers/+emacs/org/local/space-doc/space-doc.el
@@ -0,0 +1,46 @@
+;;; space-doc.el --- Spacemacs documentation minor mode.
+;;
+;; Copyright (c) 2012-2016 Sylvain Benner & Contributors
+;;
+;; Author: Sylvain Benner <sylvain.benner@gmail.com>
+;; URL: https://github.com/syl20bnr/spacemacs
+;;
+;; This file is not part of GNU Emacs.
+;;
+;;; License: GPLv3
+;;; Code:
+(require 'face-remap)
+(require 'org)
+
+;;;###autoload
+(define-minor-mode space-doc-mode
+  "Buffer local minor mode for Spacemacs documentation files.
+The mode hides `org-mode' meta tags like #+TITLE: while
+keeping their content visible."
+  :init-value nil
+  :lighter " ❤"
+  (if (eq major-mode 'org-mode)
+      (if space-doc-mode
+          (let ((bg (face-attribute 'default :background)))
+            (progn
+              ;; Make `org-mode' meta tags invisible.
+              (set (make-local-variable 'spacemacs--org-face-remap-cookie-org-tag)
+                   (face-remap-add-relative 'org-tag                  `(:foreground ,bg)))
+              (set (make-local-variable 'spacemacs--org-face-remap-cookie-org-meta-line)
+                   (face-remap-add-relative 'org-meta-line             `(:foreground ,bg)))
+              (set (make-local-variable 'spacemacs--org-face-remap-cookie-org-block-begin-line)
+                   (face-remap-add-relative 'org-block-begin-line      `(:foreground ,bg)))
+              (set (make-local-variable 'spacemacs--org-face-remap-cookie-org-document-info-keyword)
+                   (face-remap-add-relative 'org-document-info-keyword `(:foreground ,bg)))))
+        (progn
+          ;; Make `org-mode' meta tags visible.
+          (face-remap-remove-relative spacemacs--org-face-remap-cookie-org-tag)
+          (face-remap-remove-relative spacemacs--org-face-remap-cookie-org-meta-line)
+          (face-remap-remove-relative spacemacs--org-face-remap-cookie-org-block-begin-line)
+          (face-remap-remove-relative spacemacs--org-face-remap-cookie-org-document-info-keyword)
+          (setq spacemacs--org-face-remap-p nil)))
+    (progn (message (format "space-doc-mode error:%s isn't an org-mode buffer" (buffer-name)))
+           (setq org-mode nil))))
+
+(provide 'space-doc)
+;;; space-doc.el ends here
diff --git a/layers/+emacs/org/packages.el b/layers/+emacs/org/packages.el
index 288008850b1f..afb000e7fc4a 100644
--- a/layers/+emacs/org/packages.el
+++ b/layers/+emacs/org/packages.el
@@ -33,6 +33,7 @@
     org-repo-todo
     (ox-gfm :location local)
     persp-mode
+    (space-doc :location local)
     toc-org
     ))
 
@@ -567,3 +568,6 @@ a Markdown buffer and use this command to convert it.
 (defun org/init-htmlize ()
  (use-package htmlize
     :defer t))
+
+(defun org/init-space-doc ()
+  (use-package space-doc))

From 68be3a3d5056ecde1be185333f3b8e3dfe9c0a59 Mon Sep 17 00:00:00 2001
From: JAremko <w3techplayground@gmail.com>
Date: Sat, 19 Mar 2016 04:59:36 +0200
Subject: [PATCH 6/8] Add org-mode link-type "https" to open local copies

The https link-type opens the local copies of the Spacemacs documentation files with
the spacemacs/view-org-file function. It supports GitHub style heading links

For example, the link:

https://github.com/syl20bnr/spacemacs/blob/develop/layers/org/README.org#links

Will be handled similary to as if it was:

file:~/.emacs.d/layers/org/README.org::*links

Also the `space-doc' mode will be applied.

Refactored GH style anchor search.
---
 core/core-funcs.el                            | 24 +++++++++++--
 .../+emacs/org/local/space-doc/space-doc.el   | 34 +++++++++++++++++++
 2 files changed, 55 insertions(+), 3 deletions(-)

diff --git a/core/core-funcs.el b/core/core-funcs.el
index 4cffcf022017..a3a6ef7b0397 100644
--- a/core/core-funcs.el
+++ b/core/core-funcs.el
@@ -171,12 +171,30 @@ Supported properties:
   (find-file file)
   (org-indent-mode)
   (view-mode)
-  (when(and(boundp 'space-doc-mode)(fboundp 'space-doc-mode)(space-doc-mode)))
+
+  ;; Enable `space-doc-mode' if defined.
+  (when (and (boundp 'space-doc-mode)
+             (fboundp 'space-doc-mode))
+    (space-doc-mode))
+
   (goto-char (point-min))
 
   (when anchor-text
-    (re-search-forward anchor-text))
-  (beginning-of-line)
+    ;; If `anchor-text' is GitHub style link.
+    (if (string-prefix-p "#" anchor-text)
+        ;; If the toc-org package is loaded.
+        (if (configuration-layer/package-usedp 'toc-org)
+            ;; For each heading. Search the heading that corresponds to `anchor-text'.
+            (while (and (re-search-forward "^[\\*]+\s\\(.*\\).*$" nil t)
+                        (not (string= (toc-org-hrefify-gh (match-string 1))
+                                      anchor-text))))
+          ;; This is not a problem because without the space-doc package
+          ;; those links will be opened in the browser.
+          (message (format "Can't follow the GitHub style anchor: '%s' without the org layer." anchor-text)))
+
+      (re-search-forward anchor-text)))
+
+(beginning-of-line)
 
   (cond
    ((eq expand-scope 'subtree)
diff --git a/layers/+emacs/org/local/space-doc/space-doc.el b/layers/+emacs/org/local/space-doc/space-doc.el
index 63bc93a28383..ea8d1e411928 100644
--- a/layers/+emacs/org/local/space-doc/space-doc.el
+++ b/layers/+emacs/org/local/space-doc/space-doc.el
@@ -7,6 +7,22 @@
 ;;
 ;; This file is not part of GNU Emacs.
 ;;
+;; Description:
+;; This package provides:
+;;   - `space-doc-mode' - buffer local minor mode
+;; for viewing the Spacemacs documentation files.
+;; The mode hides org meta tags to improve readability.
+;;   - `org-mode' link-type "https" that opens the local
+;; copies of the Spacemacs documentation files with
+;; `spacemacs/view-org-file' and supports GitHub style
+;; heading links.
+;;
+;; For example, the link:
+;;  https://github.com/syl20bnr/spacemacs/blob/develop/layers/org/README.org#links
+;; Will be handled similary to as if it was:
+;; file:~/.emacs.d/layers/org/README.org::*links
+;; Also the `space-doc' mode will be applied.
+
 ;;; License: GPLv3
 ;;; Code:
 (require 'face-remap)
@@ -42,5 +58,23 @@ keeping their content visible."
     (progn (message (format "space-doc-mode error:%s isn't an org-mode buffer" (buffer-name)))
            (setq org-mode nil))))
 
+(defun spacemacs//space-doc-open (path)
+  "If the `path' argument is a link to an .org file that is located
+in the Spacemacs GitHub repository - Visit the local copy
+of the file with `spacemacs/view-org-file'.
+Open all other links with `browse-url'."
+  (let ((git-url-root-regexp
+         (concat "\\/\\/github\\.com\\/syl20bnr"
+                 "\\/spacemacs\\/blob\\/[^/]+\\/\\(.*\\.org\\)\\(\\#.*\\)?")))
+    (if (string-match git-url-root-regexp path)
+        (spacemacs/view-org-file (concat user-emacs-directory
+                                         (match-string 1 path))
+                                 (or (match-string 2 path)
+                                     "^")
+                                 'subtree)
+      (browse-url (concat "https://" path)))))
+
+(org-add-link-type "https" 'spacemacs//space-doc-open)
+
 (provide 'space-doc)
 ;;; space-doc.el ends here

From 341577941c1a3b7c49a919d382f3f9dd51457b2e Mon Sep 17 00:00:00 2001
From: JAremko <w3techplayground@gmail.com>
Date: Sat, 19 Mar 2016 15:45:40 +0200
Subject: [PATCH 7/8] Add the new .org example and a formatting script

Add ./doc-fmt/ folder that contains the .org example and
the script(run.bash) that should be run from the repo root.
Its purpose:
  - remove  #+HTML_HEAD_EXTRA: ... readtheorg.css" />
  - replace :TOC_4_org:noexport: with :TOC_4_gh:noexport:
  - apply the gh style TOC
---
 doc-fmt/run.bash         |  30 +++
 doc-fmt/test.org         |  29 +++
 doc-fmt/toc-org-apply.el |   4 +
 doc-fmt/toc-org.el       | 409 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 472 insertions(+)
 create mode 100755 doc-fmt/run.bash
 create mode 100644 doc-fmt/test.org
 create mode 100644 doc-fmt/toc-org-apply.el
 create mode 100644 doc-fmt/toc-org.el

diff --git a/doc-fmt/run.bash b/doc-fmt/run.bash
new file mode 100755
index 000000000000..0a9f29547f9f
--- /dev/null
+++ b/doc-fmt/run.bash
@@ -0,0 +1,30 @@
+#!/bin/bash
+
+if ! [ -d "./.git" ]
+	then
+		echo "Should be executed from the repo root."
+		exit 1
+fi
+
+#rm #+HTML_HEAD_EXTRA: ... readtheorg.css" /> in the doc.
+find ./doc    -name "*.org" -type f -exec sed -i '/#+HTML_HEAD_EXTRA.*readtheorg.css.*/d' {} \;
+
+#rm #+HTML_HEAD_EXTRA: ... readtheorg.css" /> in the layers.
+find ./layers -name "*.org" -type f -exec sed -i '/#+HTML_HEAD_EXTRA.*readtheorg.css.*/d' {} \;
+
+
+
+#replace :TOC_4_org: with :TOC_4_gh: in the doc.
+find ./doc    -name "*.org" -type f -exec sed -i 's/:TOC_4_org:/:TOC_4_gh:/' {} \;
+
+#replace :TOC_4_org: with :TOC_4_gh: in the layers.
+find ./layers -name "*.org" -type f -exec sed -i 's/:TOC_4_org:/:TOC_4_gh:/' {} \;
+
+
+
+#apply toc-org to doc.
+find ./doc    -name "*.org" -type f -exec emacs -batch -l ./doc-fmt/toc-org-apply.el '{}' -f toc-apply \;
+
+#apply toc-org to layers.
+find ./layers -name "*.org" -type f -exec emacs -batch -l ./doc-fmt/toc-org-apply.el '{}' -f toc-apply \;
+
diff --git a/doc-fmt/test.org b/doc-fmt/test.org
new file mode 100644
index 000000000000..2d3a108eb5be
--- /dev/null
+++ b/doc-fmt/test.org
@@ -0,0 +1,29 @@
+#+TITLE: FOO
+
+* Table of Contents                                         :TOC_4_gh:noexport:
+ - [[#links][Links]]
+ - [[#foo][FOO]]
+ - [[#bar][BAR]]
+ - [[#baz][BAZ]]
+
+* Links
+
+[[https://github.com/syl20bnr/spacemacs/blob/master/doc/FAQ.org#os-x][Link to FAQ "OS X" heading]]
+
+[[https://www.google.com][Link to www.google.com]]
+
+[[https://github.com/syl20bnr/spacemacs/blob/master/doc/VIMUSERS.org#sessions]]
+
+[[https://github.com/syl20bnr/spacemacs/blob/master/layers/%2Bfun/emoji/README.org][Link to Emoji layer README.org]]
+
+* FOO
+
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. Integer tincidunt. Cras dapibus. Vivamus elementum semper nisi. Aenean vulputate eleifend tellus. Aenean leo ligula, porttitor eu, consequat vitae, eleifend ac, enim. Aliquam lorem ante, dapibus in, viverra quis, feugiat a, tellus. Phasellus viverra nulla ut metus varius laoreet. Quisque rutrum. Aenean imperdiet. Etiam ultricies nisi vel augue. Curabitur ullamcorper ultricies nisi. Nam eget dui. Etiam rhoncus. Maecenas tempus, tellus eget condimentum rhoncus, sem quam semper libero, sit amet adipiscing sem neque sed ipsum. Nam quam nunc, blandit vel, luctus pulvinar, hendrerit id, lorem. Maecenas nec odio et ante tincidunt tempus. Donec vitae sapien ut libero venenatis faucibus. Nullam quis ante. Etiam sit amet orci eget eros faucibus tincidunt. Duis leo. Sed fringilla mauris sit amet nibh. Donec sodales sagittis magna. Sed conseq
+
+* BAR
+
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. Integer tincidunt. Cras dapibus. Vivamus elementum semper nisi. Aenean vulputate eleifend tellus. Aenean leo ligula, porttitor eu, consequat vitae, eleifend ac, enim. Aliquam lorem ante, dapibus in, viverra quis, feugiat a, tellus. Phasellus viverra nulla ut metus varius laoreet. Quisque rutrum. Aenean imperdiet. Etiam ultricies nisi vel augue. Curabitur ullamcorper ultricies nisi. Nam eget dui. Etiam rhoncus. Maecenas tempus, tellus eget condimentum rhoncus, sem quam semper libero, sit amet adipiscing sem neque sed ipsum. Nam quam nunc, blandit vel, luctus pulvinar, hendrerit id, lorem. Maecenas nec odio et ante tincidunt tempus. Donec vitae sapien ut libero venenatis faucibus. Nullam quis ante. Etiam sit amet orci eget eros faucibus tincidunt. Duis leo. Sed fringilla mauris sit amet nibh. Donec sodales sagittis magna. Sed conseq
+
+* BAZ
+
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. Integer tincidunt. Cras dapibus. Vivamus elementum semper nisi. Aenean vulputate eleifend tellus. Aenean leo ligula, porttitor eu, consequat vitae, eleifend ac, enim. Aliquam lorem ante, dapibus in, viverra quis, feugiat a, tellus. Phasellus viverra nulla ut metus varius laoreet. Quisque rutrum. Aenean imperdiet. Etiam ultricies nisi vel augue. Curabitur ullamcorper ultricies nisi. Nam eget dui. Etiam rhoncus. Maecenas tempus, tellus eget condimentum rhoncus, sem quam semper libero, sit amet adipiscing sem neque sed ipsum. Nam quam nunc, blandit vel, luctus pulvinar, hendrerit id, lorem. Maecenas nec odio et ante tincidunt tempus. Donec vitae sapien ut libero venenatis faucibus. Nullam quis ante. Etiam sit amet orci eget eros faucibus tincidunt. Duis leo. Sed fringilla mauris sit amet nibh. Donec sodales sagittis magna. Sed conseq
diff --git a/doc-fmt/toc-org-apply.el b/doc-fmt/toc-org-apply.el
new file mode 100644
index 000000000000..6e8e2036695f
--- /dev/null
+++ b/doc-fmt/toc-org-apply.el
@@ -0,0 +1,4 @@
+(load-file  "./doc-fmt/toc-org.el")
+(defun toc-apply ()
+  (toc-org-insert-toc)
+  (save-buffer 0))
diff --git a/doc-fmt/toc-org.el b/doc-fmt/toc-org.el
new file mode 100644
index 000000000000..30bb306f5540
--- /dev/null
+++ b/doc-fmt/toc-org.el
@@ -0,0 +1,409 @@
+;;; toc-org.el --- add table of contents to org-mode files (formerly, org-toc)
+
+;; Copyright (C) 2014 Sergei Nosov
+
+;; Author: Sergei Nosov <sergei.nosov [at] gmail.com>
+;; Version: 1.0
+;; Keywords: org-mode org-toc toc-org org toc table of contents
+;; URL: https://github.com/snosov1/toc-org
+
+;; This program is free software; you can redistribute it and/or
+;; modify it under the terms of the GNU General Public License as
+;; published by the Free Software Foundation; either version 2, or (at
+;; your option) any later version.
+
+;; This program is distributed in the hope that it will be useful, but
+;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+;; General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs; see the file COPYING.  If not, write to the
+;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+;; Boston, MA 02111-1307, USA.
+
+;;; Commentary:
+
+;; toc-org helps you to have an up-to-date table of contents in org files
+;; without exporting (useful primarily for readme files on GitHub).
+
+;; NOTE: Previous name of the package is org-toc. It was changed because of a
+;; name conflict with one of the org contrib modules.
+
+;; After installation put into your .emacs file something like
+
+;; (if (require 'toc-org nil t)
+;;     (add-hook 'org-mode-hook 'toc-org-enable)
+;;   (warn "toc-org not found"))
+
+;; And every time you'll be saving an org file, the first headline with a :TOC:
+;; tag will be updated with the current table of contents.
+
+;; For details, see https://github.com/snosov1/toc-org
+
+;;; Code:
+
+(require 'ert)
+(require 'org)
+
+(defgroup toc-org nil
+  "toc-org is a utility to have an up-to-date table of contents
+in the org files without exporting (useful primarily for readme
+files on GitHub)"
+  :group 'org)
+
+;; just in case, simple regexp "^*.*:toc:\\($\\|[^ ]*:$\\)"
+(defconst toc-org-toc-org-regexp "^*.*:toc\\([@_][0-9]\\|\\([@_][0-9][@_][a-zA-Z]+\\)\\)?:\\($\\|[^ ]*:$\\)"
+  "Regexp to find the heading with the :toc: tag")
+(defconst toc-org-tags-regexp "\s*:[[:word:]:@]*:\s*$"
+  "Regexp to find tags on the line")
+(defconst toc-org-states-regexp "^*+\s+\\(TODO\s+\\|DONE\s+\\)"
+  "Regexp to find states on the line")
+(defconst toc-org-links-regexp "\\[\\[\\(.*?\\)\\]\\[\\(.*?\\)\\]\\]"
+  "Regexp to find states on the line")
+(defconst toc-org-special-chars-regexp "[^[:alnum:]_-]"
+  "Regexp with the special characters (which are omitted in hrefs
+  by GitHub)")
+
+(defcustom toc-org-max-depth 2
+  "Maximum depth of the headings to use in the table of
+contents. The default of 2 uses only the highest level headings
+and their subheadings (one and two stars)."
+  :group 'toc-org)
+
+(defcustom toc-org-hrefify-default "gh"
+  "Default hrefify function to use."
+  :group 'toc-org)
+
+(defcustom toc-org-enable-links-opening t
+  "With this option, org-open-at-point (C-c C-o) should work on
+the TOC links (even if the style is different from org)."
+  :group 'toc-org)
+
+(defvar-local toc-org-hrefify-hash nil
+  "Buffer local hash-table that is used to enable links
+opening. The keys are hrefified headings, the values are original
+headings.")
+
+(defun toc-org-raw-toc ()
+  "Return the \"raw\" table of contents of the current file,
+i.e. simply flush everything that's not a heading and strip
+tags."
+  (let ((content (buffer-substring-no-properties
+                  (point-min) (point-max))))
+    (with-temp-buffer
+      (insert content)
+      (goto-char (point-min))
+      (keep-lines "^\*+[ ]")
+
+      ;; don't include the TOC itself
+      (goto-char (point-min))
+      (re-search-forward toc-org-toc-org-regexp nil t)
+      (beginning-of-line)
+      (delete-region (point) (progn (forward-line 1) (point)))
+
+      ;; strip states
+      (goto-char (point-min))
+      (while (re-search-forward toc-org-states-regexp nil t)
+        (replace-match "" nil nil nil 1))
+
+      ;; strip tags
+      ;; TODO :export: and :noexport: tags semantic should be probably
+      ;; implemented
+      (goto-char (point-min))
+      (while (re-search-forward toc-org-tags-regexp nil t)
+        (replace-match "" nil nil))
+
+      ;; flatten links
+      (goto-char (point-min))
+      (while (re-search-forward toc-org-links-regexp nil t)
+        (replace-match "\\2" nil nil))
+
+      (buffer-substring-no-properties
+       (point-min) (point-max)))))
+
+(ert-deftest toc-org-test-raw-toc ()
+  "Test the `toc-org-raw-toc' function"
+
+  (defun toc-org-test-raw-toc-gold-test (content gold)
+    (should (equal
+             (with-temp-buffer
+               (insert content)
+               (toc-org-raw-toc))
+             gold)))
+  (declare-function toc-org-test-raw-toc-gold-test "toc-org") ;; suppress compiler warning
+
+  (let ((beg "* TODO [[http://somewhere.com][About]]\n:TOC:\n drawer\n:END:\n\ntoc-org is a utility to have an up-to-date table of contents in the\norg files without exporting (useful primarily for readme files on\nGitHub).\n\nIt is similar to the [[https://github.com/ardumont/markdown-toc][markdown-toc]] package, but works for org files.\n:TOC:\n  drawer\n:END:\n\n* Table of Contents                                                     ")
+        (gold "* About\n"))
+
+    ;; different TOC styles
+    (toc-org-test-raw-toc-gold-test (concat beg ":TOC:"         ) gold)
+    (toc-org-test-raw-toc-gold-test (concat beg ":TOC_1:"       ) gold)
+    (toc-org-test-raw-toc-gold-test (concat beg ":TOC_1_qqq:"   ) gold)
+    (toc-org-test-raw-toc-gold-test (concat beg ":TOC@1:"       ) gold)
+    (toc-org-test-raw-toc-gold-test (concat beg ":TOC@1@cxv:"   ) gold)
+    (toc-org-test-raw-toc-gold-test (concat beg ":TOC@1_hello:" ) gold)
+
+    ;; trailing symbols
+    (toc-org-test-raw-toc-gold-test (concat beg ":TOC@1_hello:" "\n\n\n") gold)
+    (toc-org-test-raw-toc-gold-test (concat beg ":TOC@1_hello:" "\n\n\nsdfd") gold))
+
+  ;; more complex case
+  (toc-org-test-raw-toc-gold-test
+   "* About\n:TOC:\n drawer\n:END:\n\ntoc-org is a utility to have an up-to-date table of contents in the\norg files without exporting (useful primarily for readme files on\nGitHub).\n\nIt is similar to the [[https://github.com/ardumont/markdown-toc][markdown-toc]] package, but works for org files.\n:TOC:\n  drawer\n:END:\n\n* Table of Contents                                                     :TOC:\n - [[#about][About]]\n - [[#use][Use]]\n - [[#different-href-styles][Different href styles]]\n - [[#example][Example]]\n\n* Installation\n** via package.el\nThis is the simplest method if you have the package.el module\n(built-in since Emacs 24.1) you can simply use =M-x package-install=\nand then put the following snippet in your ~/.emacs file\n#+BEGIN_SRC elisp\n  (eval-after-load \"toc-org-autoloads\"\n    '(progn\n       (if (require 'toc-org nil t)\n           (add-hook 'org-mode-hook 'toc-org-enable)\n         (warn \"toc-org not found\"))))\n#+END_SRC\n** Manual                                                             :Hello:\n- Create folder ~/.emacs.d if you don't have it\n- Go to it and clone toc-org there\n  #+BEGIN_SRC sh\n    git clone https://github.com/snosov1/toc-org.git\n  #+END_SRC\n- Put this in your ~/.emacs file\n  #+BEGIN_SRC elisp\n    (add-to-list 'load-path \"~/.emacs.d/toc-org\")\n    (when (require 'toc-org nil t)\n      (add-hook 'org-mode-hook 'toc-org-enable))\n  #+END_SRC\n\n* Use\n\nAfter the installation, every time you'll be saving an org file, the\nfirst headline with a :TOC: tag will be updated with the current table\nof contents.\n\nTo add a TOC tag, you can use the command =org-set-tags-command=.\n\nIn addition to the simple :TOC: tag, you can also use the following\ntag formats:\n\n- :TOC@2: - sets the max depth of the headlines in the table of\n  contents to 2 (the default)\n\n- :TOC@2@gh: - sets the max depth as in above and also uses the\n  GitHub-style hrefs in the table of contents (the default). The other\n  supported href style is 'org', which is the default org style (you\n  can use C-c C-o to go to the headline at point).\n\nYou can also use =_= as separator, instead of =@=.\n\n* Different href styles\n\nCurrently, only 2 href styles are supported: =gh= and =org=. You can easily\ndefine your own styles. If you use the tag =:TOC@2@STYLE:= (=STYLE= being a\nstyle name), then the package will look for a function named\n=toc-org-hrefify-STYLE=, which accepts a heading string and returns a href\ncorresponding to that heading.\n\nE.g. for =org= style it simply returns input as is:\n\n#+BEGIN_SRC emacs-lisp\n  (defun toc-org-hrefify-org (str)\n    \"Given a heading, transform it into a href using the org-mode\n  rules.\"\n    str)\n#+END_SRC\n\n* Example\n\n#+BEGIN_SRC org\n  * About\n  * Table of Contents                                           :TOC:\n    - [[#about][About]]\n    - [[#installation][Installation]]\n        - [[#via-packageel][via package.el]]\n        - [[#manual][Manual]]\n    - [[#use][Use]]\n  * Installation\n  ** via package.el\n  ** Manual\n  * Use\n  * Example\n#+END_SRC\n"
+   "* About\n* Installation\n** via package.el\n** Manual\n* Use\n* Different href styles\n* Example\n"))
+
+(defun toc-org-hrefify-gh (str)
+  "Given a heading, transform it into a href using the GitHub
+rules."
+  (let* ((spc-fix (replace-regexp-in-string " " "-" str))
+         (upcase-fix (replace-regexp-in-string "[A-Z]" 'downcase spc-fix t))
+         (special-chars-fix (replace-regexp-in-string toc-org-special-chars-regexp "" upcase-fix t)))
+    (concat "#" special-chars-fix)))
+
+(ert-deftest toc-org-test-hrefify-gh ()
+  "Test the `toc-org-hrefify-gh' function"
+  (should (equal (toc-org-hrefify-gh "About") "#about"))
+  (should (equal (toc-org-hrefify-gh "!h@#$%^&*(){}|][:;\"'/?.>,<`~") "#h"))
+  (should (equal (toc-org-hrefify-gh "!h@#$% ^&*(S){}|][:;\"'/?.>,<`~") "#h-s")))
+
+(defun toc-org-hrefify-org (str)
+  "Given a heading, transform it into a href using the org-mode
+rules."
+  str)
+
+(defun toc-org-unhrefify (type path)
+  "Looks for a value in toc-org-hrefify-hash using path as a key."
+  (let ((ret-type type)
+        (ret-path path)
+        (original-path (and (not (eq toc-org-hrefify-hash nil))
+                            (gethash
+                             (concat
+                              ;; Org 8.3 and above provides type as "custom-id"
+                              ;; and strips the leading hash symbol
+                              (if (equal type "custom-id") "#" "")
+                              (substring-no-properties path))
+                             toc-org-hrefify-hash
+                             nil))))
+    (when toc-org-enable-links-opening
+      (when original-path
+        ;; Org 8.2 and below provides type as "thisfile"
+        (when (equal type "thisfile")
+          (setq ret-path original-path))
+        (when (equal type "custom-id")
+          (setq ret-type "fuzzy")
+          (setq ret-path original-path))))
+    (cons ret-type ret-path)))
+
+(defun toc-org-hrefify-toc (toc hrefify &optional hash)
+  "Format the raw `toc' using the `hrefify' function to transform
+each heading into a link."
+  (with-temp-buffer
+    (insert toc)
+    (goto-char (point-min))
+
+    (while
+        (progn
+          (when (looking-at "\\*")
+            (delete-char 1)
+
+            (while (looking-at "\\*")
+              (delete-char 1)
+              (insert (make-string
+                       (+ 2 (or (bound-and-true-p org-list-indent-offset) 0))
+                       ?\s)))
+
+            (skip-chars-forward " ")
+            (insert "- ")
+
+            (let* ((beg (point))
+                   (end (line-end-position))
+                   (heading (buffer-substring-no-properties
+                             beg end))
+                   (hrefified (funcall hrefify heading)))
+              (insert "[[")
+              (insert hrefified)
+              (insert "][")
+              (end-of-line)
+              (insert "]]")
+
+              ;; maintain the hash table, if provided
+              (when hash
+                (puthash hrefified heading hash)))
+            (= 0 (forward-line 1)))))
+
+    (buffer-substring-no-properties
+     (point-min) (point-max))))
+
+(ert-deftest toc-org-test-hrefify-toc ()
+  (let ((hash (make-hash-table :test 'equal)))
+    (should (equal (toc-org-hrefify-toc "* About\n" 'upcase hash)
+                   " - [[ABOUT][About]]\n"))
+    (should (equal (gethash "ABOUT" hash) "About")))
+  (let ((hash (make-hash-table :test 'equal)))
+    (should (equal (toc-org-hrefify-toc "* About\n* Installation\n** via package.el\n** Manual\n* Use\n* Different href styles\n* Example\n" 'upcase hash)
+                   " - [[ABOUT][About]]\n - [[INSTALLATION][Installation]]\n   - [[VIA PACKAGE.EL][via package.el]]\n   - [[MANUAL][Manual]]\n - [[USE][Use]]\n - [[DIFFERENT HREF STYLES][Different href styles]]\n - [[EXAMPLE][Example]]\n"))
+    (should (equal (gethash "ABOUT" hash) "About"))
+    (should (equal (gethash "INSTALLATION" hash) "Installation"))
+    (should (equal (gethash "VIA PACKAGE.EL" hash) "via package.el"))
+    (should (equal (gethash "MANUAL" hash) "Manual"))
+    (should (equal (gethash "USE" hash) "Use"))
+    (should (equal (gethash "DIFFERENT HREF STYLES" hash) "Different href styles"))
+    (should (equal (gethash "EXAMPLE" hash) "Example"))))
+
+(defun toc-org-flush-subheadings (toc max-depth)
+  "Flush subheadings of the raw `toc' deeper than `max-depth'."
+  (with-temp-buffer
+    (insert toc)
+    (goto-char (point-min))
+
+    (let ((re "^"))
+      (dotimes (i (1+ max-depth))
+        (setq re (concat re "\\*")))
+      (flush-lines re))
+
+    (buffer-substring-no-properties
+     (point-min) (point-max))))
+
+(ert-deftest toc-org-test-flush-subheadings ()
+  (should (equal (toc-org-flush-subheadings "* About\n" 0)
+                 ""))
+  (should (equal (toc-org-flush-subheadings "* About\n" 1)
+                 "* About\n"))
+  (should (equal (toc-org-flush-subheadings "* About\n" 2)
+                 "* About\n"))
+
+  (should (equal (toc-org-flush-subheadings "* About\n* Installation\n** via package.el\n** Manual\n* Use\n* Different href styles\n* Example\n" 0)
+                 ""))
+  (should (equal (toc-org-flush-subheadings "* About\n* Installation\n** via package.el\n** Manual\n* Use\n* Different href styles\n* Example\n" 1)
+                 "* About\n* Installation\n* Use\n* Different href styles\n* Example\n"))
+  (should (equal (toc-org-flush-subheadings "* About\n* Installation\n** via package.el\n** Manual\n* Use\n* Different href styles\n* Example\n" 2)
+                 "* About\n* Installation\n** via package.el\n** Manual\n* Use\n* Different href styles\n* Example\n"))
+  (should (equal (toc-org-flush-subheadings "* About\n* Installation\n** via package.el\n** Manual\n* Use\n* Different href styles\n* Example\n" 3)
+                 "* About\n* Installation\n** via package.el\n** Manual\n* Use\n* Different href styles\n* Example\n")))
+
+(defun toc-org-insert-toc (&optional dry-run)
+  "Looks for a headline with the TOC tag and updates it with the
+current table of contents.
+
+If optional second argument DRY-RUN is provided, then the buffer
+is not modified at all. Only the internal hash-table is updated
+to enable `org-open-at-point' for TOC links.
+
+To add a TOC tag, you can use the command
+`org-set-tags-command' (C-c C-q).
+
+In addition to the simple :TOC: tag, you can also use the
+following tag formats:
+
+- :TOC_2: - sets the max depth of the headlines in the table of
+  contents to 2 (the default)
+
+- :TOC_2_gh: - sets the max depth as in above and also uses the
+  GitHub-style hrefs in the table of contents (this style is
+  default). The other supported href style is 'org', which is the
+  default org style."
+
+  (interactive)
+  (when (eq major-mode 'org-mode)
+    (save-excursion
+      (goto-char (point-min))
+      (let ((case-fold-search t))
+        ;; find the first heading with the :TOC: tag
+        (when (re-search-forward toc-org-toc-org-regexp (point-max) t)
+          (let* ((tag (match-string 1))
+                 (depth (if tag
+                            (- (aref tag 1) ?0) ;; is there a better way to convert char to number?
+                          toc-org-max-depth))
+                 (hrefify-tag (if (and tag (>= (length tag) 4))
+                                  (downcase (substring tag 3))
+                                toc-org-hrefify-default))
+                 (hrefify-string (concat "toc-org-hrefify-" hrefify-tag))
+                 (hrefify (intern-soft hrefify-string)))
+            (if hrefify
+                (let ((new-toc
+                       (toc-org-hrefify-toc
+                        (toc-org-flush-subheadings (toc-org-raw-toc) depth)
+                        hrefify
+                        (when toc-org-hrefify-hash
+                          (clrhash toc-org-hrefify-hash)))))
+                  (unless dry-run
+                    (newline (forward-line 1))
+
+                    ;; insert newline if TOC is currently empty
+                    (when (looking-at "^\\*")
+                      (open-line 1))
+
+                    ;; find TOC boundaries
+                    (let ((beg (point))
+                          (end
+                           (save-excursion
+                             (when (search-forward-regexp "^\\*" (point-max) t)
+                               (forward-line -1))
+                             (end-of-line)
+                             (point))))
+                      ;; update the TOC, but only if it's actually different
+                      ;; from the current one
+                      (unless (equal
+                               (buffer-substring-no-properties beg end)
+                               new-toc)
+                        (delete-region beg end)
+                        (insert new-toc)))))
+              (message (concat "Hrefify function " hrefify-string " is not found")))))))))
+
+;;;###autoload
+(defun toc-org-enable ()
+  "Enable toc-org in this buffer."
+  (add-hook 'before-save-hook 'toc-org-insert-toc nil t)
+
+  ;; conservatively set org-link-translation-function
+  (when (and (equal toc-org-enable-links-opening t)
+             (or
+              (not (fboundp org-link-translation-function))
+              (equal org-link-translation-function 'toc-org-unhrefify)))
+    (setq toc-org-hrefify-hash (make-hash-table :test 'equal))
+    (setq org-link-translation-function 'toc-org-unhrefify)
+    (toc-org-insert-toc t)))
+
+(ert-deftest toc-org-test-insert-toc ()
+  "Test the `toc-org-insert-toc' function"
+
+  (defun toc-org-test-insert-toc-gold-test (content gold)
+    (with-temp-buffer
+      (org-mode)
+      (insert content)
+      (toc-org-raw-toc)
+      (toc-org-insert-toc)
+      (should (equal
+               (buffer-substring-no-properties
+                (point-min) (point-max))
+               gold))))
+  (declare-function toc-org-test-insert-toc-gold-test "toc-org") ;; suppress compiler warning
+
+  (let ((beg "* About\n:TOC:\n drawer\n:END:\n\ntoc-org is a utility to have an up-to-date table of contents in the\norg files without exporting (useful primarily for readme files on\nGitHub).\n\nIt is similar to the [[https://github.com/ardumont/markdown-toc][markdown-toc]] package, but works for org files.\n:TOC:\n  drawer\n:END:\n* Hello\n** Good-bye\n*** Salut\n* Table of Contents                                                     "))
+    (toc-org-test-insert-toc-gold-test
+     (concat beg ":TOC:")
+     "* About\n:TOC:\n drawer\n:END:\n\ntoc-org is a utility to have an up-to-date table of contents in the\norg files without exporting (useful primarily for readme files on\nGitHub).\n\nIt is similar to the [[https://github.com/ardumont/markdown-toc][markdown-toc]] package, but works for org files.\n:TOC:\n  drawer\n:END:\n* Hello\n** Good-bye\n*** Salut\n* Table of Contents                                                     :TOC:\n - [[#about][About]]\n - [[#hello][Hello]]\n   - [[#good-bye][Good-bye]]\n")
+
+    (toc-org-test-insert-toc-gold-test
+     (concat beg ":TOC_1:")
+     "* About\n:TOC:\n drawer\n:END:\n\ntoc-org is a utility to have an up-to-date table of contents in the\norg files without exporting (useful primarily for readme files on\nGitHub).\n\nIt is similar to the [[https://github.com/ardumont/markdown-toc][markdown-toc]] package, but works for org files.\n:TOC:\n  drawer\n:END:\n* Hello\n** Good-bye\n*** Salut\n* Table of Contents                                                     :TOC_1:\n - [[#about][About]]\n - [[#hello][Hello]]\n")
+
+    (toc-org-test-insert-toc-gold-test
+     (concat beg ":TOC_3:")
+     "* About\n:TOC:\n drawer\n:END:\n\ntoc-org is a utility to have an up-to-date table of contents in the\norg files without exporting (useful primarily for readme files on\nGitHub).\n\nIt is similar to the [[https://github.com/ardumont/markdown-toc][markdown-toc]] package, but works for org files.\n:TOC:\n  drawer\n:END:\n* Hello\n** Good-bye\n*** Salut\n* Table of Contents                                                     :TOC_3:\n - [[#about][About]]\n - [[#hello][Hello]]\n   - [[#good-bye][Good-bye]]\n     - [[#salut][Salut]]\n")
+
+    (toc-org-test-insert-toc-gold-test
+     (concat beg ":TOC_1_org:")
+     "* About\n:TOC:\n drawer\n:END:\n\ntoc-org is a utility to have an up-to-date table of contents in the\norg files without exporting (useful primarily for readme files on\nGitHub).\n\nIt is similar to the [[https://github.com/ardumont/markdown-toc][markdown-toc]] package, but works for org files.\n:TOC:\n  drawer\n:END:\n* Hello\n** Good-bye\n*** Salut\n* Table of Contents                                                     :TOC_1_org:\n - [[About][About]]\n - [[Hello][Hello]]\n")
+
+    (toc-org-test-insert-toc-gold-test
+     (concat beg ":TOC_3_org:")
+     "* About\n:TOC:\n drawer\n:END:\n\ntoc-org is a utility to have an up-to-date table of contents in the\norg files without exporting (useful primarily for readme files on\nGitHub).\n\nIt is similar to the [[https://github.com/ardumont/markdown-toc][markdown-toc]] package, but works for org files.\n:TOC:\n  drawer\n:END:\n* Hello\n** Good-bye\n*** Salut\n* Table of Contents                                                     :TOC_3_org:\n - [[About][About]]\n - [[Hello][Hello]]\n   - [[Good-bye][Good-bye]]\n     - [[Salut][Salut]]\n")))
+
+;; Local Variables:
+;; compile-command: "emacs -batch -l ert -l *.el -f ert-run-tests-batch-and-exit && emacs -batch -f batch-byte-compile *.el 2>&1 | sed -n '/Warning\|Error/p' | xargs -r ls"
+;; End:
+
+(provide 'toc-org)
+;;; toc-org.el ends here

From 4c521bbb419914e167c47b6675144b29c06668a4 Mon Sep 17 00:00:00 2001
From: JAremko <w3techplayground@gmail.com>
Date: Mon, 28 Mar 2016 09:13:55 +0300
Subject: [PATCH 8/8] update README.org.template to the new convention

Remove #+HTML_HEAD_EXTRA: <link ... /readtheorg.css" />

:TOC_4_org:noexport: -> :TOC_4_gh:noexport:
---
 core/templates/README.org.template | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/core/templates/README.org.template b/core/templates/README.org.template
index 637fac06a702..3bd5d17e250f 100644
--- a/core/templates/README.org.template
+++ b/core/templates/README.org.template
@@ -1,13 +1,12 @@
 #+TITLE: %LAYER_NAME% layer
-#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../css/readtheorg.css" />
 
 # The maximum height of the logo should be 200 pixels.
 [[img/%LAYER_NAME%.png]]
 
-* Table of Contents                                        :TOC_4_org:noexport:
- - [[Decsription][Description]]
- - [[Install][Install]]
- - [[Key bindings][Key bindings]]
+* Table of Contents                                        :TOC_4_gh:noexport:
+ - [[#decsription][Description]]
+ - [[#install][Install]]
+ - [[#key-bindings][Key bindings]]
 
 * Description
 This layer does wonderful things: