From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2.migadu.com ([2001:41d0:303:e16b::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id uElZJ8pI1WaOXQAAe85BDQ:P1 (envelope-from ) for ; Mon, 02 Sep 2024 05:10:34 +0000 Received: from aspmx1.migadu.com ([2001:41d0:303:e16b::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2.migadu.com with LMTPS id uElZJ8pI1WaOXQAAe85BDQ (envelope-from ) for ; Mon, 02 Sep 2024 07:10:34 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=none; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1725253834; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post; bh=KCmCwAJUUI5HyeRCFB3JkFmW9JtvzG9Cu33+xdRAiS8=; b=k/ZxRGffoZeDMeZdca+MRkhMfPmkEYt1D+Yd4wwyq4VI73AEW0A///47B5eNfNHoaNeNE5 SJMrYzYYrJW3EsdMrLFPXLKu4QGOnjoHPYYhyQEPfSbCjfVlmq5aOLNcQfIbghqksksrOi Au4yaGtySeJjhfHkkcf59cZVjsmCZWRZYtbXVW8Rw7hm9AbPROtwZqnxM7PtazPen1ndCZ MVrABLwG4vi4uh8lm0VV9f9MzvyHSt5QeU/HSQQsT3tkiKjQlMZg9SCgO3Spdql58ueCgV cjF20n9GXplhf2XYSE3f+VrKhUPGCM+bgwsfAzIWWidHl2RkAmLixA1EEsw8CA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=none ARC-Seal: i=1; s=key1; d=yhetil.org; t=1725253834; a=rsa-sha256; cv=none; b=ZarIGv9fmoiylt4+mBAFShOYVkTvoSTHhknrM/9vkXHd9ZDzSWSauRQevLx3qU3JkekXc6 Te/qsfkrkIRyBRxXcUK6AgAZnlC70GjSFZ4pO1fzB8E4zKih/s84Hv94yUeezL/oN/zb4e VgVUmVzZPrHA3A3t3nt52xZ15xJhmeinAu23WT5M4fRduZZjXfns17HQdqWOK7rYcRvL4i Cy4vbcegyzXbTYyN4B9PosgwGVyKiMEQI/8y7gMqF9uZCQDP2Da56IDVlcgw9lL+S3ypGg eX0QjcNQ/t+KOTVOYm8Zkalph+TlLxLYCwMPQiLoWFXOBrS+mYKtOTivvstTUQ== Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 1EC1416EF4 for ; Mon, 2 Sep 2024 07:10:34 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1skzJp-0003kM-GK; Mon, 02 Sep 2024 01:09:37 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1skzJn-0003kE-Eu for emacs-orgmode@gnu.org; Mon, 02 Sep 2024 01:09:35 -0400 Received: from k-7.ch ([185.31.100.96]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1skzJk-0008NR-LU for emacs-orgmode@gnu.org; Mon, 02 Sep 2024 01:09:35 -0400 Received: from van (_gateway [192.168.1.1]) (Authenticated sender: seb) by k-7.ch (Postfix) with ESMTPSA id E4B64E810D; Mon, 2 Sep 2024 07:09:29 +0200 (CEST) From: =?utf-8?Q?S=C3=A9bastien_Gendre?= To: Ihor Radchenko Cc: General discussions about Org-mode , orgmode@tec.tecosaur.net Subject: Re: Enhancing the HTML exporter: Create a new backend or contribute to the upstream In-Reply-To: <871q23qsb3.fsf@localhost> (Ihor Radchenko's message of "Sun, 01 Sep 2024 15:58:40 +0000") References: <87h6b51llh.fsf@k-7.ch> <871q23qsb3.fsf@localhost> User-Agent: mu4e 1.12.1; emacs 29.4 Date: Mon, 02 Sep 2024 07:09:29 +0200 Message-ID: <87a5gqzlo6.fsf@k-7.ch> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" Received-SPF: pass client-ip=185.31.100.96; envelope-from=seb@k-7.ch; helo=k-7.ch X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Country: US X-Migadu-Flow: FLOW_IN X-Migadu-Queue-Id: 1EC1416EF4 X-Migadu-Scanner: mx13.migadu.com X-Migadu-Spam-Score: -8.38 X-Spam-Score: -8.38 X-TUID: kOnfy26lpvWu --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hello. Thank you for your reply, I add mines after the quotes. Ihor Radchenko 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:
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=C2=A0? >> - 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=20what 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=C2=A0? 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 =2D------ Gendre S=C3=A9bastien --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQI/BAEBCAApFiEEaA9vw9ypVj1kP0tAtYb3x3I54p4FAmbVSIkLHHNlYkBrLTcu Y2gACgkQtYb3x3I54p5jag//Z2Mcaf7GkmUluRSE3FyK1lEQFkEGt313GM4PN3ho iirGXz1ATr7k9bJjOULX8Xy+oEMRivGXQ6s+HNTSmCqRsIqICUQadNmMp7cR1D8I St5W/g3gWMzGWNUxKL9q2xoDWDQifa0LDdgifD7HSayiwEs0VykQ2h+GfF/o+OPz q6nXO1/b9IrAurzpso1rknCyAVTN5ZWiavGt3i1WpxbG4T/7CTkEILNm6f2hxXUf FRRVL9kX3+J6J2+CBzr498AnPJbEZWALZhsHS+G0Ir4fx6e2h6ifMSIo5yBCV+Nk I0jw/AjjHmTSEbfQa8gcTsFKhBTd7vZ+boVCAGONMN/ZzBQTTh80lGi/Em/X2h0x a8nMDH3LFEsdPkB5vVWP6oQtS3NwWLJ+itXWDMnFiYvFRftsPAEoL3dOyf1MVXST l6jIOXH0uoxPmk3cU5wAG13Bvfagwz17MbP/5N4VmFt3uNBClXKjixyVCPYdgHso BSbl50M9EivB8yqmwH/ZDnHUAWEeOrxo76kmOKZwib560nTMNRgheL/KCDZsvkxD 7ml4tKrUJMW6DO0wdVxWTMX+mCmy5QMjsospOXp3OybIV+Skuz2tshe/x6L9mrHe j75zAjB3u5uYQxEbDQMgMjgcAiPichTtuAoey72kLic72J/8XAWhWpQ9Smt2SCT3 hK4= =DygD -----END PGP SIGNATURE----- --=-=-=--