How do I generate a Table of Contents

Scrivener Scrivener for macOS
1

I have some technical documentation to write and I decided to try out scrivener before I get started. It looks nice. However I am absolutely stumped when it comes to creating a table of contents.

I’ve organized a set of folder and placeholder documents in the Binder, and now I’d like to make it so one of the Text Documents has a table of contents in it. If you’ve ever used Microsoft Word, you know adding a table of contents is pretty easy.

Any advice?

I’m guessing that there may be no way to do this in the product but that there may be a way to do this using an external tool that would look at the .scriv contents.

2

A table of content normally contains page numbers to tell you where you can find the chapters or whatever in the text.

Scrivener does not work with a pages concept. Sure, when you print you get pages but Scrivener does not know on which of the printed pages which chapter does appear. This is due only to the general paper settings of the printer.

A table of content only makes sense in a layout program or a word processor that shows you exactly how the output will look like. The kind of program you – or your editor, publisher, whatever – export the text into after you have written it in Scrivener.

Nonetheless, there is a way of getting a TOC-like something (without page numbers) in Scrivener: Go to compile draft and choose only the file and folder titles for export. Export and re-import the file.

3

Though not automated, you can always “build your own” as you work. Create a TOC document at the top of your draft, and drag titles into it as you create them. This has the side-effect of linking to the documents too, which makes it useful in Scrivener. That is the closest thing to an actual useful TOC you can get, since page numbers are moot in a drafting program. Having a document full of titles can be generated using Suavito’s advice, but it will not be functional, it will just be a list of names. At that point, you might as well just use the Binder as your TOC—which is kind of what it is there for. :slight_smile:

Creating a real TOC for the finished publish version should be done in a word processor, where things like page numbers have actual meaning.

4

Scrivener keeps surprising me, I didn’t know that!

5

Yup! It’s easy to catch up, too. Just lock the TOC document in the editor (Cmd-Opt-L), then Option-click on the Draft folder arrow (closing it first if necessary). Select all of the titles and drag them into the TOC document at once. Instant link file… but again, that is what the Binder already kind of does. So while this is a cool trick for creating cross references, I don’t really see the point of making a TOC file in Scrivener itself.

6

Suavito, I agree that the printed form of a Table of Contents should generally have page numbers to help the reader but that is not necessary for online documents. In my case I don’t need them as I expect the final result will be a PDF document, an HTML document or a Wiki page. In all of those cases I would expect the table of contents to have hyperlinks to the appropriate sections. The issue is the automatic generation.

Even without links, a Table of Contents is very useful when you have a large document because it allows the reader to get a quick view of all the material.

I can always manually create the table of contents before generating a draft but I’m kind of surprised there is no automatic way to accomplish the procedure AmberV is describing. Since I fully expect to reorganize the sections of my document several times before I’m done, it sounds like it will be a lot of rework if I want to publish a series of intermediate drafts for other people who won’t have Scrivener.

7

I just tried the procedure. Selecting all the documents in the Binder and dragging them into the Table of Contents document has the effect of creating several links, but unfortunately none of the hierarchy is preserved.

For example, I have the following structure under Draft:

Table of Contents (document)
Overview (document)
Test (folder)
	Data (folder)
	Configuration (folder)
		config.xml (document)
		catalog.xml (document)
		summary.xml (document)
	Catalog (folder)
	Rules (folder)
		Apache (folder)
			... (documents)
		Mysql (folder)
			... (documents)
		Summary (folder)
			... (documents)

When I paste the links into the Table of Contents document, I lose all the hierarchy and get only a flat list of links:

Overview
Test
Data
Configuration
config.xml
catalog.xml
summary.xml
Catalog
Rules
Apache
…
Mysql
…
Summary
…

It looks like if I really want a useful Table of Contents I’ll need to manually edit it and put back the indentation with each draft.

8

Sorry, I misunderstood your question. I thought you just wanted a table of contents that was functional from within Scrivener. You are right, manually dragging links in and indenting by hand whenever you make a change would get tedious.

If you are going the PDF route, you might want to look at MultiMarkdown. With that, you can produce a PDF (using LaTeX for typesetting), with an automatically hyperlinked and page-numbered TOC. The advantages here are that the TOC is generated post-export by LaTeX, meaning you can re-arrange all you want. Scrivener compiles a structured MultiMarkdown file using the Binder outline hierarchy, automatically during export. Once you get the LaTeX path installed and functional, producing a PDF only takes a few steps. This would be ideal for putting out intermediate drafts, as the PDF will look good everywhere, and be fully functional without any work on your part.

The HTML TOC would be a little more problematic, but not impossible. By default the XHTML produced by MMD has no TOC. However, it would be a fairly simple matter to create a basic XSLT to accomplish this. See the downloaded BBCode XSLT available in the Scrivener FAQ on the forum for a working example. The FAQ is produced using Scrivener+MMD. The table of contents at the top is generated automatically using BBCode lists. Unfortunately, because BBCode does not allow anchor linking, they are not hyperlinked, but it would be a simple matter to add that ability to the XHTML transformer. MMD creates id attributes automatically by stripping spaces and lowercasing the <h*> value. Manual id overrides can be supplied in those cases where the automatically generated attribute would be unwieldy to use.

As for the wiki page, I am not aware of a pre-built XSLT in the MMD package that will handle that conversion, but I would be surprised if there is not a good XHTML -> MediaWiki (or whatever) XSLT floating around on the Internet. It wouldn’t be too hard to drop that into the MMD XSLT folder (with perhaps a few name-space tweaks) and specify it in Scrivener’s MultiMarkdown Settings dialogue box. The XHTML that MMD produces is extremely straight-forward and clean. That is another advantage if you are a web designer. Apple’s HTML generator leaves many things to be desired.

Judging by the example article titles in your table of contents, I’m guessing that none of this will be “greek” to you. :slight_smile:

The reason Scrivener does not have a table of contents generator out of the box is that it is strictly a rich text based engine. Unless you are using MultiMarkdown, there are no semantics in the produced files. Chapter titles are just a different font from body text. The intention for the application has always been that a finished draft would be exported and then tidied up in a word processor, where structure could be applied (automatically in an optimum situation) and necessary TOC and so forth could be generated in the word processor. At most, it could produce an indented list on page one using the binder structure, but it would not be very useful, as many users prefer to put their chapter titles in the documents themselves, and leave the binder titles for self-reference. I actually do that myself in the FAQ project (albeit with MultiMarkdown syntax), because I wanted to use the full question as the header, and it wasn’t very easy to “read” the Binder only seeing the first few words. In these cases, Scrivener wouldn’t have any idea of how to generate a full table of contents, since as said, everything is just font changes.

Scrivener export philosophy boils down to two camps. If you need semantics, use MultiMarkdown. If using a word processor is good enough, then the regular RTF engine is easier to use for most people, since you can use italics like normal and so forth, you don’t have to learn any syntax (though MMD is very easy to learn).

9

From what I can tell most of what I want could be accomplished if Scrivener supported the concept of a document whose contents are generated by an external program or script. I’m tempted to just write my own program to overwrite my “Table of Contents” document with a new one generated from the other sections. The issue I see with that is possibly getting Scrivener confused when I overwrite it (there could be a cache or something that would need to be invalidated). Is there a good “technical manual” for Scrivener anywhere?

Meanwhile it sounds like MultiMarkdown is the way to go then. I’ll look into it. I haven’t written anything yet so I have no problem at this point with that or using any of the tools you mention.

Thanks for the prompt reply.

10

Unless I am misunderstanding you, that is precisely what MultiMarkdown is, and what Scrivener is doing. Scrivener has some GUI niceness that allows you to store MMD meta-data in the project (located in the File menu), a tool for importing MMD header structure into binder hierarchy, a bold and italic to syntax converter, and of course the export system. When exporting using Compile draft, Scrivener inserts MMD headers at the appropriate level, based on the Binder. This is what will be used to generate the TOC in LaTeX. Then creates a plain text temporary file.

From that point on, MMD is just what you described, a set of external scripts that Scrivener invokes, which convert the syntax into a valid XML file (XHTML), which is then further converted using the XSLT language into the desired end format (unless user specified they just wanted an XHTML file, of course). All of these scripts are located in the Scrivener bundle, but if you wish to do any heavy modification, it is recommended you install MultiMarkdown into your user library folder. Scrivener will defer to that over its internal copy of the scripts.

If you wanted to create a hard-coded TOC generator instead of using XSLT to create one, you’d just have to look at the base Perl script that does the syntax conversion and figure out a way to insert your modifications there. I think it would be easier to use XSLT, because the MMD scripts are modular at that point, whereas any edits you make to the Perl scripts will have to be stitched back into newer revisions of MMD.

Everything you need to know is located here.

11

bayareaguy,

Using Scrivener’s embedded Multimarkdown facilities is also your answer if you want HTML output.

best,
Greg

p.s. Ah, the Bay Area.

12

To be precise, what I meant was I could do what I wanted easier if I could specify the program I want to run in order to periodically regenerate just the Table of Contents. That would allow me to get what I want without having to use MultiMarkdown.

One thing I’m still considering is having a little web server run a cgi that would generate the table of contents from whatever Scrivener document I specify and point Scrivener at it. A URI such as http ://localhost/TOC/MyDocument.scriv would turn into what I want with each refresh.

That sounds like exactly what I’d like to do, but now that I know a little more about MultiMarkdown I’m going to see how it works out first.

I’m still coming up to speed with the way the information is organized here. I tried searching for “Table of Contents” in the Scrivener tutorial, in the forum and half-a-dozen ways on google and came up with nothing. It also appears there is a lot more information here and there in the forum than in any Scrivener documents I’ve found, which in itself is a little surprising compared with similar tools. For example, the author of the Leo ( webpages.charter.net/edreamleo/front.html ) editor uses Leo itself to manage all the documentation on it.

13

I’m not exactly sure why you find this surprising; forums by their very nature will generate more text than can be found in a Help file. The documentation of Scrivener is quite comprehensive. You can’t find anything about a table of contents there because it cannot generate one automatically. The documentation is hardly going to list the features that Scrivener doesn’t have! Instead, it describes those it does! Moreover, it doesn’t go into MultiMarkdown in any great detail because Scrivener just provides a portal to MMD. MMD itself has nothing to do with me or Scrivener so the documentation for that remains at the author’s website. Oh, and I would hardly write the documentation for Scrivener in Scrivener - that is not what Scrivener is designed for. The Apple Help editor expects multiple HTML pages, and Scrivener isn’t an HTML editor.

Perhaps the reason you find that the forum contains so much information is simply that the author of this particular tool (i.e. me) spends a lot of time answering questions here, and comprehensively.

Sorry, I was just a little perplexed by your comments.

All the best,
Keith

14

I started the assumption that client software (which I consider Scrivener to be) generally has five kinds of documentation: the product literature, the manual, the tutorial, the online help and finally documents written by the community. Each of those is generally used differently and contains different information.

So far I’ve found product literature on the website, a tutorial (which is a Scrivener document), online help and the forum. From what I can tell the online help actually contains the kind of information I would expect in the manual.

The fact that what is currently serving as both the online help and the manual isn’t a Scrivener document is quite suprising because it would be so much more useful if it were.

For instance, in its current form it is very difficult to search as it is inseparable from the application and lacks a comprehensive index. When I choose Help->Scrivener Help->Reference Guide, the ordinary in-page search (pretzel-F) doesn’t work. If you enter something in the “Ask a question” area, the matches only take you to the page and not the exact location of the keyword.

For example, if you enter “masterpiece” in that box, it will tell you only that the word occurs somewhere in the introduction. That isn’t very helpful when the document is structured as a collection of very long passages.

Are there good reasons that Scrivener’s own online help isn’t maintained with Scrivener? Scrivener certainly isn’t an HTML editor but surely it can generate HTML.

15

I’m sure everyone appreciates the time and effort you do put into answering questions. My only point was that it’s very hard to independently find answers when the information isn’t structured in certain ways and you don’t already know where to look.

That said, I’m still a little confused with the exactly how Scrivener works with MultiMarkdown but that discussion belongs elsewhere.

Regards

16

Scrivener uses the standard OS X online help format, as recommended by Apple. The Help tool itself - which I agree isn’t fantastic - is an Apple application. It takes HTML files which are then compiled into that Apple Help tool. You will find that most OS X programs use this format, as it is the standard (e.g. Pages, TextEdit, iPhoto etc). Scrivener can generate HTML but the MMD HTML exporter is much better than the standard one. Besides which, when it comes to HTML, I prefer to hand-code it rather than use a rich text system. Thus I use either TextWrangler or Coda to maintain the Help information. If the Help file itself were a Scrivener document, you would be able to delete whole swathes of text in it and so forth. Anyway, like I say, I’m just using the format that most users will be familiar with as it is standard across OS X.
All the best,
Keith

17

Still… it would be nice to be able to actually search the Reference Guild in the online help with precision. Scrivener’s own document search gets it right. You can see what I mean easily:

Help -> Tutorial, enter “importing” in the search box, click on Step 11. Importing and you see all the keywords (importing) in the document highlighted.

but the equivalent with

Help -> Scrivener Help -> Reference Guide, enter “importing”, select the first document and none of the keywords are highlighted.

18

As Keith has already said, though, this is a limitation of the OSX help system, not Scrivener. And I feel that presenting the user with a familiar, system-wide interface for help is worth the very small price of not being able to see highlighted search terms.

19

Isn’t it fairly standard practice these days to put the manual in the Help menu? Some companies produce a PDF along with that, but it is the same exact text in most cases, just in a different format.

You must be using Leopard. That is one of the things that I absolutely loath with the new operating system. Why is help now a floating palette that can only show help from one application at a time, and cannot be searched using Cmd-F!

Anyway, I think panning the documentation because it isn’t published in the application’s format is a little strange. Like you, I think it is neat when an information based application has embedded documentation in its own format. DEVONthink does this, Boswell, Leo, and I can think of a few others. But I certainly don’t consider it a pre-requisite.

By the way, as Keith said, it is just HTML. If you want more control over it, get into the Scrivener.app bundle and make a copy of the “Help” directory in Resources. Double-click on index.html and you should see it open up in your browser. You could even drag this Help directory into a Scrivener project, and have your embedded documentation. :slight_smile: