ox-twbs

ox-twbs copied to clipboard

• ox-twbs

** Summary

Export [[http://orgmode.org/][org-mode]] docs as HTML compatible with [[http://getbootstrap.com/][Twitter Bootstrap]].

** Example

The following [[https://raw.githubusercontent.com/marsmining/ox-twbs/master/example/eg0.org][org source]] exports to [[http://clubctrl.com/org/prog/ox-twbs.html][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 [[http://osscdn.com][osscdn]].

Derived from the built-in HTML back-end of [[http://www.gnu.org/software/emacs/][GNU Emacs]], =ox-html.el=, which was written by Carsten Dominik and Jambunathan K.

** Install

*** via package.el

Latest builds available on [[http://melpa.org/#/][MELPA]] and for a bit more stability, use [[http://stable.melpa.org/#/][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 [[http://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.html][the org-mode docs]] on setting up your project. An example configuration might look like:

#+BEGIN_SRC elisp (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 ))) #+END_SRC

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:

#+BEGIN_SRC elisp (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")))) #+END_SRC

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

#+BEGIN_SRC elisp (add-hook 'org-mode-hook (lambda () (local-set-key (kbd "s-\") 'my-org-publish-buffer))) #+END_SRC

** General Org Tips

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

: #+TITLE: My Doc

To quickly add blocks, check this [[http://orgmode.org/manual/Easy-Templates.html#Easy-Templates][easy template]] section of org manual.

Be sure to understand how to [[http://orgmode.org/manual/Editing-source-code.html#Editing-source-code][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 [[http://orgmode.org/manual/Export-settings.html][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 [[https://github.com/marsmining/ox-twbs/blob/d5ae9c3fb224d081d59d3686d619edf152523f09/ox-twbs.el#L987-L1002][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 [[http://orgmode.org/manual/HTML-export.html#HTML-export][HTML export]]
• Improve Affix.js plugin scroll-spying/following
• Ensure this package works well with org's sitemap function