Some hacks on top of org-publish

Some hacks on top of org-publish

[Nikolaos Chatzikonstantinou]

Hello,

I spent the past couple of days hacking together this new blog based
on org-publish that I'd like to show you (comments welcome!):

Blog: <https://createyourpersonalaccount.github.io/blog-v2/>
git repo: <https://github.com/createyourpersonalaccount/blog-v2>

The highlights are that I got

1) MathJax to work
2) TikZ commutative diagrams to work as SVG files
3) Source code blocks + colors (server-side; not a .js coloring client-side)
4) A nice navigation sidebar
5) I get to preview locally if I want but also I have a GitHub
workflow that automatically builds my blog; both views are the same.

In this format all I have to do is add .org files under the
content/pages/ directory (and .tex files under the content/img/
directory for the commutative diagrams) and run `make` and the static
blog is built.

I know there's several ways to improve but I want to bring a couple of
points where you might be able to help me:

1) I got colors in source blocks by post-processing with node.js +
highlight.js the raw HTML. Is it possible to write my own backend that
feeds the source block into my node app?
2) I got several issues with how the org files are exported as HTML,
for example I may want to insert an <article> tag, I may want a div
around content and a div around nav bar, etc. Not everything can be
solved with #+HTML: tags because I don't have precise control of where
those go. Can the HTML backend be edited or do I have to write my own
backend?
3) I am very inexperienced with org backends. What good resources are
out there for this subject?

Finally a highlight of the hacks I had to pull off: apparently
#+INCLUDE: will strip away inline backend information such as
@@html:<b>@@. I figured out that if I write something like
@@html@@a:@@:<b>@@, only the inner @@a:@@ is recognized and stripped,
which leaves me with what I originally wanted! (see
<https://github.com/createyourpersonalaccount/blog-v2/blob/main/content/publish.el#L14-L20>)

Regards,
Nikolaos Chatzikonstantinou

Re: Some hacks on top of org-publish

[Ihor Radchenko]

Nikolaos Chatzikonstantinou <nchatz314@gmail.com> writes:

> 3) Source code blocks + colors (server-side; not a .js coloring client-side)

Note that ox-html can fontify src blocks by itself. Via htmlize + CSS styles.

> 1) I got colors in source blocks by post-processing with node.js +
> highlight.js the raw HTML. Is it possible to write my own backend that
> feeds the source block into my node app?

Yes, of course. See my next answers. The whole export proces is hackable
on multiple levels.

> 2) I got several issues with how the org files are exported as HTML,
> for example I may want to insert an <article> tag, I may want a div
> around content and a div around nav bar, etc. Not everything can be
> solved with #+HTML: tags because I don't have precise control of where
> those go. Can the HTML backend be edited or do I have to write my own
> backend?

Check out https://orgmode.org/manual/Advanced-Export-Configuration.html

> 3) I am very inexperienced with org backends. What good resources are
> out there for this subject?

See https://orgmode.org/manual/Adding-Export-Backends.html
Org export backends can use inheritance. So, if you need to re-define a
part of backend (if filters are not enough), you can always create a
"subclass" by creating a "derived" backend.

> Finally a highlight of the hacks I had to pull off: apparently
> #+INCLUDE: will strip away inline backend information such as
> @@html:<b>@@. I figured out that if I write something like
> @@html@@a:@@:<b>@@, only the inner @@a:@@ is recognized and stripped,
> which leaves me with what I originally wanted! (see
> <https://github.com/createyourpersonalaccount/blog-v2/blob/main/content/publish.el#L14-L20>)

May you show more concrete example?
#+INCLUDE by itself does not remove export snippets.

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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>

Re: Some hacks on top of org-publish

[Nikolaos Chatzikonstantinou]

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

On Wed, Dec 25, 2024 at 8:47 AM Ihor Radchenko <yantar92@posteo.net> wrote:
>
> Nikolaos Chatzikonstantinou <nchatz314@gmail.com> writes:
>
> > Finally a highlight of the hacks I had to pull off: apparently
> > #+INCLUDE: will strip away inline backend information such as
> > @@html:<b>@@. I figured out that if I write something like
> > @@html@@a:@@:<b>@@, only the inner @@a:@@ is recognized and stripped,
> > which leaves me with what I originally wanted! (see
> > <https://github.com/createyourpersonalaccount/blog-v2/blob/main/content/publish.el#L14-L20>)
>
> May you show more concrete example?
> #+INCLUDE by itself does not remove export snippets.

It must not be #+INCLUDE then, but sitemap.org generation itself, I
misremembered when I wrote the e-mail. Here's a reproducer, see
attachment. Have this index.org file in its own directory and publish
it. Then view public/sitemap.html. You will see that the @@BACKEND:@@
stuff has been stripped away in the first sitemap entry instance,
while in the second it is there. When inspecting the generated
sitemap.org you will see the following line:

  - Without italics: [[file:./index.org][index]], 2024-12-26 -- With
italics: [[file:./index.org][index]],
@@html:<i>@@2024-12-26@@html:</i>@@

Regards,
Nikolaos Chatzikonstantinou

[-- Attachment #2: index.org --]
[-- Type: text/org, Size: 874 bytes --]

* Hello world

This is a test.

#+begin_comment
Local Variables:
org-publish-project-alist:
  (("test-project"
    :components ("test-component"))
   ("test-component"
    :auto-sitemap t
    :base-directory "."
    :base-extension "org"
    :publishing-function org-html-publish-to-html
    :publishing-directory "public"
    :sitemap-format-entry
    (lambda (entry sitemap-style project)
      (let* ((title (org-publish-find-title entry project))
             (date (org-publish-find-date entry project))
             (date-s (format-time-string "%Y-%m-%d" date)))
        (format (concat "Without italics: [[./%s][%s]], @@html:<i>@@%s@@html:</i>@@"
                        " -- "
                        "With italics: [[./%s][%s]], @@html@@a:@@:<i>@@%s@@html@@a:@@:</i>@@")
                entry title date-s
                entry title date-s)))))
End:
#+end_comment

Re: Some hacks on top of org-publish

[Ihor Radchenko]

Nikolaos Chatzikonstantinou <nchatz314@gmail.com> writes:

>> > Finally a highlight of the hacks I had to pull off: apparently
>> > #+INCLUDE: will strip away inline backend information such as
>> > @@html:<b>@@. I figured out that if I write something like
>> > @@html@@a:@@:<b>@@, only the inner @@a:@@ is recognized and stripped,
>> > which leaves me with what I originally wanted! (see
>> > <https://github.com/createyourpersonalaccount/blog-v2/blob/main/content/publish.el#L14-L20>)
>>
>> May you show more concrete example?
>> #+INCLUDE by itself does not remove export snippets.
>
> It must not be #+INCLUDE then, but sitemap.org generation itself, I
> misremembered when I wrote the e-mail. Here's a reproducer, see
> attachment. Have this index.org file in its own directory and publish
> it. Then view public/sitemap.html. You will see that the @@BACKEND:@@
> stuff has been stripped away in the first sitemap entry instance,
> while in the second it is there. When inspecting the generated
> sitemap.org you will see the following line:

I see.
What happens here is double export:
1. The default `org-publish-sitemap-default' first exports the sitemap
   items to Org file
2. The resulting Org file is exported to html

During the first step, @@html:...@@ is stripped because we export to
org.

You may want to use a custom :sitemap-function.

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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>