They really need to download Sigil and use it for 5 seconds.
I do (although for a considerably longer duration than 5s on average), and consider the pairing between Scrivener and Sigil / Calibre to be essential—though ultimately most of what I do in Sigil ends up encoded into Scrivener somehow, either as text, or compile settings. I.e. the Sigil environment is fantastic for design since you can work on the CSS in a real-time environment, it’s also good for testing tech solutions. But once I have either of those I plug them into Scrivener and move on, as that part is now there whenever I compile.
So to get to the point, Scrivener can of course insert HTML anchors and the links to them! There are two different major approaches to how one would do so (and slight variations within them):
- Firstly, consider using Pandoc to convert to ePub instead of the native exporter. It will produce a much cleaner HTML source to work from, when designing the CSS or making other modifications, but you can also type in whatever HTML you need without any fanfare and have it pass-thru verbatim into the ebook. In this case you might as well use Pandoc’s native markup for cross-referencing though, since it will handle the .xhtml addressing for you (in cases where a link jumps major sections). As generators, both Scrivener and Pandoc build out the internal files sequentially which can mean filename shifting if you shuffle sections around.
- If writing in Markdown, or setting up your work to compile well to Markdown doesn’t sound like something you’d be interested in, then you can make use of pass-thru styles to drop raw HTML into the output rather than having it escaped and printed as visible text.
I’ve attached a sample project that shows both methods.
ebook_links.zip (182.7 KB)
(Thanks to @MimeticMouton for providing back-link examples, which will in some book readers will cause the linked passage to display in a popup rather than requiring full navigation between sections of the book.)
Pandoc method
You will need to install the converter as it doesn’t ship with Scrivener. It’s got a simple .msi / .pkg installer for Win/Mac users respectively. After running that, restart the software so Scrivener can detect the install and add the necessary compile methods.
With that set up, load the sample project and open the compiler. It should say “Pandoc → ePub” at the very top, if the install went as it should, and the rest should already be set up for you. Give that a test compile, open it in Sigil, and compare alongside with the source.
Explanation...
- In the Draft folder, click on the “cross-reference examples” item, within the “Pandoc Example” book in the draft.
- In the first example we see the raw HTML approach. As noted you would need to know how Pandoc numbers files internally and either anticipate the target name or fetch it from a test compile.
- The second example demonstrates how we can leave that menial task up to Pandoc. It will build an index of all the anchors we declare, and route them automatically to the right internal .xhtml file. All we need to do then is provide the anchor ID as the link target.
- Now load up “link targets” to see how these are marked up. You can click between the comments to jump straight to the examples. The first example in the target section demonstrates the native Pandoc way of classing and IDing a div (which is designated with the
:::markers). - The second example is straight-forward and shows the raw HTML approach. Again I wouldn’t bother with that, for not only does it require more manual labour, it clutters up the editor and reduces the flexibility of the output, in case we want something other than ePub.
Native Scrivener
Before compiling, check out the example sections in the “Scriv Example” book. The notable things here are:
- We are using a special character style, called “Raw HTML”, to type in the link and anchor. The compiler will be set up to pass-thru verbatim anything typed into these character styles.
- With native Scrivener, there is no indexing of IDs or routing, like Pandoc provides, so we do need to know the internal xhtml naming scheme.
Compiling an example
Now to test the output:
- Open the compiler again, and switch to Compile for ePub3 at the top.
- We’re using the stock “Ebook” compile format, which conveniently has this “Raw HTML” character style already set up for you. All you have to do is define it in the project to make use of it.
- To see how such a thing is set up, double-click on the “Ebook” Format to duplicate and edit it, and click into the Styles tab. Select the “Raw HTML” style, and note how the Treat as raw markup setting is enabled. That’s your pass-thru.
- Go ahead cancel out of that, make sure to select the “Scriv Example” book in the Contents tab, and give it a test compile.
Conclusion
Of course now that you know how this can be done in theory, no matter which method you use, you also now know how to go beyond whatever Scrivener doesn’t address natively. With the ability to insert your own HTML there are few limitations.