Table of contents guide

Overview

This is a quick overview of how to get the Table of Contents functionality in Google Docs moved over to WordPress via Wordable.

There will be a bit of tinkering you need to do once the document has been exported to WordPress, and this will help you get your head around that.

It doesn’t pretend to deal with anything other than Google Docs, Wordable and WordPress, but the information around WordPress will apply to any website creation tool.

As you may have found this post via the website, here’s the corresponding Google Doc.

First we need some pretty sections to form a table of contents. For every document you do, you want ONE Heading One style heading, and then everything flows down from that. An HTML page should only have a single H1 tag (which corresponds to Heading One in Google Docs), and the structure should flow down from there.

If you can guarantee that your page will allow you to supersede the title with the Heading One from the Google Doc, then start with Heading One. If you can’t, start with Heading Two and work down.

Oh, some advice, don’t read any sections with a title beginning with Chapter, they are just boilerplate lorem ipsum text to give us a decent sized table of contents.

Next step is to insert the table of contents via Insert > Table of Contents > With Blue Links (the second image). That gives us the following.

Table of contents guide

Overview

Exporting to WordPress

Fixing the markup

The HTML5 shortcut

Conclusion

Chapter 1

Chapter 1.1

Chapter 1.1.1

Chapter 1.1.2

Chapter 1.2

Chapter 1.3

Chapter 1.3.1

Chapter 2

Google handles the formatting of it for us.

Exporting to WordPress

Go to Wordable and click on Documents in the left hand menu. Then Export to WordPress to the right of your chosen Google Doc.

Well, that was a short section 🙂

Fixing the markup

Wordable does a fairly decent job of exporting “clean” HTML. If what you see doesn’t look clean to you, have a look at an export from Microsoft Word. You’ll soon see the difference!

Find the Table of Contents block in the exported HTML. It’ll look something like this:

<p><u><a href=”” target=”_blank”>Table of contents guide</a></u></p>
<p><u><a href=”” target=”_blank”>Overview</a></u></p>
<p><u><a href=”” target=”_blank”>Chapter 1</a></u></p>
<p><u><a href=”” target=”_blank”>Chapter 1.1</a></u></p>
<p><u><a href=”” target=”_blank”>Chapter 1.1.1</a></u></p>
<p><u><a href=”” target=”_blank”>Chapter 1.1.2</a></u></p>
<p><u><a href=”” target=”_blank”>Chapter 1.2</a></u></p>
<p><u><a href=”” target=”_blank”>Chapter 1.3</a></u></p>
<p><u><a href=”” target=”_blank”>Chapter 1.3.1</a></u></p>
<p><u><a href=”” target=”_blank”>Chapter 2</a></u></p>

I’ll run through a quick explanation of what we’re seeing here, as it’ll help understand what you’re reading. An HTML tag is a way to instruct the browser on how to render the contents of the tag. Usually you’ll see an opening and a closing tag. For instance, <p> and </p>.

<p> stands for paragraph. Everything wrapped between each pair of <p> and </p> tags is considered to be part of a single paragraph.

<u> tags denote a piece of text as needing to be stylistically different. The default output is to underline the text, but this can be modified.

<a> tags are anchor tags. They change behaviour depending on what attributes are present. For our purposes we have two types, one of which is in the snippet above: <a href=”” target=””></a>.

<a name=””></a> is the other type. To complicate matters, <a name…> tags are deprecated in HTML5, having been replaced by a Global ID element.

I’ll speak a bit about the old style first, as it helps us to understand the relationship a bit better, and then show you the HTML5 shortcut.

This is commonly referred to as a link: <a href=”” target=”_blank”>

This is commonly referred to as an anchor: <a name=”ch1″ class=”uganchor”></a>

The links exported as part of the Table of Contents block are incomplete. The href=”” part means that they will go to the current page, and the target=”_blank” part means they’ll also open in a new window.

If you click on a Table of Contents link in your exported guide, you’ll be forgiven for thinking it doesn’t work as all it does is open the current page in a new tab.

So annoying!

We have two things to do to change the skeleton output by Wordable into a real, working table of contents:

  1. We need to set up some anchors
  2. We need to wire up the table of contents links to those anchors

That’s it.

See that anchor above? Copy it. After all, I copied it from Diana’s guide! It’s repeated just below for your convenience:

<a name=”ch1″ class=”uganchor”></a>

Now you need to insert those wherever you want an anchor to be present, updating the name as you go.

So, once you’ve added all your anchors to the document, the next step is to fix the links in the Table of Contents skeleton.

Remember, each line looks like this: <a href=”” target=”_blank”>

First thing we do is we delete all the target=”_blank” portions as we don’t want our anchor jumps loading the same page in a new tab. That gets old very quickly!

This leaves us with a list of <a href=”” target=”_blank”> elements wrapping the Chapter names. Update each one so that it references the correct anchor, prefixed with a # symbol. # used in this way is shorthand for “in page reference”.

For Chapter 1’s link, which is exported as:

<p><u><a href=”” target=”_blank”>Chapter 1</a></u></p>

We want to  change it so that it looks like the following:

<p><a href=”#ch1″>Chapter 1</a></p>

You’ll notice I also removed the <u> </u> tags. This allows your website’s hyperlink style to come through on the newly exported page.

I also included the contents of the name attribute on the anchor for Chapter 1, prefixed with a # symbol to denote an in page link. That’s why we edit the HTML to include the anchors before we mess with the Table of Contents.

It’s much easier on our sanity that way!

So now, when you preview or publish the post, your table of contents should jump to the anchors.

There is one caveat.

If you have a fixed header at the top of your pages like many sites, the page may jump to a location that seems off. That’s what the class=”uganchor” part is for. As this is very dependent on your site, get in touch with me if this is the case for you, and we’ll get the relevant CSS sorted.

The HTML5 shortcut

I mentioned the Global ID previously. It’s a great feature in HTML5 that allows us to just add an id to any element and use that as the anchor target.

It doesn’t actually allow me to do a nice and easy Wordable export as I can’t give an id to the actual headings in the document, so I’m not going to do that in this particular document (as updating it later will be a pain).

I can put the HTML that would need to be added for it. Assuming a Table of Contents link of:

<p><a href=”#ch1″>Chapter 1</a></p>

We want to modify the exported H2 for Chapter 1 so that it looks like this (the extra bit is in bold):

<h2 id=”ch1” class=”uganchor”>Chapter 1</h2>

That way the in page link will lock onto the relevant tag. Much less code, and probably the preferred way for any guides that have the Google Doc form the basis of the PDF as well. I’ll do one link that way in the exported page, which you can view via the code inspector if you want to.

Conclusion

Yeah, I know, conclusions come at the end.

As the rest of this page is boilerplate, this is the end.

I hope it’s been useful.

If not, let me know where I lost you, and we’ll figure out a better explanation, then I’ll update this post to reflect it.

Cheers,

Jonathan


The rest of the page is now boilerplate!

Chapter 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Chapter 1.1

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Chapter 1.1.1

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Chapter 1.1.2

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Chapter 1.2

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Chapter 1.3

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Chapter 1.3.1

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Chapter 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.