Re: Enhancing the HTML exporter: Create a new backend or contribute to the upstream

[Ihor Radchenko <yantar92@posteo.net>]

Before I continue with my replies, I'd like to add one general comment.

You are suggesting a number of new diverse features.
Ideally, it is better to discuss and add them separately.
Especially, when we move ahead and discuss the concrete implementations
or patches.

I will also provide some links to existing discussions on similar
features. It is a good idea to continue those discussions, so that we do
not spread things across the mailing list too much.

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

>>>   - A search field for an local search engine
>>
>> +1, but I would like to know more details - will it be something you
>> want to ship with Org mode, as JS?
>
> For now, I have done successful testes with Pagefind. When you execute
> the "pagefind" binary on the root of the generated website, it will do
> the indexation of the HTML pages ....
>
> This subfolder contain all the JS, CSS and a data needed to add a
> functioning search field to each webpage. ...
>
>>> For now, the search engine use the software Pagefind:
>>> https://pagefind.app
>>
>> It is a very young project (2022). Any alternatives? Preferably,
>> well-established.
>
> I can search for another project.
> 
> I don't know how many work it would be needed to develop a search motor
> specifically for Org-mode. But doing the indexing on Org-mode files could
> let the user control the indexation of each page and section directly
> from them. With buffer settings and heading properties.

Let me clarify.
Unless an indexer is very simple, we do not really want it in Org - it
will put a lot of extra load on maintainers.

On the other side, we do not want to tie things to some project that
may fade out in 10 years into the future.

The way I see search engine support in Org mode is either:

1. Using some really established project that we can expect to last for
   many years.

2. Implementing pluggable search support where users can choose which
   indexer/searcher to use

(2) will be the best.

So, may you please search across available search engines and see what
they have in common. Then, we can work out some infrastructure that is
generic enough to plug a custom engine.

Then, pagefind can be the default (it is MIT license - GPL compatible),
unless someone proposes a better alternative.

>>>   - A main navigation menu, built from a dedicated org-mode file
>>
>> Maybe, but that's probably a feature for org-publish.
>> Maybe we can somehow integrate it with TOC functionality.
>
> I was thinking of the main navigation menu to navigate in the website,
> between web pages, while the TOC is for navigate on one page.
>
> Integrate the 2 is a good idea, it can help building one unified menu on
> the side panel. But separate the 2 let more flexibility to users who
> want to customize the exported web page. And, maybe, it can help user to
> navigate too. I'm not an UX expert.
>
> For example, on Jupyterbook and Sphink generated webpages, the website
> navigation menu is on the left and the page table of content is on the
> right. (On desktop)

I see. I do not mind a site-wide navigation menu.

I think that we may do it in the following way:

1. Provide an option for users to specify the html source of such menu

2. Provide an option to generate global site menu from org-publish, or
   from a specified Org file

I'd like to provide html source approach because I saw some people using
python scripts to generate such global menus. It would be nice to
support such (existing) use case.

>>> - A more "modern" look
>>
>> That can be anything, so I need more details to say anything.
>
> My inspiration for "modern" look are:
>
> * Jupyterbook: https://jupyterbook.org
>
> * The Furo theme for Sphinx: https://github.com/pradyunsg/furo

Sorry, but that's not what I am asking about.
I do not care much about specifics of the color scheme and so.
I am looking to know what specific visual features you want to add.

From a quick glance, there is a toggle between dark/ligh themes. What else?

>>> - More special blocks available like:
>>>   - A question/answer bloc, where the answer is hidden
>>>   - Important, warning and tip blocks
>>>   - A generic hide-show bloc
>>
>> Are you referring to extending the default CSS? Something else?
>
> At first, I was thinking of extending the CSS theme. But after
> reflection, I think it would be better to introduce new kind of Org-mode
> block. So we can manage their exportation to other format, like LaTeX.
>
> My inspiration for the 2 last kind of blocks are from "Special Content
> Blocks", from Jupyterbook:
> https://jupyterbook.org/en/stable/content/content-blocks.html

Maybe something like
https://list.orgmode.org/orgmode/8B86B788-3B46-4879-ABDB-3AD04A7EC0CE@gmail.com/
?
If yes, we may continue discussion there.

> For the question/answer, the idea is to facilitate the creation of
> exercises. When a user write a lesson on a subject and want to give the
> readers some practice. It would be nice to have a way to indicate which
> text is the question and which text is the answer.
>
> On the export, a question and its answer are rendered inside a frame,
> with a question number. The question can have sub-questions, like 2.a,
> 2.b, etc.

> And in case of HTML export, the answer could be hidden and shown when
> user click on a button "show reply".

In HTML5 export, ox-html does support details and summary special
blocks. Will it be good enough?

See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary

>>> - Tab to select which content to see
>>
>> May you elaborate?
>
> My inspiration are the "Tab Content" from Jupyterbook:
> https://jupyterbook.org/en/stable/content/components.html#tab-content
>
> A use case could be in a documentation, when the writer want to share a
> same example in multiple languages.
>
> But, as for the previous blocks, it maybe need a new Org-mode element.
> So we can also manage it when export to LaTeX or other formats.

Why do we need a new element here? Maybe just an export option for, say, list?

>>> - A button to download the Org-mode file source of a webpage
>>
>> On top panel? It might be useful as default top/side panel settings in
>> org-publish. Not sure.
>
> I was more thinking to put this button at the top of the content, as
> it's the source of the webpage. While the top/side panel is more related
> to the website itself.
>
> But it make sense to have it as an org-publish setting. For example, a
> ":html-pulish-source". When set as "t", the HTML publish function copy
> the Org-mode source beside the generated HTML file. And include a link
> in the HTML file to the copied Org-mode file.
>
> Or is it better to use the "org-publish-attachment" function to copy the
> Org-mode files ?

:htlm-publish-source sounds reasonable.

>>> - Possibility to set the home page, when there is no index.org
>>
>> May you elaborate?
>
> Today, if you publish multiple Org-mode file and one of them are named
> "index.org", this file will be exported to "index.html". And it will
> become the default web page when someone visit your website without
> specifying a path.
>
> But if you don't want to create a file named "index.org", but define
> another document as the website home page, it would be nice to have the
> possibility to define it.
>
> For example: The user set an Org-publish option ":html-home-document" to
> "Introduction.org". After doing the publishing, an "index.html" file is
> automatically created on the output folder and this file contain a
> redirection to "Introduction.html". (If no index.org already exist)

You can simply specify #+EXPORT_FILE_NAME for your desired index.html
file, even when the Org source has different name.

For redirection, it can be done my multiple means, not necessary via
dedicated redirect page.

I feel that what you are suggesting here is way too niche as a general
upstream feature.

> While we talk about the "org-html-publish-to-html":
>
> I use a lot the Org-mode attachment function for files I want to use
> inside a webpage. Images, archives, sounds, videos, etc. In a lot of
> formats. And I manage them separately from the general static files
> (CSS, JS, etc).
>
> On the Org-mode side:
>
>   1. I attach a file to the section I want to use it, with the copy or
>      move action
>
>   2. I create an "attachment" link to the file
>
>
> For the static files, like CSS, JS and website logo:
>
>   1. I create a "static/" folder, separated from the folder where the
>      Org-mode files are written
>
>
> On the Org-publish projects
>
>   1. I define a project that use "org-html-publish-to-html" to export
>      each Org-mode document to a web page
>
>   2. I define a second project that use "org-publish-attachment" on the
>      same folder, with all the used extension, only to publish the files
>      who are inside the "data/" subfolder
>
>   3. I define a third project that also use "org-publish-attachment" but
>      for the static files
>
> It feel strange to do the publication of attached file on a separate
> project while "org-html-publish-to-html" already manage a part of the
> attachment management by taking care of the "attachment" links. And also
> to use a publish function named "org-publish-attachment" to publish
> static files.
>
> What do you think about adding an option in "org-html-publish-to-html"
> to copy each file attached to and linked from an Org-mode heading ?
> Independently of its extension. But maybe we need to rename the function
> "org-publish-attachment" to "org-publish-static-files" to avoid
> confusion.

That might be useful, yes.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>