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

["Sébastien Gendre" <seb@k-7.ch>]

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


Hello. Thank you for your reply, I add mines after the quotes.


Ihor Radchenko <yantar92@posteo.net> 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 and add a subfolder named "pagefind/".

This subfolder contain all the JS, CSS and a data needed to add a
functioning search field to each webpage.

To add the search field, you only need to add this on the webpages:

    <link href="/pagefind/pagefind-ui.css" rel="stylesheet">
    <script src="/pagefind/pagefind-ui.js"></script>
    <div id="search"></div>
    <script>
        window.addEventListener('DOMContentLoaded', (event) => {
            new PagefindUI({ element: "#search", showSubResults: true });
        });
    </script>

For readers who want more information about Pagefind, here is its
documentation:

https://pagefind.app/docs/


>> 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.


>>   - 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)


>> - 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


>> - 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

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".

But, maybe this question/answer block is a big feature and need to be
kept for the future.


>> - 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.


>> - Bibliography on a dedicated webpage when using org-publish
>
> Probably fits within "multipage export" feature we are discussing now
> https://list.orgmode.org/orgmode/ZoUdiTfbYqzPwTiX@orm-t14s/T/#u

I will take a look.


>> - 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 ?


>> - 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)


>> And the menu is made from an org-mode file where first level heading
>> become menu item and links are simple org-mode links.
>
> This kind of idea should be discussed in more details.
> I see it as a way to define special HTML markup from Org markup, but it
> is a question how to implement such a feature.

I agree. I started with an Org-mode file to do some tests, but it
should be discussed in more details.

From what I understand, the need is to have a simple way to define a
website menu that:

  * Can have 2 levels

  * Each entry can be a link to an exported Org document or any raw link

  * We should avoid link on a menu entry who contain a sub menu,
    otherwise it become difficult to use on a touchscreen



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.



Best regards

-------
Gendre Sébastien

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