* Build a menu for an HTML publish
@ 2024-08-12 0:45 Sébastien Gendre
2024-08-12 16:56 ` Sébastien Gendre
0 siblings, 1 reply; 5+ messages in thread
From: Sébastien Gendre @ 2024-08-12 0:45 UTC (permalink / raw)
To: Org mailing list
[-- 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 --]
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Build a menu for an HTML publish
2024-08-12 0:45 Build a menu for an HTML publish Sébastien Gendre
@ 2024-08-12 16:56 ` Sébastien Gendre
2024-08-13 8:50 ` Bruno Barbier
2024-08-13 9:56 ` Sébastien Gendre
0 siblings, 2 replies; 5+ messages in thread
From: Sébastien Gendre @ 2024-08-12 16:56 UTC (permalink / raw)
To: Org mailing list
[-- 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 --]
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Build a menu for an HTML publish
2024-08-12 16:56 ` Sébastien Gendre
@ 2024-08-13 8:50 ` Bruno Barbier
2024-08-13 10:58 ` Sébastien Gendre
2024-08-13 9:56 ` Sébastien Gendre
1 sibling, 1 reply; 5+ messages in thread
From: Bruno Barbier @ 2024-08-13 8:50 UTC (permalink / raw)
To: Sébastien Gendre, Org mailing list
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Build a menu for an HTML publish
2024-08-12 16:56 ` Sébastien Gendre
2024-08-13 8:50 ` Bruno Barbier
@ 2024-08-13 9:56 ` Sébastien Gendre
1 sibling, 0 replies; 5+ messages in thread
From: Sébastien Gendre @ 2024-08-13 9:56 UTC (permalink / raw)
To: Org mailing list
[-- 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 --]
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Build a menu for an HTML publish
2024-08-13 8:50 ` Bruno Barbier
@ 2024-08-13 10:58 ` Sébastien Gendre
0 siblings, 0 replies; 5+ messages in thread
From: Sébastien Gendre @ 2024-08-13 10:58 UTC (permalink / raw)
To: Bruno Barbier; +Cc: Org mailing list
[-- 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 --]
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2024-08-13 10:59 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-08-12 0:45 Build a menu for an HTML publish Sébastien Gendre
2024-08-12 16:56 ` Sébastien Gendre
2024-08-13 8:50 ` Bruno Barbier
2024-08-13 10:58 ` Sébastien Gendre
2024-08-13 9:56 ` Sébastien Gendre
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).