Is there anyway to export/convert the hierarchy of documents in the Draft folder into a set of html files with internal links (and cross reference links) working?
Basically I imagine to produce a hyperlinked html version of something like the Scrivener manual. An example here: Server Administration Guide
You seem to be asking TWO questions:
Output sets of files: by default Scrivener compiles multiple binder files into a single target document. So you would have a single HTML file. The question is do you need separate HTML files? If you do then you would need some way of splitting the compiled file and rewriting any links. Or using the export feature and some sort of post-processor.
As far as i know, Scrivener’s native document links are converted to internal cross-references automatically (at least for markdown workflows). This means you can cross reference between any document in the binder and these are preserved in the HTML.
Now any tweak that enables (1) will break (2) unless it explicitly handles the single > multiple file hyperlink address rewrite.
If I had to solve this problem, I would use Scrivener > Quarto and split the compiled markdown into one file per heading level, this would get me a multi-page HTML unified with nice navigation. The script to split could rewrite the cross-ref links like so: say in my introduction I link to a binder item named “My Results” with text “see the results”. Scrivener’s native document links would result in [see the results][My Results] as markdown. If we split this compiled file into intro.md and my-results.md then we would rewrite the link in intro.md to be [see the results][my-results.md] and when converted to HTML it should then link to that file properly. The renaming rules are quite simple in theory. See Quarto - Creating a Website for the details, note that page is written using Quarto itself.
Ah, your edited example [Server Administration Guide] is all ONE webpage (index.html) so if we ignore (1) then (2) becomes very easy. As I said Scrivener’s document links are already converted into cross-references at least in markdown compiler outputs, so this is very easy…
(I’m new to Scrivener.) Would you please elaborate how this is done? I tried the default Compile > MultiMarkdown to Webpage html, and it is far from satisfactory: internal links are gone, and multi-levels of headings are squeezed into one level.
Would you please give me more directions? I tried Compile > MultiMarkdown. The compiled markdown does not preserve internal links. If you have a more working compile format, would you please share with me? Thanks.
Yes, the Default compile format does not handle binder levels properly IIRC. Use Basic Multimarkdown and make sure to enable Convert links to MultiMarkdown:
This gets you HTML with full levels from the Binder and internal links between headings.
As a further step forwards, please see this example Scrivener project, which demonstrates the reference links and headers for a bunch of possible markdown → HTML outputs using different compiler formats:
Links.scriv.zip (81.7 KB)
The project uses a front-matter metadata file to specify some defaults and options for pandoc and quarto. This is just to give you an example of the type of settings available. If you wanted to run the compiler for each formatting option yourself, you would need to install Quarto / Pandoc / Scrivomatic etc. But you can see the outputs below:
By far the nicest output for HTML from Scrivener is via Quarto. The sample project above has several compiler formats to generate HTML (you need to have the tool installed of course):
Here is a comparison of the different outputs, comparing plain MMD, plain Pandoc, Pandoc+template, and Quarto:
By default, the pandoc output is nicer than the MMD output, but you can apply custom CSS and HTML to improve it further (as in my scrivomatic example). Quarto goes furthest in making a very nice document, including a floating TOC. You asked elsewhere about tables and you’ll notice in this sample project that we also add custom HTML to highlight alternate rows (at least for pandoc-based solutions).
The HTML sources for each tool alongside the markdown source from Scrivener’s compiler is zipped up here:
Examples.zip (373.9 KB)
Quarto is fairly easy to install and it has lots of tweaks to optimise your outputs and it is in active use for a growing number of documentation sites.
To summarise, you can use a straight Multimarkdown compile using pandoc (Basic Pandoc in my sample project) and then run Quarto. The command would be quarto render Links.md --to html. You can also automatically run Quarto (the Quarto compile format in my sample) from Scrivener’s post-processor.
Compiling to Quarto via MMD is great: the final document looks the best, and it supports floating/tracking TOC. But it does not support merged table cells! Any work around to this problem in the Scrivener - MMD - Quarto workflow?
Merging table cells is a work in progress for Pandoc flavoured markdown, and is not supported in Scrivener’s tables at all. Even when Pandoc does support the markdown table cell merging, we still must wait for Scrivener to update its table code (which @KB has said he was working on), and then wait for Scrivener’s compiler to support the translation into markdown. I wouldn’t hold my breath for when this will work…
One solution would be to use raw source directly. So if you are rendering to HTML then you embed the raw HTML table using raw attributes. You can wrap the raw_attribute markup using a Paragraph style or Section Type as you prefer.
One potential caveat is that if you specify raw html, then this will not be included when you compile to e.g. TeX. You would need different raw table chunks for each output… If you were using section types then you could filter the compiler document include list for just those formats…
After having read the documentation, I still can’t understand the workflow exactly. Let’s see if this is correct:
Prepare your project with Scrivener. Break it into as many separate documents you want.
Compile as an MMD document.
Make a new Quarto project.
Copy the MMD document generated by Scrivener into the Quarto project folder.
Render the HTML project with Quarto.
You should end up with the original Scrivener project broken up into as many HTML pages as there where sections in Scrivener, with the navigation bar and page commands appearing in any page.
Is it correct?
EDIT: Uhm. It seems to just create a single page, corresponding to the MMD file generated by Scrivener. So, I can’t understand how to break it into sections when letting it be processed by Quarto, without manually adding something like a “\newpage” command.
Or, maybe it’s something to do in Scrivener, in the Edit Project Format > Styles dialog, by adding the “\newline” command as a prefix to the corresponding heading paragraph style?
EDIT 2: Nope, the \newpage trick doesn’t work. It always generates a single HTML file.
EDIT 3: I’ve seen Quarto doesn’t want the LaTeX \newpage command, but its own {{< pagebreak >}}. In any case, neither this one broke my .md source file into separate .html files.
Paolo
According to a developer in the Quarto forum, it seems that to get multiple HTML files one has to input multiple MD files.
This would obviously not be possible with Scrivener. However, by reading the Quarto documentation, it seems that pagebreak is supported in various file formats, including HTML.
Can Quarto break a MD file generated by Scrivener into a website made of multiple pages?
Paolo
Just wondering: if Quarto can’t split a single MD file compiled by Scrivener, maybe exporting from Scrivener could work as well? Scrivener can export to MD, but I don’t know if having to give up with the scripts and transformations that are possible with compiling make it the same thing.
EDIT: No, exporting is not the same thing. It’s just the original text, with no preparation for actual use.
Paolo
What about, if cross-references between sections are always inserted as markdown links?
I would like to work in Scrivener using the comfort of RTF visualization. But I wouldn’t use its internal links system, and I would type links in markdown style.
This wouldn’t be too different from what one has to do in a page layout program, apart for having to manually enter an anchor at the target.
In InDesign, I would have to create a section heading or an anchor, and then insert a link to it from the source.
In Scrivener, in “manual mode”, I would have to type the anchor/#identifier next to the section heading, and the type a link to it from the source. (Since Pandoc automatically considers heading titles as anchors/identifiers, creating an anchor couldn’t be needed – but this would add complications with translations).
If using anchors, changes to a target heading could be harmless. It’s just a matter of not changing the anchor, or also changing it in the source. This can led to errors. Project-wide search is however a great tool to find any occurrence of a source to a section heading one is going to modify.
Would it work, when compiling to an MD file, and then splitting it to let Quarto work on separate source MD files?
Paolo
I assume if you know what the future files will be called, then manual links should work just fine. Scrivener will not rewrite text or force links to be valid, so it should just spit out what goes in. You could use styles to generate the link markup for you or just type it yourself in the document ( I always prefer styles). The remaining issue will be figure links and footnotes which are put at the end of the document, and will get broken when split. You can force footnotes to be inline or use a script to turn reference links to inline links before you split…
