320 lines
13 KiB
Org Mode
320 lines
13 KiB
Org Mode
#+TITLE: How to export Org mode files into awesome HTML in 2 minutes
|
|
#+AUTHOR: Fabrice Niessen
|
|
#+EMAIL: (concat "fniessen" at-sign "pirilampo.org")
|
|
#+DESCRIPTION: Org-HTML export made simple.
|
|
#+KEYWORDS: org-mode, export, html, theme, style, css, js, bigblow
|
|
#+LANGUAGE: en
|
|
#+OPTIONS: H:4 toc:t num:2
|
|
|
|
#+PROPERTY: header-args :padline no
|
|
#+SETUPFILE: setup/theme-readtheorg.setup
|
|
|
|
#+html: <a href="http://opensource.org/licenses/GPL-3.0">
|
|
#+html: <img src="http://img.shields.io/:license-gpl-blue.svg" alt=":license-gpl-blue.svg" />
|
|
#+html: </a>
|
|
#+html: <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=VCVAS6KPDQ4JC&lc=BE&item_number=org%2dhtml%2dthemes¤cy_code=EUR&bn=PP%2dDonationsBF%3abtn_donate_LG%2egif%3aNonHosted">
|
|
#+html: <img src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" alt="btn_donate_LG.gif" />
|
|
#+html: </a>
|
|
|
|
* Tasks :noexport:
|
|
|
|
** TODO Add a demo page
|
|
|
|
Example:
|
|
- http://demo.thi.ng/org-spec/
|
|
- https://raw.githubusercontent.com/thi-ng/org-spec/master/index.org
|
|
|
|
* Overview
|
|
|
|
** Description
|
|
|
|
Though you can easily override CSS stylesheets and add your own HTML themes, we
|
|
can say (or write) that Org mode provides a /basic/ HTML support.
|
|
*Org-HMTL themes* is an open source framework for providing you with a list of
|
|
very nice (cross-browser) themes for all your Org documents. Use them to *style
|
|
your docs*, and your colleagues will come up to tell you that you are a genius!
|
|
|
|
Share this content by tweeting this page:
|
|
|
|
#+html: <script src="http://platform.twitter.com/widgets.js"></script>
|
|
#+html: <a href="https://twitter.com/share" class="twitter-share-button" data-via="f_niessen">Tweet</a>
|
|
|
|
Follow [[https://twitter.com/f_niessen][f_niessen]] on Twitter for updates on Org-HTML themes!
|
|
|
|
** Requirements
|
|
|
|
Org mode version 8 (or later) is required.
|
|
|
|
If such a version is not bundled with your Emacs, install one from ELPA.
|
|
|
|
* Quotations
|
|
|
|
** About Bigblow
|
|
|
|
"Very very nice, I enjoy it a lot." \\
|
|
-- /Ista Zahn/
|
|
|
|
"This is awesome. I love it!" \\
|
|
-- /Rainer M Krug/
|
|
|
|
"This is awesome!!" \\
|
|
-- /Mehul Sanghvi/
|
|
|
|
"This very nice html theme. [...] I cannot use another emacs-theme than your
|
|
[[https://github.com/fniessen/emacs-leuven-theme][emacs-leuven-theme]], and it is going to be probably the same with your html
|
|
theme!" \\
|
|
-- /Joseph Vidal-Rosset/
|
|
|
|
"Thanks a lot for sharing [...] the wonderful Bigblow theme. I create lot of
|
|
specification for other team members to use. It has always been a trouble to
|
|
share and maintain such spec. Now, I can create a much neater spec which is
|
|
available for the team's reference as a webpage." \\
|
|
-- /Shankar R./
|
|
|
|
"I like Bigblow the best. I've exported most of my Org files using this theme
|
|
and published them within my company's intranet. Thanks for sharing this
|
|
wonderful package!" \\
|
|
-- /Richard K./
|
|
|
|
** About ReadTheOrg
|
|
|
|
"OMG. The ReadTheOrg theme for exported HTML from org mode files is eye
|
|
wateringly beautiful. Thank you!" \\
|
|
-- /Rob Stewart/
|
|
|
|
"It is fantastic, so beautiful. I will switch several of my pages over to
|
|
this theme." \\
|
|
-- /Carsten D./
|
|
|
|
"That is incredibly impressive. Thanks for this." \\
|
|
-- /Noah R./
|
|
|
|
"Thank you! I enjoy your themes. The best ones I've ever found." \\
|
|
-- /Kang T./
|
|
|
|
"Awesome theme. Wonderful job. You're doing a wonderful thing --- it will
|
|
enable people (at least those who use Emacs and Org mode) to put together
|
|
on-line reference works in a much-more usable fashion than is currently
|
|
available." \\
|
|
-- /D. C. Toedt/
|
|
|
|
"Extremely useful." \\
|
|
-- /Thomas S. Dye/
|
|
|
|
* Gallery
|
|
:PROPERTIES:
|
|
:ID: 79e0ed21-c3b0-4f00-bdab-29fbff9dcad4
|
|
:END:
|
|
|
|
This is a list of available *HTML themes for Org mode*, which you can use right
|
|
now! Well, I hope to have more than one in a couple of weeks...
|
|
|
|
** Bigblow
|
|
|
|
Bigblow is perfect for your work: it is a clean design aimed at optimal *Org
|
|
mode experience in your browser*. It looks just awesome!
|
|
|
|
#+ATTR_HTML: :width 640
|
|
[[https://www.youtube.com/watch?v=DnSGSiXYuOk][file:bigblow.png]]
|
|
|
|
Click on the image for a quick demo of Bigblow (2:49 min, no audio).
|
|
|
|
Keyboard shortcuts to save time and boost your productivity:
|
|
|
|
| Shortcut | What it does |
|
|
|----------+-----------------------------------|
|
|
| =?= or =h= | Access the *dashboard* |
|
|
| =n= | Move to the *next* main heading |
|
|
| =p= | Move to the *previous* main heading |
|
|
| =b= | Scroll up |
|
|
| =<= | Scroll to top |
|
|
| =>= | Scroll to bottom |
|
|
| =-= | Collapse all |
|
|
| =+= | Expand all |
|
|
| =r= | Go to next task in list |
|
|
| =R= | Go to previous task in list |
|
|
| =q= | Stop reviewing the list of tasks |
|
|
| =g= | Reload the page |
|
|
|
|
** ReadTheOrg
|
|
|
|
ReadTheOrg is a clone of the official -- and great! -- [[https://github.com/snide/sphinx_rtd_theme][theme]]
|
|
used in the [[http://docs.readthedocs.org/en/latest/][Read The Docs]] site. It gives a beautiful and professional style to
|
|
all your Org docs.
|
|
*Thanks to its creator(s)!*
|
|
|
|
#+ATTR_HTML: :width 640
|
|
[[file:readtheorg.png]]
|
|
|
|
#+begin_note
|
|
While the original theme shines on mobile devices as well, ReadTheOrg does not
|
|
stay completely functional.
|
|
|
|
I don't have a lot of time to maintain this project due to other
|
|
responsibilities. Help is welcome to work on that (and eventually improve the
|
|
default structure of the HTML export)!
|
|
#+end_note
|
|
|
|
* Demo
|
|
|
|
I've written a demo page for the themes that provides a maximal working support
|
|
of Org mode syntax.
|
|
|
|
Please see the [[https://github.com/fniessen/refcard-org-mode][Org mode refcard]] page for full examples of headings, code,
|
|
admonitions, footnotes, tables and other details.
|
|
|
|
* Installing a theme
|
|
|
|
Using a theme from the [[id:79e0ed21-c3b0-4f00-bdab-29fbff9dcad4][theme gallery]] for your own Org documents is very easy:
|
|
you just need to clone the Org-HTML themes project, add a =#+SETUPFILE:= directive
|
|
in the preamble to include the CSS and JavaScript files, then export your Org
|
|
mode file to HTML.
|
|
|
|
You can either:
|
|
|
|
- copy the "setup file" of the chosen theme to the directory of your Org files,
|
|
|
|
#+begin_src org :exports code
|
|
,#+SETUPFILE: THEME-NAME.setup
|
|
#+end_src
|
|
|
|
or
|
|
|
|
- use the (relative or absolute) path to the "setup file" (in your Git local
|
|
repository)
|
|
|
|
#+begin_src org :exports code
|
|
,#+SETUPFILE: path/to/Git/repo/setup/THEME-NAME.setup
|
|
#+end_src
|
|
|
|
Then export your Org mode file to HTML with =org-html-export-to-html= or with =C-c
|
|
C-e h h=.
|
|
|
|
** Bigblow
|
|
|
|
In order to use the Bigblow style, just copy the [[file:setup/theme-bigblow.setup][theme-bigblow.setup]] file to
|
|
your project and link to it this way:
|
|
|
|
#+begin_src org :exports code
|
|
,#+SETUPFILE: theme-bigblow.setup
|
|
#+end_src
|
|
|
|
If you prefer, you can add the content of the setup file at the beginning of
|
|
your Org file instead:
|
|
|
|
#+begin_src org :exports code :tangle setup/theme-bigblow.setup
|
|
# -*- mode: org; -*-
|
|
|
|
,#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/bigblow/css/htmlize.css"/>
|
|
,#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/bigblow/css/bigblow.css"/>
|
|
,#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/bigblow/css/hideshow.css"/>
|
|
|
|
,#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/bigblow/js/jquery-1.11.0.min.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/bigblow/js/jquery-ui-1.10.2.min.js"></script>
|
|
|
|
,#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/bigblow/js/jquery.localscroll-min.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/bigblow/js/jquery.scrollTo-1.4.3.1-min.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/bigblow/js/jquery.zclip.min.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/bigblow/js/bigblow.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/bigblow/js/hideshow.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.min.js"></script>
|
|
#+end_src
|
|
|
|
*** Local version
|
|
|
|
Here a local version (using relative paths):
|
|
|
|
#+begin_src org :exports code :tangle setup/theme-bigblow-local.setup
|
|
# -*- mode: org; -*-
|
|
|
|
,#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="styles/bigblow/css/htmlize.css"/>
|
|
,#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="styles/bigblow/css/bigblow.css"/>
|
|
,#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="styles/bigblow/css/hideshow.css"/>
|
|
|
|
,#+HTML_HEAD: <script type="text/javascript" src="styles/bigblow/js/jquery-1.11.0.min.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="styles/bigblow/js/jquery-ui-1.10.2.min.js"></script>
|
|
|
|
,#+HTML_HEAD: <script type="text/javascript" src="styles/bigblow/js/jquery.localscroll-min.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="styles/bigblow/js/jquery.scrollTo-1.4.3.1-min.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="styles/bigblow/js/jquery.zclip.min.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="styles/bigblow/js/bigblow.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="styles/bigblow/js/hideshow.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="styles/lib/js/jquery.stickytableheaders.min.js"></script>
|
|
#+end_src
|
|
|
|
** ReadTheOrg
|
|
|
|
In order to use the ReadTheOrg style, just copy the [[file:setup/theme-readtheorg.setup][theme-readtheorg.setup]] file
|
|
to your project and link to it this way:
|
|
|
|
#+begin_src org :exports code
|
|
,#+SETUPFILE: theme-readtheorg.setup
|
|
#+end_src
|
|
|
|
If you prefer, you can add the content of the setup file at the beginning of
|
|
your Org file instead:
|
|
|
|
#+begin_src org :exports code :tangle setup/theme-readtheorg.setup
|
|
# -*- mode: org; -*-
|
|
|
|
,#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
|
|
,#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
|
|
|
|
,#+HTML_HEAD: <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
|
|
,#+HTML_HEAD: <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
|
|
,#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
|
|
#+end_src
|
|
|
|
* Contributing
|
|
|
|
** Issues
|
|
|
|
Report issues and suggest features and improvements on the [[https://github.com/fniessen/org-html-themes/issues/new][GitHub issue tracker]].
|
|
|
|
** Patches
|
|
|
|
I love contributions! Patches under any form are always welcome!
|
|
|
|
** Donations
|
|
|
|
If you use the org-html-themes project (or any of [[https://github.com/fniessen/][my other projects]]) and feel it
|
|
is making your life better and easier, you can show your appreciation and help
|
|
support future development by making today a [[https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=VCVAS6KPDQ4JC&lc=BE&item_number=org%2dhtml%2dthemes¤cy_code=EUR&bn=PP%2dDonationsBF%3abtn_donate_LG%2egif%3aNonHosted][donation]] through PayPal. Thank
|
|
you!
|
|
|
|
Regardless of the donations, org-html-themes will always be free both as in
|
|
beer and as in speech.
|
|
|
|
** Follow me
|
|
|
|
I have an [[https://twitter.com/f_niessen][f_niessen]] account on Twitter. You should follow it.
|
|
|
|
* License
|
|
|
|
Copyright (C) 2011-2017 Fabrice Niessen.
|
|
|
|
Author: Fabrice Niessen \\
|
|
Keywords: org-mode html themes
|
|
|
|
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 3 of the License, 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
|
|
this program. If not, see http://www.gnu.org/licenses/.
|
|
|
|
#+html: <a href="http://opensource.org/licenses/GPL-3.0">
|
|
#+html: <img src="http://img.shields.io/:license-gpl-blue.svg" alt=":license-gpl-blue.svg" />
|
|
#+html: </a>
|
|
#+html: <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=VCVAS6KPDQ4JC&lc=BE&item_number=org%2dhtml%2dthemes¤cy_code=EUR&bn=PP%2dDonationsBF%3abtn_donate_LG%2egif%3aNonHosted">
|
|
#+html: <img src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" alt="btn_donate_LG.gif" />
|
|
#+html: </a>
|