Build a menu for an HTML publish

Build a menu for an HTML publish

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 2015 bytes --]

Hello,

I (continue to) write an online documentation with Org-mode and I want
to build the main navigation menu dynamically. I would like to have your
opinion about what I plan to do.


# What I plan

I plan to write a function that I can assign to the variable
`org-html-preamble` or the publish setting :html-preamble.

This function would take as parameters:

* The brand name and/or the brand logo url

* The main menu structure

And optionally the HTML templates for:

* The brand name and/or logo url

* The menu item

* The menu item with submenu

* The menu surrounding

* The preamble

This function will return the formatted preamble in HTML format.


# What I need to define

I need to choose how the menu structure is defined. An Elisp
alist ? An org-mode file containing only a list ?

If I choose an Elisp alist, do I reuse the Org-mode URL format ? If yes,
is there any org-mode internal function I can use to convert an url like
"file:example.org::*some headline" to "https://example.html#custom-id" ?

With the Elisp alist, I could use keys as menu labels and associated values as
targets. With this solution, I can have different kinds of targets.

If I choose an org-mode file, I cannot control how the HTML export is
built. I will need to write my own function that parse the file, extract
the needed information and format the HTML result. And I need to use a
different extension to avoid having to exclude this file with
org-publish.


# How to pass parameters to this function

If I set a function as value to the variable `org-html-preamble`, this
function will receive a plist containing all the export options.

But can I set custom export option in the publish project alist ?
And when I export manually a file, can I set custom export option on
buffer level ?

Or each option in the plist that my function receive need to be defined
in the HTML export backend level ?


Best regards

-------
Gendre Sébastien

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Build a menu for an HTML publish

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 2282 bytes --]


So, I can partially reply to myself:

Sébastien Gendre <seb@k-7.ch> writes:
> # How to pass parameters to this function
>
> If I set a function as value to the variable `org-html-preamble`, this
> function will receive a plist containing all the export options.
>
> But can I set custom export option in the publish project alist ?
> And when I export manually a file, can I set custom export option on
> buffer level ?
>
> Or each option in the plist that my function receive need to be defined
> in the HTML export backend level ?

If I use org-publish, define a publish project and set a function as
its preamble: Any custom settings in the publish project will be put in the
info plist that the preamble function receive as parameter.

For example, if I define this function:

    (defun my/preamble-test (info)
      "docstring"
      (plist-get info :very-strawbery))


Then I set a publish project like this:

    (setq org-publish-project-alist
          '(("pages-org"
             :base-directory "./Pages/"
             :base-extension "org"
             :recursive t
             :publishing-function org-html-publish-to-html
             :publishing-directory "./public/"
             :html-doctype "html5"
             :html-html5-fancy t
             :very-strawbery "Test 1, test 2, test 3"
             :html-preamble my/preamble-test)))


And finally I publish the project "pages-org", in my published web pages
I get a preamble with the content "Test 1, test 2, test 3".


But if I set the variable `org-html-preamble` to my custom preamble
function like this:

(setq org-html-preamble 'my/preamble-test)

I cannot found a way to define "very-strawbery" value in an Org-mode
buffer and having it used while I manually export the Org-mode buffer.

I tried with "#+very-strawbery: test123" and "#+OPTIONS: very-strawbery:
test123", without success.

Someone have an idea ?



In conclusion, about this point: It is possible to define custom
Org-mode publish settings that will be available to a preamble function.
But, I cannot found a way to set the value of "very-strawbery" that is
used when I export an Org-mode buffer instead of publish it.


Best regards

-------
Gendre Sébastien

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Build a menu for an HTML publish

[Bruno Barbier]

Hi Sébastien,

Sébastien Gendre <seb@k-7.ch> writes:

[...]
> I cannot found a way to define "very-strawbery" value in an Org-mode
> buffer and having it used while I manually export the Org-mode buffer.
>
> I tried with "#+very-strawbery: test123" and "#+OPTIONS: very-strawbery:
> test123", without success.
>
> Someone have an idea ?

IIUC, "BIND" should work.

You put this in the exported file:

#+BIND: a-string "3"
#+BIND: a-number 3

And you can then use these variables directly:

(defun my/preamble-test (info)
   (message "My string: %S" a-string)
   (message "My number: %S" a-number))

This works only if 'org-export-allow-bind-keywords' is t; else Org
ignores the "#+BIND" instructions.

HTH,

Bruno

Re: Build a menu for an HTML publish

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 948 bytes --]


Thank you very much for your reply.

I didn't know the bind part. I will take a look at it.




Bruno Barbier <brubar.cs@gmail.com> writes:

> Hi Sébastien,
>
> Sébastien Gendre <seb@k-7.ch> writes:
>
> [...]
>> I cannot found a way to define "very-strawbery" value in an Org-mode
>> buffer and having it used while I manually export the Org-mode buffer.
>>
>> I tried with "#+very-strawbery: test123" and "#+OPTIONS: very-strawbery:
>> test123", without success.
>>
>> Someone have an idea ?
>
> IIUC, "BIND" should work.
>
> You put this in the exported file:
>
> #+BIND: a-string "3"
> #+BIND: a-number 3
>
> And you can then use these variables directly:
>
> (defun my/preamble-test (info)
>    (message "My string: %S" a-string)
>    (message "My number: %S" a-number))
>
> This works only if 'org-export-allow-bind-keywords' is t; else Org
> ignores the "#+BIND" instructions.
>
> HTH,
>
> Bruno

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Build a menu for an HTML publish

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 2937 bytes --]


Another reply to myself about this specific part:

Sébastien Gendre <seb@k-7.ch> writes:
> But if I set the variable `org-html-preamble` to my custom preamble
> function like this:
>
> (setq org-html-preamble 'my/preamble-test)
>
> I cannot found a way to define "very-strawbery" value in an Org-mode
> buffer and having it used while I manually export the Org-mode buffer.
>
> I tried with "#+very-strawbery: test123" and "#+OPTIONS: very-strawbery:
> test123", without success.
>
> Someone have an idea ?

If I want to define the value of my new option "very-strawbery" in the
level of an Org-mode buffer (or file), I need to add this new option
into the variable `org-export-options-alist` like this:

If I evaluate this:

    (add-to-list 'org-export-options-alist
                 '(:very-strawbery "VERYSTRAWBERY" nil nil))


To quote the docstring of `org-export-options-alist`:

> Alist between export properties and ways to set them.
> 
> The key of the alist is the property name, and the value is a list
> like (KEYWORD OPTION DEFAULT BEHAVIOR) where:
> 
> KEYWORD is a string representing a buffer keyword, or nil.  Each
>   property defined this way can also be set, during subtree
>   export, through a headline property named after the keyword
>   with the "EXPORT_" prefix (i.e. DATE keyword and EXPORT_DATE
>   property).
> OPTION is a string that could be found in an #+OPTIONS: line.
> DEFAULT is the default value for the property.
> BEHAVIOR determines how Org should handle multiple keywords for
>   the same property.  It is a symbol among:
>   nil       Keep old value and discard the new one.
>   t         Replace old value with the new one.
>   ‘space’   Concatenate the values, separating them with a space.
>   ‘newline’ Concatenate the values, separating them with
> 	    a newline.
>   ‘split’   Split values at white spaces, and cons them to the
> 	    previous list.
>   ‘parse’   Parse value as a list of strings and Org objects,
>             which can then be transcoded with, e.g.,
>             ‘org-export-data’.  It implies ‘space’ behavior.
> 
> Values set through KEYWORD and OPTION have precedence over
> DEFAULT.

After adding my new export option, I can use it by writing this on my
Org-mode buffer/file I want to export:

    #+VERYSTRAWBERRY: TestTestTest


After exporting my Org-mode buffer/file to HTML, I get a preamble with
the text "TestTestTest".


Note :

* Having a buffer option for "very-strawbery" is useful for export
  but also for publish. I can set a value that will override the
  value set in the Org-publish project settings.

* The variable `org-export-options-alist` is made for options who are
  back-end agnostic. But I didn't found a way to modify export options of
  HTML backend without redefine a new backend.


Best regards

-------
Gendre Sébastien


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]