HTML contents list not appearing in compiled epub book

I’m making a setlist for a blues singer friend, doing it as an ebook so she can open it on her iPad and use the contents list to navigate between the songs.

I’ve set up a Contents page.
I’ve set up a bunch of songs as individual documents.
I’ve ‘Pasted Special’ the song titles into the Contents page as ToC links (to do this, I selected all the documents in the Binder with songs - the titles having been automatically generated by Scrivener from the first line - and then went Edit/ Copy special/ Copy Documents as ToC; then pasted the results into the Contents page.

Then I went to File/Compile and Compile for:/ ePub 3 ebook (.epub)

One basic problem: the table of contents didn’t appear in the resulting ebook - and it’s essential for my friend to be able to click a song title and jump to the words. What am I failing to do?

Edit: to clarify, the table of contents is appearing, just as a list of tracks, but it is not html, it’s not clickable. And I did check that “Generate HTML table of contents” was ticked - even tried un-ticking it, in case that was the problem.

A further request, when this is sorted out: how do you make a link that will jump back from the title of the song to the contents list, please?

Edit: Tried making it as a .mobi, thinking I could change to .epub in Calibre - but still no html contents in the .mobi version.

It’s a little difficult to say what is going on without seeing the project. One thing I would note, though, Copy Documents as ToC is not really what you want. That creates a list of documents with page numbers which is for use with all other formats. Ebooks are a bit of a special case in that they do not have page numbers. So you would be better of selecting the documents you want to include in the contents in the binder, using Copy (on its own) and then pasting into the contents list - this will create list of links without the page numbers.

What I suspect is the cause of your issue, though, is that your song documents do not have section breaks before them. Links in the contents page can only point to separate HTML files in the final ebook, and these are determined by adding a section break before the documents. Anything in the contents page that links to a document that does not start a new section will not come out as a link - which fits what you are describing. In Compile, then, ensure you assign a Section Layout (via “Assign Section Layouts…”) that places a section break before the Section Type used for your song documents.

For a link back to the contents page, simply add a document link at the end of the page. For instance, select the contents document in the binder, hit Copy, and then Pate at the bottom of the song document. This will create a link to the contents document.

All the best,

a) How should I make a table of contents, then?
b) What’s a section break and how do I add it?
c) here’s the project so you can take a look.
d) Thanks for your help.

Mervyene setlist (59.4 KB)

In Scrivener for Dummies, the way to make a table of contents is described as I do it above. All this is puzzling, because on any ebooks I’ve made before, this method of making a table of contents worked. I’ve looked in that and in the Help file for ‘Section break’ but failed to find any reference.

The Table of Contents is working in the Scrivener project (as you can see); it doesn’t appear as an html file when the project is compiled to make an ebook, though.

  1. I explained this above - copy the documents in the binder and copy into the editor to create the linked list.

  2. A “section break” is what a “page break” is called for ebooks. You will need to assign a Section Layout that has its “Separator before” set to “Section Break” to the Section Type that is assigned to the relevant sections. (Note: you need to understand about how Section Types and Section Layouts work for this. If you don’t, please refer to the section on them and Compile in the v3 tutorial. Alternatively, view the videos on our Learn & Support page or see the comprehensive coverage in the [url=]Scrivener 3 Transition Guide
    for details on moving to the system from a Scrivener 2 mindset.

Here is what you should do in your project to get this working (I’ll describe rather than simply providing the updated version of the project so that you can follow along and see how it all works yourself):

  1. First, we’ll set up your Section Types. These tell Scrivener what the parts of your project are. As far as I can see, you have a table of contents and a bunch of songs, so we will se these up according. Go to Project > Project Settings.

  2. In the “Section Types” area, rename “Section” to “Song” by double-clicking into it and typing over it.

  3. Click “+” beneath the Section Types list and create a new Section Type called “Contents”.

  4. Click “OK”.

  5. Open the Inspector.

  6. Switch to the metadata pane of the Inspector (the middle one with the tag icon).

  7. Click on your song documents - note how the “Section Type” is given as “Song”, which is now the default.

  8. Click on the “Contents” document and change the “Section Type” in the Inspector to “Contents”.

Your project is now set up so that you can tell Compile how you want the different sections formatted. Next:

  1. Open Compile.

  2. Choose “Ebook” from the Formats on the left - this provides a nice look for ebooks out of the box.

  3. Click on “Assign Section Layouts…”. This is where you tell scrivener how each of your sections (Section Types) should be formatted.

Note that you now see a list of Section Types on the left, including the “Song” and “Contents” ones you created. On the right is a selection of layouts - these allow you to tell Scrivener how you want each one formatting.

  1. Select “Song” from the list on the left, and then, on the right, select “New Section”. This assigns the “New Section” layout to “Song”, which, as you can see, has a section break before it.

  2. Now select “Contents” on the left and assign it “Table of Contents (Bordered)” on the right.

  3. Click “OK”.

  4. Compile and examine the ebook.

That’s it - you now have an ebook with a table of contents that works and with songs that each start on a new section so don’t run into each other. You only need to set that up all once for your project - from now on, whenever you Compile, it’s all set up and good to go.

That said, I think you could make it look nicer. The problem at the moment is that, because you’ve written the titles at the start of each document, the titles aren’t formatted very nicely in the final ebook. So, try this:

  1. In the binder, give each document the name of each song. (At the moment each document has no title and is just showing the first few words of the text - hence the italics.)

  2. In Project > Project Settings, under “Custom Metadata”, add a new metadata type and name it “Singer” (or “Songwriter” or whatever is most apt). Then click “OK”.

  3. In the Inspector Metadata pane, go through each song and add the necessary singer to each “Singer” field (e.g. “Billie Holliday” etc). Note that you will need to expand the “Custom Metadata” area to do this.

  4. Go through each document and delete the singer/songwriter line that is written at the top of the text.

Now the title is contained in the binder, the singer is stored in custom metadata, and the text of each document only contains the lyrics. Now we can make the ebook look a little nicer:

  1. Go to Compile again.

  2. Ctrl-click on “Ebook” in the Formats list and select “Duplicate & Edit Format…”. This allows you to create a customised copy of the format. Compile will expand to show you controls you will find familiar from Scrivener 2.

  3. Next to “Format Name” at the top, give the copied format a meaningful title, such as “Songs Ebook”.

  4. Under “Section Layouts”, you’ll see a whole slew of possible layouts. These are different options that users can choose for their ebook, formatting, but you don’t need them all. Delete all of them except for “Table of Contents (Bordered)” and “New Section”.

  5. Rename “New Section” to “Song Lyrics”.

  6. Under the “Settings” tab for “Song Lyrics”, change “CSS class name” to “song-lyrics” (optional).

  7. Tick “Title” for “Song Lyrics”. The title will be represented as “Section Title” at the top of the text preview below.

  8. Click into the “Section Title” text in the preview and choose “Bordered Title”.

  9. Click on “Title Options” and, in “Title Suffix”, make is that there is a newline (return character) followed by " by <$custom:Singer>" (replace “Singer” with “Songwriter” or whatever you used for the custom metadata title earlier).

  10. Switch to the “Formatting” tab and click into where it says “by singer”. Change the style (where it says “No Style” above) to “Subtitle”.

  11. Select “Table of Contents (Bordered)”, switch to “Title Options”, and change “Title Case” to “Normal”.

  12. Click “Save”.

  13. Click Compile.

Take a look at the ebook. Now it looks much nicer! Two things to note, though: The contents list doesn’t look that great because you copied it from auto-titled documents. Also, because the text is set up for prose, the first line of each section is not as indented as the rest. Let’s fix that:

  1. In Compile, Ctrl-click on the “Songs Ebook” format and choose “Edit Format…”.

  2. Choose “CSS” on the left, and then, under “Base text formatting”, click in the preview text and then drag the first line indent indicate to the left so that all of the text is flush-left with no indents.

  3. Click “Save” and then hold down the Option key so that the “Compile” button changes to “Save” and press that too to return to your project.

  4. In the “Contents” document, edit each line so that it reads more nicely. For instance, change “The thrill is gone (by BB King” to “The Thrill is Gone (BB King)”. (NOTE: You can just delete the contents, type out the titles as you want them, and then select each title and drag the document that it should link to onto the selected text. This turns the selected text into a link to the relevant document).

  5. I’d also recommend going through the songs and making sure that there are no extra spaces around. For instance, in “The Thrill is Gone” there are two returns after the first verse instead of one as there is elsewhere.

  6. Next, let’s add that “Return to Contents” link you wanted to the bottom of each song. For this, under each song, in the text, go to Edit > Emoji & Symbols and, from “Arrows”, inset into the text a return arrow, such as “Leftwards arrow with hook” (you could equal add “Return to Contents” as text, but I think an arrow looks nicer).

  7. Now, select the arrow in the text and go to Edit > Add Link… Choose “No prefix” for the link and for the text of the link, type “contents.xhtml”. This will tell the arrow to link to the contents document. (For some reason, linking it to the contents document isn’t currently working - I need to look into that. But typing the HTML name directly

  8. Copy and paste the arrow with the link at the bottom of each song.

One final tweak I might make is to add a hanging indent to the table of contents, given that the titles are quite long and spill across two lines. To do this:

  1. Edit the “Songs Ebook” Format in Compile again.

  2. Select “CSS” on the left and then, at the bottom of the “Custom Stylesheet” on the left, paste this:

nav#toc ol { padding-left: 2em; text-indent: -2em; }

(This is a rather advanced tweak, as you may gather!)

Okay, that was quite a lot of work! Note, though, that we could have stopped after the very first few changes and had a workable ebook. Everything else here was about turning into a really-nice looking ebook. One you’ve done all this, you have a format that can be used again and again - you can use the Songs Ebook format with other projects if you have other song collections. And it was more work than it would be for setting up, say, a standard novel or book, simply because you are compiling to a format (a collection of songs) that Scrivener doesn’t know about, so what we had to do above was create our own Compile Format for this. To do so, we started with the “Ebook” format and adapted it to our needs.

I’ve attached the resulting ebook, so that you can see the result of the above steps. The above steps should only take a little while to go through, and once you’ve been through them, you should have a much better idea of how to set all of this up in the future and the sort of thing you can do.

All the best,
Keith (8.76 KB)

Oh, that’s very nice! Thank you so much!

Pity it’s so complex, though; my plan was to get my blues-singer friend to buy Scrivener, and give her this first ebook, and instructions on how to make her own setlists for the future. She’s not very techie; can’t see her doing it. I think I’m going to be making a lot of setlists for her!

On the other hand, perhaps I could make a few quid doing it for others!

If there’s any way to automate html-contents-list-making in a future Scrivener tweak, it would be great.

Actually, I could use your version to make a template for setlists, Keithvin - I’ll do that over the next couple of days, if you’d like, and you can add it in to the templates? (But could you send me the .scriv project to use as a basis, if that’s easy?) I’ll use old Irish poems so they won’t be copyright.

I’ve attached the edited project. And yes, you can just create a project template from it and your friend can then just import the project template and use that without having to do any of the above.

I might actually use this for a future blog post on how to create a custom Compile format, in fact, as it is a good example that I think other users might find really useful. (I won’t use your project, of course, but one with some poems or different songs in it.)

All the best,
Mervyene setlist (94.4 KB)

As attached?

Mervyene Set (432 KB)

I missed that bit, but yes, it is already possible to automatic the HTML table of contents - if you don’t provide your own document with the “Contents” (or whatever) name, then Scrivener will generate it for you. In this case, though, we wanted a bit of a custom ToC, so it was good to use our own.

All the best,

A few questions as I go through - sorry, had to divert for a few days, and am going through the interactive tutorial:

You say: “Go to Project > Project Settings. 2. In the “Section Types” area…”

I can’t find any Section Types area. Where is it, please?

From the Project > Project Settings menu…


  1. Choose “Ebook” from the Formats on the left - this provides a nice look for ebooks out of the box.

I don’t seem to have an Ebook offered there? (I’m using the Blank template.)

At the very top of that window, you are compiling for print. Select that letterbox and choose to compile for the relevant ebook type. The ebook formatting options should then appear in the left panel.

Aha, thanks. Not all of the ebook formats change that menu to include ‘ebook’, by the way.

I don’t seem to have 'Table of contents (bordered), though there is a ‘Table of contents’? (ah ok, that worked)

How do I get the link back to the Contents to look like a little curly link rather than being the word “Contents” - as Keith did in his example? Much more elegant!

In the compiled version, having Copy-special-ed and pasted the filenames into the Contents list, the Contents do appear as links, but the links to return to the Contents list do not appear as html, but only as plain text. How do I make them retain their html-ness in the compiled version?.

To use the curly link, go to Edit > Emoji & Symbols, If you only see lots of emojis, click on the box icon in the top right corner of the emoji window to bring up a full panel of special characters. Then select “Arrows” in the list on the left and look for one you like:

For this, either:

  1. Tick “Convert document links to HTML links” in the options area of Compile (click on the gear icon above the contents area to switch to Options).


  1. Instead of linking back to the contents document with a Scrivener link, use Edit > Add Link, choose “No prefix”, and type “contents.xhtml” s the link. (The contents page will always be converted to a contents.xhtml page internally, so this is a trick that will work.)

All the best,

Thanks, Keith. One last (I think) question - how do I get that arrow to know that it’s to point to the Contents?

Select the arrow in the editor and then either:

  1. Drag the “Contents” document onto the selected arrow (or go to Edit > Link to Document and choose the contents document) - this assumes you have ticked “Convert document links to HTML links”.


  1. Select the arrow and go to Edit > Add Link and follow the instructions in my previous post for linking to contents.xhtml.

All the best,