Indexing/Table of Contents workflow ideas?

I write in Markdown and convert documents from Markdown into HTML (either using TextMate or Marked) which I then publish to a website.

My documents are always structured the same way. I begin with an ordered list of sections, then flesh out each section starting with a header (usually an h2) for each topic.

I like to create my index/table of contents as I work, using Markdown’s hyperlink syntax to link to the future anchor tag for each header. When I convert the Markdown into HTML, the header tag is rendered including an anchor tag formatted like id=“section_name”. The index/table of contents then works automatically when published to my website. Never a dead link!

There are two problems: 1) I change the section order and modify section names continuously during the writing process until I feel the title of the section is “just right,” and 2) Typos or other differences between the index and the section headers mean I have to be careful that, if I change a section header, I also have to remember to change it in my index.

I can predict how TextMate will render the anchor tag (id=“section_name”) and enter that manually from the index/table of contents, but my preference would be to avoid that. Similarly, I can convert a list of Markdown header tags to HTML, return to Scrivener, and paste them into my hyperlinks in the index/table of contents. But, of course, if I change any of these I have to do it again.

I’d like to produce an index/table of contents dynamically from either a bunch of Scrivener documents or sections from within one document. Can this be done?

[size=140]First Approach[/size]:
There is a neat somewhat hidden feature in MultiMarkdown that lets you specify an anchor label by hand, rather than relying upon the auto-generation code. This really comes in handy if your titles are extremely long, duplicate or in cases like yours where the name of the section is liable to change. I use this technique myself for many of the section titles in the user manual, especially those that are based upon interface componenent names.

The syntax looks like this:

## Visible Title That Readers See [internal_id_that_you_use] ##

Now, what I like to do to keep the Binder clean and intuitive is to actually put this some place other than the binder name. That works just fine, but like I say it can make things look a bit cluttered.

So what I’ve done is created a custom meta-data field, “AnchorID”. In there I will type, including the brackets, “[anchor_id]” to give a section a hand-crafted ID. I have added this field as a column to my outliner so that I can easily look them up and revise them if necessary.

The trick then is to have the compiler print the contents of the custom meta-data field into the title area. This easily done by adding a suffix to each title field, making sure keep the option enabled that keeps any suffix inside the hashes. For example:

<$custom:anchorID>

Items that do not have a value for anchorID will just print an extra space (as there is one space to pad the ID away from the printed title), which is harmless. This is why you have to type the brackets into the individual meta-data fields though. Initially I tried putting the brackets into the suffix so all I had to type was the anchor_id itself, but then if something doesn’t have an ID, Scrivener prints:

## Visible Title That Readers See [] ##

Which tells MMD to not use an ID at all, even a generated one. That actually comes in very handy for stuff you know you’ll never link to and might likely collide with another section name. I just type “[]” into the custom meta-data field for those.

This won’t fix your typo problem of course, but with shorter labels it is easier to get the right one. What I like to do is add the anchor IDs to my project auto-complete list. That makes typing it in correctly not only easier, but 100% accurate. This however requires an extra step from you so whether you do that is going to depend on how often you type these in.

[size=140]Second approach[/size]:
Another approach entirely, if you aren’t using the first method, is to use Scrivener’s title auto-complete feature. If you start typing in the name of a section, you can hit Ctrl-Esc and it will provide potential matches for you from a list. In addition to that, I enable [[ wiki ]] style links in the Navigation preference pane. So in fact what I type is:

[[[Na]]][]

Then hit Ctrl-Esc, and I get:

[Name of Document][]

Complete with a Scrivener Link to the item in question, making my links useful in Scrivener as well. A good side-effect of having linked links (heh), is that you can then use the Edit/Update Links to Use Target Titles menu command to synchronise with any changes. This can be done to many links at once. If your main concern is that, and you don’t have any of the other problems, this approach might be what you prefer to the custom ID approach. It certainly requires less work from you, and results in an agile working area.

As for myself, I do a bit of a combination. For titles I know aren’t going to change, I use the second method. For titles that need a custom ID, I can’t use the wiki-link completion trick, but I can auto-complete the custom anchor and then select it, pop open Synopsis Finder (Ctrl-Cmd-G), find the document using that and then drag it with the Opt key held down into the selection to create a Scrivener Link to it. It’s slightly more work, but the next time something like “Full Screen” changes its name, I don’t have to update a hundred cross-references throughout the entire manual! I can just forget about it because I know all of the links still internally point to [edit_scrivenings] or [full_screen] or what have you.

Thanks so much! It turns out that the MultiMarkdown feature was the one I was looking for. I create my index with [Section Title][] and MultiMarkdown knows to look for an anchor called Section Title when it renders the HTML! Perfect.