Exporting org-mode trees to HTML

Each export module uses three levels of configuration:

• publish-org-tree defaults
• overwritten by settings used when adding the module
• overwritten by settings in <module>-export-plist

All Org-mode publishing options are allowed. The format follows the org-publish-project-alist format to allow easy transformation of the different modules into a single org-publish-project-alist.

Project specific modules are best configured as described in the following section, while overrides for the default modules are best done using the 3rd override:

(setq html-export-plist '(:with-toc t))

This will enable TOC generation for the main HTML export module. Note that TOC generation is mainly useful when using the default org exporter - with org-thtml it is often easier to just call org-html-toc in a template. Also see the org-page-toc-level variable.

The export script uses the list dynamic-modules for generated content, and the list static-modules for static content. Any additional modules pushed onto those list will be generated before the default modules - this is useful for generating files the main export pass expects to be present. The format follows the specification for

(push `("sidebar"
        :publishing-directory ,abs-template-directory
        :base-directory ,(plist-get settings :project-directory)
        :exclude ,(regexp-opt '("index.org" "README.org"))
        :include ("sidebar.org")) dynamic-modules)

This example defines an export module called sidebar, excluding the files index.org and README.org, with the resulting html files generated in the absolute path to the template directory - which is the search path for org-thtmls :include macro.

(push `("fontawesome"
        :publishing-directory ,(expand-file-name "fontawesome" (plist-get settings :publish-directory))
        :base-directory ,(expand-file-name "../fontawesome" (plist-get settings :project-directory)))
        static-modules)

This example pushes a local copy of Font Awesome as static files to the subdirectory fontawesome in the publish directory.

Override the page template to use when exporting this page.

Set the depth of the TOC included in some templates. Default is 3.

Note that this needs to be supported in the templates - the relevant templates needs to contain something like this:

{{(org-html-toc org-page-toc-level info)}}

Include a TOC in templates with inline sidebar. Default is t.

Note that this needs to be supported in the templates - the relevant templates needs to contain something like this:

{{(if org-page-toc-in-sidebar (org-html-toc org-page-toc-level info))}}

A list of stylesheets to add to the page. If the path is absolute it will be transformed to a path relative to the project directory. The default value is '().

#+BIND: org-page-stylesheets ("/css/default.css" "/css/pure/pure-min.css")

Note that this needs to be configured in the templates - see add-relative-stylesheets for details.

Use a list of default stylesheets. The default value is nil. This is just a flag for guarding an implementation which needs to be either provided in a customisation file or a template. A possible way to do it in a template is:

    {{
(progn
  (if (and (= (length org-page-stylesheets) 0) org-page-default-stylesheets)
      (setq org-page-stylesheets '("/css/default.css"
                                   "/css/pure/pure-min.css"
                                   "/css/pure/grids-responsive-min.css"
                                   "/css/layouts/blog.css")))
    "")
    }}

Note the "" at the end - the template engine experts strings, so to execute arbitrary code without changing the output the last argument must be an empty string.

A list of stylesheets to add to a page with relative paths. Can be used as alternative to org-page-stylesheets with a more descriptive name.

A list of stylesheets to add to the path with absolute paths. The variable content will not be modified, and should already be absolute paths to the stylesheet locations on a server or filesystem.

The default template to use if no other template is specified.. Defaults to page.html.

The function to call for doing the export. Defaults to org-html-publish-to-html. For using org-thtml set this to org-html-publish-to-templated-html, look at the org-thtml example templates, generade a template directory, and maybe read the advanced templating section.

The main directory to export. Defaults to ., which often is not what you want.

The name of the project. This is mostly used internally, so leaving the default of default is fine in most cases.

The directory to publish the generated files to. Defaults to "" when used directly, which usually is not what you want.

A list of patterns for matching static files to export. Defaults to css eot gif jpg js json less mp3 ogg pdf png scss svg ttf txt woff woff2 yml zip.

A directory containing style sheets and similar files. The default is "" (empty). When not empty this is treated as an additional static module.

Note that the directory name is relative to the project directory. Assuming the following directory structure with the scripts executed in the page directory and the project set to doc the correct value for style_directory is ../style

/home/user/page/
|-- style
|   `-- css
|   `-- templates
`-- doc

A directory containing template files. Setting this usually is only sensible when using org-html-publish-to-templated-html as org_publish_function.

Just like style_directory this is relative to the project directory.

- name: Build page
  uses: aardsoft/publish-org-tree@v1
  with:
    project-directory: doc
    gh-pages: true
  env:
    GH_TOKEN: ${{secrets.GITHUB_TOKEN}}
    pre_excludes: .

This function takes a list of stylesheet files, and generates the matching link statements without altering the path names.

It can be used in a template as follows:

{{(if (> (length org-page-absolute-stylesheets) 0)(add-stylesheets org-page-absolute-stylesheets info))}}

This function takes a list of stylesheets (see org-page-stylesheets and org-page-default-stylesheets), and generates path names relative to the project directory. This enables easy publishing of self-contained pages where CSS can be found by the browser both locally and when published to a web server.

With org-page-stylesheets set either through a user setting file, in a template or in the org header the following org-thtml snippet will include the correct stylesheets:

{{(if (> (length org-page-stylesheets) 0)(add-relative-stylesheets org-page-stylesheets info))}}

Insert the contents of a file without performing macro expansion:

{{(insert-from-file "custom-insert.html")}}

The function takes a list of directories to search for the file as optional second argument. If omitted the file is searched in the project directory, followed by the template directory.