ox-twbs

Summary

Export org-mode docs as HTML compatible with Twitter Bootstrap.

Example

The following org source exports to this html.

Description

Output your org-mode docs with a simple, clean and modern look.

This library implements a new HTML back-end for exporting org-mode docs as HTML compatible with Twitter Bootstrap. By default, HTML is exported with jQuery and Bootstrap resources included via osscdn.

Derived from the built-in HTML back-end of GNU Emacs, ox-html.el, which was written by Carsten Dominik and Jambunathan K.

Install

via package.el

Latest builds available on MELPA and for a bit more stability, use MELPA Stable. You can install ox-twbs using the following command:

M-x package-install [RET] ox-twbs [RET]

If the installation doesn’t work try refreshing the package list:

M-x package-refresh-contents [RET]

Manual

Put ox-twbs.el in your load path and require it. Alternatively, open ox-twbs.el in your buffer and run package-install-file, which will compile and install the package in your package folder.

Usage

Open or create an org file and run org-twbs-export-to-html. This will create an HTML file in the same dir as your org file.

You will more likely want more control and automation of the export process. You can read the org-mode docs on setting up your project. An example configuration might look like:

(setq org-publish-project-alist
      '(("org-notes"
         :base-directory "~/org/"
         :publishing-directory "~/public_html/"
         :publishing-function org-twbs-publish-to-html
         :with-sub-superscript nil
         )))

Using the above config, you can run: org-publish-all

And you might create a function which publishes the current buffers file and opens it in your system’s default browser. Here is what I use in my emacs config:

(defun my-org-publish-buffer ()
  (interactive)
  (save-buffer)
  (save-excursion (org-publish-current-file))
  (let* ((proj (org-publish-get-project-from-filename buffer-file-name))
         (proj-plist (cdr proj))
         (rel (file-relative-name buffer-file-name
                                  (plist-get proj-plist :base-directory)))
         (dest (plist-get proj-plist :publishing-directory)))
    (browse-url (concat "file://"
                        (file-name-as-directory (expand-file-name dest))
                        (file-name-sans-extension rel)
                        ".html"))))

And bind the above command. I’m on OSX and happen to use CMD-\.

(add-hook 'org-mode-hook
          (lambda ()
            (local-set-key (kbd "s-\\") 'my-org-publish-buffer)))

General Org Tips

To specify a title of your org doc, other than the default:

#+TITLE: My Doc

To quickly add blocks, check this easy template section of org manual.

Be sure to understand how to edit source code blocks.

Controlling depth of section numbers, table of contents and headings can be controlled per document via a declaration like the following:

#+OPTIONS: num:5 whn:2 toc:4 H:6

And to set these via your publish configuration using the org-publish-project-alist, the options would be :section-numbers, :headline-levels and :with-toc.

The above options are described in the export settings section of the orgmode manual. This component introduces a new setting whn for per document, and :with-headline-numbers for publish config, which controls the display of section numbers. To disable, set to nil, to enable, set to t, and to control depth of display, use a whole number.

Note re: latest Org 8.3.x

Traditionally preventing section numbers from display was accomplished via the :section-numbers option, however, in 8.3.x, setting it to nil now also eliminates the numbering from the parsed document, which then breaks toc and linking. Therefore, this module introduces a new option :with-headline-numbers which can be used for toggling display of section numbers.

Customize

The first place to look is in the definition of org-twbs-head. You can set this on a per-file basis using #+HTML_HEAD:, or for publication projects using the :html-head property.

Todo

Contributions are welcome! A list of potential fixes and enhancements follows:

Allow users to more easily add a Twitter Bootstrap theme
Document areas where this package deviates from org-mode manual on HTML export
Improve Affix.js plugin scroll-spying/following
Ensure this package works well with org’s sitemap function

marsmining/ox-twbs