From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id oCUwKK4+3GY2EgAAqHPOHw:P1 (envelope-from ) for ; Sat, 07 Sep 2024 11:53:18 +0000 Received: from aspmx1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0.migadu.com with LMTPS id oCUwKK4+3GY2EgAAqHPOHw (envelope-from ) for ; Sat, 07 Sep 2024 13:53:18 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=XN28ukTS; dmarc=pass (policy=none) header.from=posteo.net; 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" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1725709998; 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: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=kRIoyYInLjcP0HeO+GWmtUt+2CkmUeAu8VhJlvYF/xc=; b=N7k7NCWBT2KpFANVtDK9QuP8DxQCP2fYWwhOlaEUutkUZjZJ65chOe9TQyICy8/8ufWBq8 t88EYUMTyGmJprMHBc4iJlbICyS45r8UuelHu0blLEIXRVkJyN9DORwaFPwJKo8YiHqklM Ogj4MA3HDs/COreOPpINgJ+FlEOJZ9THFa8dyrJrlpED1Blix8pw4l7uZXPY8hfqiTj1Ih mo4vhbMOAmP7hwv5TgOqZXISqw8qdE9mLapqqGdAY9GYnzf/9qXI9VtAQTiel+lUDhl8Wk TH4sqtg/dQUyI/PdXHUkdThmh5mYPl7Mh2wJx8KhvypPuzrnr0GmHGbIFBsqCg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1725709998; a=rsa-sha256; cv=none; b=oY0neblRFCc012GoeQI2+rmJcOiH4YreAQsS6Z2FoaSfYnXaIXa9mnatCF2p84BkDBKOoi UiGJrgB1Wz01fS4MM4BX+HKUiCvZfaq6NMFD5W+z7eTQ08bUTVKaSqMfqawAtvRz4eavO2 63i/aIHRGclNWb1mKrxrAOllVtThXU+0kSJ7Bd9ced3mqxsLTfbMvPOROa7oZuauYZ6V/m gW03Tj0LzeyZygsNoWZEg9/p3OcCMjAz8SRj/zXmqeSQ3VG4Y6KsuBLRt2ireXj7G/Oni6 XszmhYQszjMpjkq5QwV+4oBFk1NbO558YcF/T1u06TUX6lWqf37LUs++MkIJhw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=XN28ukTS; dmarc=pass (policy=none) header.from=posteo.net; 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" 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 55F1579B67 for ; Sat, 7 Sep 2024 13:53:17 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1smtzJ-0005WJ-Nf; Sat, 07 Sep 2024 07:52:21 -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 1smtzH-0005W6-PK for emacs-orgmode@gnu.org; Sat, 07 Sep 2024 07:52:19 -0400 Received: from mout02.posteo.de ([185.67.36.66]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1smtzD-00024Z-G8 for emacs-orgmode@gnu.org; Sat, 07 Sep 2024 07:52:19 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 0AFB6240101 for ; Sat, 7 Sep 2024 13:52:11 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1725709932; bh=ALx9ptT0x2L/gPCQQYPT/45zyu9CAuuO9xCFCepL7b8=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type: Content-Transfer-Encoding:From; b=XN28ukTSz7akVcYb6SWBpVSdylQxj5d70dIVabOVNDurg6arX4yDGh7jwwOjQkZ4C 5ntnbU4aUPFZ8MUDwDwvxfe2lJSfAcCNmL+nUSXynNGuz4wdPLDQgssxF4XrP3MH2r S+oy/qPqMLyR985n76vt6a0ZZUIuLp7Ppe22gqx8m30OQ82Ac+KJeKkiAy1IgKj4tT Da26boPKn0VFypqtgku2Q7ZgNOl6QD29KxJdV/R/dIINaOTKJAE3u6Uqb35lL1JuN2 OvHNK1UeHZhu8KfG/qZXOQW13MnerMfyNGGwM50kVDkzZwfUEwa4h25NZnxvqV31xo 3Tm/rkS9caDJg== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4X1BKR3VVTz6tvc; Sat, 7 Sep 2024 13:52:11 +0200 (CEST) From: Ihor Radchenko To: =?utf-8?Q?S=C3=A9bastien?= Gendre 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: <87a5gqzlo6.fsf@k-7.ch> References: <87h6b51llh.fsf@k-7.ch> <871q23qsb3.fsf@localhost> <87a5gqzlo6.fsf@k-7.ch> Date: Sat, 07 Sep 2024 11:53:39 +0000 Message-ID: <87frqbel30.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=185.67.36.66; envelope-from=yantar92@posteo.net; helo=mout02.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 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-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Queue-Id: 55F1579B67 X-Migadu-Scanner: mx12.migadu.com X-Migadu-Spam-Score: -9.71 X-Spam-Score: -9.71 X-TUID: WUniCf3toWYl 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=C3=A9bastien Gendre 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. >=20 > 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, li= st? >>> - 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? :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=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. That might be useful, yes. --=20 Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at