Browse Source

Tutorial: publish to HTML. Please comment.

Sebastian Rose, Hannover, Germany 11 years ago
parent
commit
7d31bfea7e
3 changed files with 439 additions and 2 deletions
  1. 3 1
      org-tutorials/index.org
  2. 434 0
      org-tutorials/org-publish-html-tutorial.org
  3. 2 1
      worgers.org

+ 3 - 1
org-tutorials/index.org

@@ -59,6 +59,8 @@ Also check this page: http://orgmode.org/tutorials.html
 
 - [[file:org-column-view-tutorial.org][Emacs Org's Column View]] by [[http://www.cognition.ens.fr/~guerry/][Bastien]], with an accompanying [[http://www.cognition.ens.fr/~guerry/org-column-screencast.html][screencast]].
 
+- [[file:org-publish-html-tutorial.org][Publishing Org-mode files to HTML]], covering the basics of publishing to HTML.
+
 * Special tasks
 
 ** Natural Project Planning
@@ -98,7 +100,7 @@ Also check this page: http://orgmode.org/tutorials.html
 - Properties and Column View
 - Custom Agenda Commands
 - Export and publishing
-- HTML export
+- HTML export (see above)
 - LaTeX export
 - Embedded LaTeX
 - Using orgtbl-mode in LaTeX

+ 434 - 0
org-tutorials/org-publish-html-tutorial.org

@@ -0,0 +1,434 @@
+#+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
+#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
+#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
+#+TAGS:       Write(w) Update(u) Fix(f) Check(c)
+#+TITLE:      Publishing Org-mode files to HTML
+#+AUTHOR:     Sebastian Rose
+#+EMAIL:      sebastian_rose@gmx.de
+#+LANGUAGE:   en
+#+PRIORITIES: A C B
+#+CATEGORY:   worg-tutorial
+
+# This file is the default header for new Org files in Worg.  Feel free
+# to tailor it to your needs.
+
+[[file:../index.org][{Back to Worg's index}]]
+
+* Introduction
+
+  This Tutorial describes one of many ways to publishing Org-mode files to
+  XHTML. I use the publishing mechanism to keep the =*.html= files separated
+  from my =*.org= files and to access them via web browser. Simply exporting the
+  Org-mode files to HTML would leave them in =~/org/=.
+
+  Throughout this tutorial, let's assume that all our Org-mode files live beneath
+  =~/org/= and we publish them to =~/public_html/=.
+
+* Basics
+
+  The first thing to do is to create the folder =~/org=. This is where my notes
+  files live. Inside =~/org/= I have a folder =css/= for stylesheets and
+  scripts, and a folder calles =img/= (guess what's in there).
+
+  The first file I add to that folder (and to subdirectories later on) is called
+  =index.org=. This name was choosen, since Org will publish the files to those
+  with the basename of the source file plus the extension =.html= [1]. Thus
+  =~/org/index.org= will once be =~/public_html/index.html=.
+
+  Let's add another file and call it =~/org/remember.org=. After adding a
+  stylesheet, =~/org/= looks like this:
+
+  :~/org/
+  :   ├ css/
+  :   │  └ stylesheet.css
+  :   ├ img/
+  :   ├ index.org
+  :   └ remember.org
+
+  When ever you want to add link to a file, do it the usual way. To link from
+  =index.org= to =remember.org=, just write
+  :[[file:remember.org][remember]]
+  Org will convert those links to HTML links for you on export:
+  :<a href="./remember.html">remember</a>
+
+  Same is true for images. To add an image, put it =~/org/img/test.jpg= and
+  refer to it by
+  :[[file:img/test.jpg]]
+
+  You may test your links by clicking on them. To test image links you may also
+  try to turn on =iimage-mode= [3] which works without problems here.
+
+  Optionally, set up the stylesheet as shown in section Special comment section.
+
+* Publishing the /org/ project
+
+  To publish the =~/org/= project to HTML, you'll have to setup the variable
+  =org-publish-project-alist=. I tend to split each project in three basic
+  /components/ as described in the manual. We need these different components,
+  since we want org to use two different functions to publish dynamic content
+  (org => html) and static content like scripts, images, stylesheets or even
+  .htaccess files (org => copy). The third component is just for convenience and
+  tells org to execute the former ones.
+
+  =org-publish-project-alist= may be adjusted using customize (=M-x
+  customize-variable RET org-publish-project-alist RET=), but I prefere to
+  use an extra file to setup my projects, since there are quite a few. To follow
+  this tutorial use the =*scratch*= buffer and put all the Lisp in this section
+  in there.
+
+  First of all, enter this into the =*scratch*= buffer:
+
+  :(require 'org-publish)
+  :(setq org-publish-project-alist
+  :      '(
+  :
+  :       ;; ... add all the components here (see below)...
+  :
+  :      ))
+
+  Be shure to put all the /components/ bellow right there where the comment line
+  is now.
+
+** The /notes/ component
+
+   The /notes/ component publishes all the Org-mode files to HTML. Hence the
+   =publishing-function= is set to =org-publish-org-to-html=. Here is an example
+   of the notes component:
+
+   :("org-notes"
+   :      :base-directory "~/org/"
+   :      :base-extension "org"
+   :      :publishing-directory "~/public_html/"
+   :      :recursive t
+   :      :publishing-function org-publish-org-to-html
+   :      :headline-levels 4             ; Just the default for this project.
+   :      :auto-preamble t
+   :      )
+
+   Note, that =headline-levels= may be adjusted [[Overwrite the defaults][on a per file basis]] to overwrite
+   the default.
+
+   The most important settings here are:
+
+   | base-directory       | The components root directory.                                                                                                |
+   | base-extension       | Filename suffix without the dot.                                                                                              |
+   | publishing-directory | The base directory where all our files will be published.                                                                     |
+   | recursive            | If =t=, include subdirectories - we want that. Subdirectories in =:publishing-directory= are created if they don't yet exist. |
+   | publishing-function  | If and how org should process the files in this component. In this case: convert the Org-mode files to HTML.                  |
+
+** The /static/ component
+
+   The /static/ component just copies files (and their folders) from
+   =:base-directory= to =:publishing-directory= without changing them. Thus
+   let's tell Org-mode to use the function =org-publish-attachment=:
+
+   :     ("org-static"
+   :      :base-directory "~/org/"
+   :      :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf"
+   :      :publishing-directory "~/public_html/"
+   :      :recursive t
+   :      :publishing-function org-publish-attachment)
+
+   *Note* that =:publishing-function= is set to =org-publish-attachment=.
+
+** The /publish/ component
+
+   To publish all with one command, we add the /publish/ component. For this
+   component I usually drop the suffix and just use the basename of the
+   project.
+
+   :     ("org" :components ("org-notes" "org-static"))
+
+   Now =M-x org-publish-project RET org RET= publishes everything
+   recursively to =~/public_html/=. Target directories are created, if they
+   don't yet exist.
+
+** Pooh - can we publish now?
+
+   The good message is *yes, we can*. Just one little hump. Since we've put the
+   definition for our in the =*scratch*= buffer, again, make shure all the
+   /components/ are enclosed by the lines
+
+   :(require 'org-publish)
+   :(setq org-publish-project-alist
+   :      '(
+   :
+   :       ;; ... all the components ...
+   :
+   :      ))
+
+   Move to the end of the first line and press =C-x C-e= to load
+   =org-publish=. Now go to the end of the last line and press =C-x C-e=
+   again. Repeat the last step after every change to your
+   =org-publish-project-alist=.
+
+   To publish your Org-mode files just type
+   =M-x org-publish-project RET org RET= or use one of the shortcuts listed in
+   the manual. If nothing went wrong, you should now be able to point your
+   browser to http://localhost/~user/, if =mod_userdir= is set up. If
+   not, simply navigate to file:///home/user/public_html (you might use
+   /file -> open/ from the file menu of your browser.
+
+
+* Adding directories
+
+  As we add more and more files to =~/org/=, we will soon end up with filenames
+  like '=networking-ssh-sshd-config.org=' or longer. What we need is a
+  directory structure:
+
+  :~/org/
+  :   ├ css/
+  :   │  └ stylesheet.css
+  :   ├ Emacs
+  :   │  ├ index.org
+  :   │  ├ gnus.org
+  :   │  ├ org.org
+  :   │  └ snippets.org
+  :   ├ img/
+  :   ├ index.org
+  :   └ remember.org
+
+  If we hadn't added
+  :      :recursive t
+  in the /notes/ and /static/ components already, we would have to do it now at
+  the latest to export the subdirectories too.
+
+* Overwrite the defaults
+
+  The defaults set by =org-publish-project-alist= may be overwritten. You might
+  want to justify the export properties for single files. Be it the level of
+  headlines, include extry scripts or different stylesheets. Org offers ways to adjust
+  the settings for a single file.
+
+** The export options template
+
+   The first choise is the /export options template/ on top of the file. When in
+   an Org-mode file, =M-x org-insert-export-options-template= does the trick for
+   us. This command adds the following lines to the beginning of our file:
+
+   :#+TITLE:     filename.org
+   :#+AUTHOR:    Firstename Lastname
+   :#+EMAIL:     arthur-dent@example.tld
+   :#+DATE:      <2008-08-25 Mo>
+   :#+LANGUAGE:  en
+   :#+TEXT:      Some descriptive text to be emitted.  Several lines OK.
+   :#+OPTIONS:   H:3 num:t toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:nil skip:nil d:t tags:not-in-toc
+   :#+INFOJS_OPT: view:nil toc:t ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js
+   :#+LINK_UP:
+   :#+LINK_HOME:
+
+   All we have to do now is to alter the options to match our needs. All the
+   options are listed in the wonderful Org-mode manual. Note though, that these
+   options are only parsed on startup (i.e., when you first open the file). To
+   explicitly apply your new options move on any of those lines and press =C-c=
+   twice.
+
+** <<<Special comment section>>>
+
+   CSS style variables cannot be supplied in the export options template. For
+   those a special section may be insert/appended to Org-mode files:
+
+   :* COMMENT html style specifications
+   :
+   :# Local Variables:
+   :# org-export-html-style: "<link rel=\"stylesheet\" type=\"text/css\" href=\"css/stylesheet.css\" />"
+   :# End:
+
+   =css/stylesheet.css= suits the needs for a file in the root folder. Use \\
+   =../css/stylesheet.css= in a subfolder (first level), \\
+   =../../css/stylesheet.css= for a file in a sub-sub-folder.
+
+** Tired of export templates?
+
+  If you're like me, you will soon get tired of adding the same export options
+  template to numerous files and adjust the title and paths in it. Luckily,
+  Org-mode supports laziness and offers an additional way to set up files. All
+  we need is a directory (e.g. =~/.emacs.d/org-templates/=) and create the
+  following files there:
+
+  + =level-0.org= \\
+    This file contains all export options lines and the special comment section
+    for the stylesheet suitable for each file in the projects root folder
+    (=~/org/= or =~/B/= in the examples). Just drop the =#+TITLE= since this
+    will be different for every file and automatically set on export (based on
+    the filename if omitted).
+  + =level-1.org= \\
+     This file contains all export options lines and the special comment section
+     for the stylesheet suitable for each file in a subfolder of the projects
+     root folder (e.g. =~/org/emacs/= or =~/org/networking/=). Just drop the
+     =#+TITLE= again.
+  + Add more files for more levels.
+
+  Now remove the special comment section from the end of your Org-mode files in
+  the project folders (add them to the =level-N.org= files) and change the
+  export options template to
+
+  :#+SETUPFILE: ~/.emacs.d/org-templates/level-N.org
+  :#+TITLE: My Title
+
+  Replace =N= with distance to the root folder (=0=, =1= etc.) of your project
+  and press =C-c= twice while still on this line to apply the
+  changes. Subsequent lines still overwrite the settings for just this one file.
+
+
+
+* More Projects
+
+   As we get used to note taking in org, we might add an =org= directory to most
+   of our projects. All those projects are published as well. Project '=~/B/='
+   is published to '=~/public_html/B/=', '=~/C/=' is published to
+   '=~/public_html/C/=', and so on. This leads to the problem of common
+   stylesheets and current JavaScripts --- and to a new /component/.
+
+** The /inherit/ component
+
+   Once we get tired of copying the static files from one project to another, the
+   following configuration does the trick for us. We simply add the /inherit/
+   component, that imports all the static files from our =~/org/= directory
+   [5]. From now on, it will be sufficient to edit stylesheets and scripts just
+   there.
+
+   :     ("B-inherit"
+   :      :base-directory "~/org/"
+   :      :recursive t
+   :      :base-extension "css\\|js"
+   :      :publishing-directory "~/public_html/B/"
+   :      :publishing-function org-publish-attachment
+   :      )
+   :
+   :     ("B-org"
+   :      :base-directory "~/B/"
+   :      :auto-index t
+   :      :index-filename "sitemap.org"
+   :      :index-title "Sitemap"
+   :      :recursive t
+   :      :base-extension "org"
+   :      :publishing-directory "~/public_html/B/"
+   :      :publishing-function org-publish-org-to-html
+   :      :headline-levels 3
+   :      :auto-preamble t
+   :      )
+   :     ("B-static"
+   :      :base-directory "~/B/"
+   :      :recursive t
+   :      :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf"
+   :      :publishing-directory "~/public_html/B/"
+   :      :publishing-function org-publish-attachment)
+   :
+   :     ("B" :components ("B-inherit" "B-notes" "B-static"))
+
+   *Note*, that the inheritance trick works for non org directories. You might
+   want to keep all your stylesheets and scripts in a single place, or even add
+   more /inheritance/ to your projects, to import sources from upstream.
+
+   *Note* also, that =B-inherit= is the first component in =B=. This is
+   important for this trick to work since the components in =B= are executed in
+   the sequence listed: first get the new stylesheet into =B=, then execute
+   =B-static=.
+
+   *One more Example:*
+
+   As I use [[file:../code/org-info-js/index.org][org-info.js]] and track Worg git, I use "=inherit-org-info-js=" in all
+   my =org= projects:
+
+   :     ("inherit-org-info-js"
+   :      :base-directory "~/develop/org/Worg/code/org-info-js/"
+   :      :recursive t
+   :      :base-extension "js"
+   :      :publishing-directory "~/org/"
+   :      :publishing-function org-publish-attachment)
+   :
+   :     ;; ... all the rest ... ;;
+   :
+   :     ("B" :components ("inherit-org-info-js" "B-inherit" "B-notes" "B-static"))
+   :     ("C" :components ("inherit-org-info-js" "C-inherit" "C-notes" "C-static"))
+   :     ("D" :components ("inherit-org-info-js" "D-inherit" "D-notes" "D-static"))
+   :     ("E" :components ("inherit-org-info-js" "E-inherit" "E-notes" "E-static"))
+
+   ...means, =B= =C= =D= and =E= uses my local stylesheets and always the latest
+   version of =org-info.js=.
+
+
+* Overview
+
+  Once there are lots of files and subdirectories, we're in the need of ways to
+  easily navigate our notes in a browser. What we need now, is an index, an
+  overview of all our note files.
+
+** The /index file/
+
+   Org-modes great publishing also generates a recursive sitemap (called /index
+   file/ in the manual). It's name defaults to =index.org=, which get's in our
+   way, since we have a real startpage as =index.html= [4]. Fortunately there is
+   a configuration option to change the name of the generated sitemap. To
+   generate the sitemap, add these lines to the /notes/ component:
+
+   :      :auto-index t                  ; Generate index.org automagically...
+   :      :index-filename "sitemap.org"  ; ... call it sitemap.org ...
+   :      :index-title "Sitemap"         ; ... with title 'Sitemap'.
+
+   The sitemap will reflect the tree structure of the project. To access the
+   sitemap easily, we could do two things:
+
+   1. Setup the '/UP/' link of the Startpage to link to =sitemap.html= (see next
+      section),
+   2. use the =#+INCLUDE sitemap.org= directive. Most of my Org-mode files
+      contain a chapter called "/Links/" at the end of the file, which contains
+      a subsection =*** Sitemap= that in turn just consists of that
+      diretive. For the =index.org= files in the root directory, I include the
+      /index file/ as the first section.
+
+** org-info.js
+
+   Another way to get additional links to navigate the structure is
+   [[file:../code/org-info-js/index.org][org-info.js]]. Let's set it up like this (either in every file, or in
+   =org-level-X.org=):
+
+   :#+LINK_UP: index.html
+
+   This makes the little /UP/ link ('=h=') point to the =index.html= in the
+   current directory. The =index.org= in the root of the project has the /index
+   file/ as section 2 (which I may reach pressing '=n=' then), and the same
+   option set like this:
+
+   :#+LINK_UP: sitemap.html
+
+   For an =index.org= in a subdirectory:
+
+   :#+LINK_UP: ../index.html
+
+   The =LINK_HOME= always points to the same file:
+
+   :#+LINK_HOME: http://localhost/~user/index.html
+
+   Please consider replacing the last one with a relative path (which will be
+   different for every level of subdirectories).
+
+   No matter where we are, we may always press =H n= and we face the sitemap.
+   No matter where we are, we may always press =h= to move up the tree.
+
+* Further reading
+
+   For more information you might want to read the great [[http://orgmode.org/#sec-5.1][Org-mode manual]]. One of
+   the nicest mailing lists on this planet, BTW, is [[http://lists.gnu.org/archive/html/emacs-orgmode/][emacs-orgmode (archive)]]
+   where you might as well find an answer to your questions.
+
+   Have fun!
+
+
+
+
+---- Footnotes: ---------------
+
+ [1]  You may customize the file suffix for exported files like this:
+ =M-x customize RET org-export-html-extension=.
+
+ [3] ...by typing =M-x iimage-mode RET=. iimage-mode even shows *.svg images, if
+ =librsvg= was present on compile time. FIXME: is this true for emacs22 ?
+
+ [4]  This is primarily because of the sitemap file. Since all directories are
+ listet as links, "/Emacs/" leeds to =emacs/index.html= which should be the page
+ entitled /Emacs/.
+
+ [5]  Files may be copied from arbitrary src directories to any target directory
+ desired.

+ 2 - 1
worgers.org

@@ -1,7 +1,7 @@
 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
-#+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
+#+TAGS:       Write(w) Update(u) Fix(f) Check(c)
 #+TITLE:      The list of Worgers
 #+AUTHOR:     Worg people
 #+EMAIL:      bzg AT altern DOT org
@@ -27,6 +27,7 @@ This is the list of Worgers:
 | Phil Jackson        |                                      |
 | Rustom Moody        |                                      |
 | Sven Bretfeld       |                                      |
+| Sebastian Rose      | sebastian_rose@gmx.de                |
 
 # Feel free to create a page with your name like sven-bretfeld.org