keeping subtree heading on export

keeping subtree heading on export

[Matt Price]

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

I'm writing a primitive exporter for jupyter-book
<https://github.com/executablebooks/jupyter-book>, which is a neat way to
maintain static documentation and executable jupyter notebooks from the
same source files.  The source files are written in Myst flavored markdown
<https://mystmd.org/>, so I started with a simpleminded fork of the gfm
exporter <https://github.com/titaniumbones/ox-myst>. What I'd really like,
though is something more like ox-hugo
<https://github.com/kaushalmodi/ox-hugo>, which maintains a whole blog in a
single org file.  For this to work, I need to export each individual page
of the "book" to its own markdown page.  However, jupyter-book expects to
find the title of the page in the initial first-level heading.  So I'd like
to retain the subtree "title" as a first-level heading, and demote the
remaining headings to their original state within the larger org document.

Does anyone know of an existing exporter that already does this, from which
I can steal? Or if not, how would you suggest I go about doing this?

Thanks,

Matt

[-- Attachment #2: Type: text/html, Size: 1279 bytes --]

Re: keeping subtree heading on export

[Ihor Radchenko]

Matt Price <moptop99@gmail.com> writes:

> ... I need to export each individual page
> of the "book" to its own markdown page.  However, jupyter-book expects to
> find the title of the page in the initial first-level heading.  So I'd like
> to retain the subtree "title" as a first-level heading, and demote the
> remaining headings to their original state within the larger org document.
>
> Does anyone know of an existing exporter that already does this, from which
> I can steal? Or if not, how would you suggest I go about doing this?

May you provide an example demonstrating initial Org mode document and
how the exported md documents should look like?

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

Re: keeping subtree heading on export

[Matt Price]

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

thanks for the response, Ihor -- reply inline below:

On Fri, Apr 26, 2024 at 9:45 AM Ihor Radchenko <yantar92@posteo.net> wrote:

> Matt Price <moptop99@gmail.com> writes:
>
> > ... I need to export each individual page
> > of the "book" to its own markdown page.  However, jupyter-book expects to
> > find the title of the page in the initial first-level heading.  So I'd
> like
> > to retain the subtree "title" as a first-level heading, and demote the
> > remaining headings to their original state within the larger org
> document.
> >
> > Does anyone know of an existing exporter that already does this, from
> which
> > I can steal? Or if not, how would you suggest I go about doing this?
>
> May you provide an example demonstrating initial Org mode document and
> how the exported md documents should look like?
>
>
I don't think my request was very clear.  Let's say I'm writing a "book"
(really a documentation set of some kind) with several "chapters" (really,
each chapter is an indiviual html page, though more complex nesting is
permitted by jupyter-book).

I write in org-mode:

-----
* Chapter 1
text
** Chapter 1.1
text
** Chapter 1.2
* Chapter 2
text
** Chapter 2.1
text
-----

And I want to produce two markdown files:

chapter-1.md:
-----
# Chapter 1
text
##  Chapter 1.1
text
##  Chapter 1.2
------

chapter-2.md
----
# Chapter 2
text
## Chapter 2.1
text
-----

I tried to learn a little more on my own after posting.  I can set
`org-md-toplevel-hlevel` to `2`, and then in the template function add the
title property "manually" by extracting it from the info communication
channel:

------
(defun org-myst-inner-template (contents info)
  "Return body of document after converting it to Markdown syntax.
CONTENTS is the transcoded contents string.  INFO is a plist
holding export options."
  (let* ((depth (plist-get info :with-toc))
         (headlines (and depth (org-export-collect-headlines info depth)))
         (toc-string (or (mapconcat (lambda (headline)
                                      (org-myst-format-toc headline info))
                                    headlines "\n")
                         ""))
         (toc-tail (if headlines "\n\n" ""))
         (front-matter (org-myst-front-matter))
         (title (org-export-data (plist-get info :title) info)))
    (org-trim (concat front-matter toc-string toc-tail "\n" "# " title
"\n\n"  contents (org-myst-footnote-section info)))))
------

This works ok!  But the problem ocmes because I would like to be able to
*also* sometimes export a whole file (rather than just a subtree) using the
same exporter.That's because I have inherited osme projects where files
take hte form:

chapter-1.org
------
* Chapter 1
text
** Chapter 1.1
text
** Chapter 1.2
------
etc.

The real problem I have is that, when exporting a subtree, I want to set
org-md-toplevel-hlevel to "2" and add the title; when exporting a whole
file, I want to set org-md-toplevel-hlevel to "1" and ignore the title.

I don't think this is how org exporters are supposed to work, but I'm
trying to interface to an established system that has chosen osme
un-org-like conventions.

Is this clearer, and do you see a way to do this?  I am just looking at the
source code and I wonder if I could add some (let) bindings inside
org-myst-export-to-markdown and ....-as-markdown before calling
org-export-to-[buffer|file].

hmm. Just tried it and it seems to work.  Something seems wrong about this
kind of code, though, in which I let-bind a variable in one function solely
so that I can use it in another.  Is there a better way?



 Un that case ,I would want to set


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

[-- Attachment #2: Type: text/html, Size: 5665 bytes --]

Re: keeping subtree heading on export

[Ihor Radchenko]

Matt Price <moptop99@gmail.com> writes:

> The real problem I have is that, when exporting a subtree, I want to set
> org-md-toplevel-hlevel to "2" and add the title; when exporting a whole
> file, I want to set org-md-toplevel-hlevel to "1" and ignore the title.

You can examine :export-options value in the INFO plist.
The value is a list with up to 3 elements: 'subtree, 'visible-only, and
'body-only.

In your backend :filters-alist, you can define a :filter-options filter
that will set :md-toplevel-hlevel option as needed, before the export
starts.

The :filter-options filter is there to pre-process export options
programatically, just as you describe.

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