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,
which was written by Carsten Dominik and Jambunathan K.
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]
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.
Open or create an org file and run
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:
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
(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
The above options are described in the export settings section of the
orgmode manual. This component introduces a new setting
whn for per
:with-headline-numbers for publish config, which
controls the display of section numbers. To disable, set to
enable, set to
t, and to control depth of display, use a whole
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.
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
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