https://pandoc.org/MANUAL.html#options-affecting-specific-writers and look for --css

(I suggest also searching the manual for "css")

-c URL, --css=URL

Link to a CSS style sheet. This option can be used repeatedly to include multiple files. They will be included in the order specified.

A stylesheet is required for generating EPUB. If none is provided using this option (or the css or stylesheet metadata fields), pandoc will look for a file epub.css in the user data directory (see --data-dir). If it is not found there, sensible defaults will be used.


On Thu, 17 Nov 2022 at 14:36, Luís de Sousa <luis.a.de.sousa-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
Hi again Will,

I managed to get a well formatted output with a few tweaks to the CSS in the repo. However, I need to add the references to CSS files by hand. I understand this might be beyond the original scope of this thread, but what is the canonical method to automatically include these files in the pandoc compilation? If that is possible.

Thank you.

On Wednesday, 16 November 2022 at 10:25:37 UTC+1 wlu...@broadband-forum.org wrote:
Probably, yes!

The details depend on the template variable values (and on the CSS too of course; for example, the "sidebar" ToC is all done using CSS).

If you go to the example that I gave earlier (https://usp.technology/specification) and then to corresponding place in the GitHub repo (https://github.com/BroadbandForum/usp/tree/master/docs/specification) you can see all the final products, including the CSS.

On Wed, 16 Nov 2022 at 08:32, Luís de Sousa <luis.a....@gmail.com> wrote:
Hello again. I am now certain the template is being applied as you showed. However the output page is in all similar to the default, same font, colours and the absence of a TOC (a screen capture of the two side by side is attached). I was expecting to see something more akin to what you pointed to upthread and thought it was not functioning: https://usp.technology/specification . So I would just ask you to confirm the output in the screen capture is the expected.

Thank you.

On Tuesday, 15 November 2022 at 19:29:14 UTC+1 wlu...-QSt+ys/nuMyEUIsrzH9SikB+6BGkLq7r@public.gmane.org wrote:
Well not really, apart from using a very simple input file. See below for an example (I've downloaded the template from the gist to github-template-gist.html and put it in the current directory).

I'm wondering whether your problem might be that you're not supplying the needed metadata, so it _looks_ as though it's using the default template but in fact it isn't. I hope that you noted this comment in the README:
  • This is intended as a demo just to show the approach. It is not likely to be directly usable. In particular, all generated YAML files will currently be empty.
Have you tried editing the template, e.g., to insert some arbitrary HTML, so you can be absolutely sure whether it's being used or not?

% cat temp.md
Document.

% pandoc temp.md
<p>Document.</p>

% pandoc -s temp.md -o temp-default.html
[WARNING] This document format requires a nonempty <title> element.
  Defaulting to 'temp' as the title.
  To specify a title, use 'title' in metadata or --metadata title="...".

% pandoc -s --template github-template-gist.html temp.md -o temp-github.html
[WARNING] This document format requires a nonempty <title> element.
  Defaulting to 'temp' as the title.
  To specify a title, use 'title' in metadata or --metadata title="...".

% diff -w temp-default.html temp-github.html
1a2
> <!-- ORGANIZATION GitHub Pages pandoc template; modified from default.html template -->
164a166
>   <!-- XXX header includes are included just before the ToC (below) -->
165a168
>
166a170,182
>   <section class="page-header">
>     <h1 class="project-name">
>       <a href="" style="text-decoration: none; color: white;">
>         <img src="bbflogo-reverse-dark.png"/><br>
>        
>       </a>
>     </h1>
>     <h2 class="project-tagline"></h2>
>     <p></p>
>     <p></p>
>   </section>
>
>   <section class="main-content">
167a184,194
>     <div style="clear: both;"/>
>     <footer class="site-footer">
>       <span class="site-footer-owner">
>       </span>
>       <span class="site-footer-credits">
>         This page was generated by <a href="https://pandoc.org">pandoc</a>
>         and <a href="https://pages.github.com">GitHub Pages</a>.
>         <span class="release"/>
>       </span>
>     </footer>
>   </section>

On Tue, 15 Nov 2022 at 15:54, Luís de Sousa <luis.a....-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
Hi again Will, sorry for bothering you further. I so far failed to get the template to work. I tried to add it to the data folder ($HOME/.local/share/pandoc/templates/) but still nothing. Looks like the default template is being applied no matter what. For instance, none of the meta predicates in the head section ever make it to the final HTML. 

Would you have any suggestion to debug this issue?

Thank you.

On Friday, 11 November 2022 at 15:30:17 UTC+1 wlu...-QSt+ys/nuMyEUIsrzH9SikB+6BGkLq7r@public.gmane.org wrote:
Inline...

On Fri, 11 Nov 2022 at 14:01, Luís de Sousa <luis.a....-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
Alright, it is working now, many thanks. The output HTML looks pretty solid and well linked. Two questions: 

Great!

1. What is the purpose of the /dev/null bit in the second compile command?

That's what this remark in the README is referring to (rather obliquely):

> Including the HTML via --include-in-header was a workaround I think, and might no longer be necessary.

I think there was a problem with parsing HTML at one point, and this was a way of injecting HTML without passing it through pandoc.
 
2. Could you share an HTML template? It would greatly facilitate the design work.

I've added github-template.html (somewhat anonymised) to the gist.

Next I will give it a try with a more elaborate document including cross-references, citations, etc. Will report back on that.

You'll probably have noted that the writer attempts to fix cross-references so they reference the correct output file. 

Regards.

On Friday, 11 November 2022 at 13:58:28 UTC+1 wlu...-QSt+ys/nuMyEUIsrzH9SikB+6BGkLq7r@public.gmane.org wrote:
Oh, I'm so sorry! I hadn't tested exactly what I gave you (I'd put the contents of utils.lua into the writer for testing, but then put it into a new file to share with you, so the writer didn't need to change), but I forgot to put 'return utils' at the bottom.

I've now added this line: https://gist.github.com/wlupton/2fc23fc1c4e4b4899121bfafc0fea4bf#file-utils-lua-L51 and this time I've tested it locally. Please try again.

On Fri, 11 Nov 2022 at 12:33, Luís de Sousa <luis.a....@gmail.com> wrote:
Hello again. I confirm those are the contents in line 38. I assume utils.lua is being found, line 21 is now being  parsed without error. Anything else I can try? 

Thank you.

On Thursday, 10 November 2022 at 18:06:06 UTC+1 wlu...-QSt+ys/nuMyEUIsrzH9SikB+6BGkLq7r@public.gmane.org wrote:
can you confirm what's in line 38 of the writer? if you haven't edited the file then it's this:

local output_file_dir, output_file_base = utils.path.split(output_file)

can you confirm that you've also copied utils.lua and that it's being found? it should be calling the function at this line: https://gist.github.com/wlupton/2fc23fc1c4e4b4899121bfafc0fea4bf#file-utils-lua-L31


On Thu, 10 Nov 2022 at 16:36, Luís de Sousa <luis.a....-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
Thank you once more for keeping this going. I made some progress but now there is an error with html-multi-writer.lua itself (log below). I never worked with Lua before, apologies if I am making something dumb.

$ wget https://raw.githubusercontent.com/wlupton/pandoc-lua-logging/main/logging.lua
--2022-11-10 17:28:08--  https://raw.githubusercontent.com/wlupton/pandoc-lua-logging/main/logging.lua
Resolving raw.githubusercontent.com (raw.githubusercontent.com)... 185.199.111.133, 185.199.108.133, 185.199.110.133, ...
Connecting to raw.githubusercontent.com (raw.githubusercontent.com)|185.199.111.133|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 8173 (8,0K) [text/plain]
Saving to: ‘logging.lua’

logging.lua             100%[==============================>]   7,98K  --.-KB/s    in 0s

2022-11-10 17:28:08 (42,0 MB/s) - ‘logging.lua’ saved [8173/8173]

$ mkdir -p $HOME/.local/share/pandoc/filters
$ mv logging.lua $HOME/.local/share/pandoc/filters
$ export LUA_PATH="$HOME/.local/share/pandoc/filters/?.lua;;"
$ pandoc multi-test.md -t html-multi-writer.lua -o output/multi-test.html
Error running Lua:
html-multi-writer.lua:38: attempt to index a boolean value (local 'utils')
stack traceback:


On Thursday, 10 November 2022 at 13:47:52 UTC+1 wlu...-QSt+ys/nuMyEUIsrzH9SikB+6BGkLq7r@public.gmane.org wrote:
I've updated the gist by adding utils.lua and updating the README. This should be sufficient for the writer to run without error (please let me know if not).

Note that you'll also need to get logging.lua as described, and also note that any generated YAML files will be empty (I didn't want to share my brain-dead YAML writer but there appear to be lua YAML writers out there that might work... anyway you might decide that you don't need the generated YAML... this depends on how you set up the make rules).

I don't really want to create a repo for this (well... a gist _is_ a repo!) because I don't want (at this point) to provide any support for it (questions are OK though). I'm providing the gist just as a demo of the approach. Maybe later...

On Wed, 9 Nov 2022 at 18:28, William Lupton <wlu...@broadband-forum.org> wrote:
Oh sorry, yes, utils is one of mine! I'll look into this tomorrow...

On Wed, 9 Nov 2022, 16:03 Luís de Sousa, <luis.a....-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
Thank you very much for sharing, that looks very promising.

Pandoc can't run the script though, says it can't find the utils package. I installed luarocks and with it lua-utils but the error prevails:

$ pandoc multi-test.md -t html-multi-writer.lua -o output/multi-test.html
Error running Lua:
html-multi-writer.lua:21: module 'utils' not found:
    no field package.preload['utils']
    no file '/usr/local/share/lua/5.4/utils.lua'
    no file '/usr/local/share/lua/5.4/utils/init.lua'
    no file '/usr/local/lib/lua/5.4/utils.lua'
    no file '/usr/local/lib/lua/5.4/utils/init.lua'
    no file './utils.lua'
    no file './utils/init.lua'
    no file '/usr/local/lib/lua/5.4/utils.so'
    no file '/usr/local/lib/lua/5.4/loadall.so'
    no file './utils.so'
stack traceback:
    html-multi-writer.lua:21: in main chunk

P.S.: would you consider creating a repository for this work? I would like to automate the second stage with bash, shouldn't be too hard.

On Monday, 7 November 2022 at 15:46:58 UTC+1 wlu...@broadband-forum.org wrote:
I've created this gist: https://gist.github.com/wlupton/2fc23fc1c4e4b4899121bfafc0fea4bf

I added a README.md and hope that there's enough info to get going. Please let me know if not.

(Please note that this writer does some other things too, which might need to be stripped out. Also, it's an old-style writer... I haven't got around to updating it yet,)

On Mon, 7 Nov 2022 at 09:22, Luís de Sousa <luis.a....-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
Hi there. That is precisely the kind of output I would like to have. Similar to what tools like mdBook produce. I would be glad if you could share more details on that custom writer.

Thank you and regards.

On Friday, 4 November 2022 at 17:51:24 UTC+1 wlu...-QSt+ys/nuMyEUIsrzH9SikB+6BGkLq7r@public.gmane.org wrote:
See https://usp.technology/specification for an example of how the Broadband Forum has recently been publishing some specs. This output is generated via an html-multi-writer.lua custom writer that contains the logic for splitting the output into multiple files (based on header level and/or specific classes). The writer also takes care of generating the navigation bar that you see at the top and bottom of the pages. The multiple files are then passed through pandoc again (to add the overall sidebar ToC and the top/bottom navigation bars, and to generate multiple standalone docs).

Please let me know if you'd like more details (the overall setup is not very easily shareable, because it's heavily dependent on rather complicated make rules, but I could probably share the custom writer and give some example command lines.)

On Fri, 4 Nov 2022 at 12:45, Luís de Sousa <luis.a....-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
Dear all,

I am currently working on a long document that must served as a web page. The single file output is becoming too slow and cumbersome for readers. I am aware this functionality is not available, but a Feature Request is open [0]. 

In that issue there are some hints to this issue being addressable with a template [1]. I have tried many HTML templates, but never seen one that would split a long document in a set of small files. Would there be an example somewhere I could follow? Otherwise, could someone provide a general idea of how such template would function?

Thank you.


--
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/264eeee0-68c8-4389-a5c5-12563c6926f6n%40googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/cb3753d7-e845-4a72-a1aa-e93086a32f11n%40googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/1ef6858a-0a37-4f5f-a88b-eff2479a8130n%40googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/539db8b9-47f4-43b8-83d1-4b4c99dc3b3fn%40googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/7f4b28ec-1e91-4228-ab03-fe58a2e5cf18n%40googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.

--
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/20b2a20b-69ad-4b93-863a-c70db01d45een%40googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/fbe785d6-57dc-45a5-a4da-cc275638cd6dn%40googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/0a29b118-ae0f-448f-8e3e-39cc96ef5d8an%40googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CAEe_xxgnCSkiBiFFrU%3DOBEVwHf1XUXzf9PshA-HCB-w2E6dfkw%40mail.gmail.com.