It is a good practice to use HTML Headings when writing blog posts. Doing so builds structure around your content and helps to make reading a bit easier for your visitor.
To further help your reader, wouldn’t it be nice to have a table of contents section that matches your headings and is displayed alongside your post? Wouldn’t it be even better if the table of contents were dynamically populated as you update existing posts and create new ones?
Before you read further, it is important to know the code below is specific to the Genesis Framework. If your theme is not a child theme of the Genesis Framework you will need to modify this code to fit your specific need.
Post Template Files
WordPress takes advantage of Post Template Files to help change the look and feel of a particular page on your website. There are several template files to choose from. For this example we will concentrate on the single.php file.
The Single.php File
The code below belongs to the single.php file where a JavaScript file is enqueued. This is the file that does much of the heavy lifting for our table of contents to display and work. We will discuss more on this JavaScript File in the next section. In the edwinvelez_do_sidebar() function there is a skeleton, or the beginnings of a <section></section> which also contains an empty <ul></ul>. This is the location and future home of the soon to be populated table of contents.
[gist id=”cdeace5a855d78a8b54e23be4e56db84″ file=”single.php” lines=”11-40″]
An example of this table of contents in action is seen on this very same page you are now reading.
The JavaScript File
The required JavaScript file is enqueued and set to do its job. When loaded, this file scans the page for existing HTML <h1> to <h6> tags and automatically populates the skeleton created in the single.php file. Notice how the $in_footer parameter of the wp_enqueue_script() function is set to true. This is important because we need the page to completely load first before the JavaScript is fired off to run.
[gist id=”cdeace5a855d78a8b54e23be4e56db84″ file=”genesis-build-sidebar-toc.js” lines=”11-78″]
Important Notes
There are at least two important things to keep in mind before you decide to use this code on your Genesis Framework child theme.
Below are two simple changes you may want to make when keeping the above notes in mind.
Restore Your Configured Widgets
When the remove_action() function is called it effectively removes all widgets previously added to the sidebar in the WordPress Dashboard for your theme. What though if you want to keep these widgets? Simply comment out this one line and your widgets are restored.
Change the Position of the Table of Contents
But wait! When the widgets are restored the table of contents is at the very bottom of the widget list. How do you bring it to the top? That is easy!
The add_action() function uses the default $priority value of 10. Change the priority value to a lower number, for example 5, and the position of the table of contents is brought to the top of the widget list.
Creating Page Jumps
The JavaScript Code searches your headings for spaces and replaces them with hyphens to create the table of contents. If you would like to Create a Page Jump when composing your posts, be sure to pay attention to capitalization and complete the same task manually.
To Do List
I would like subheadings to be clearly identified if one is found under a another in order to apply a more visual structure. For example, when a <h2> tag is found under a <h1> there should be an indent, hyphen or leader dots showing it is a subordinate of the previous heading.
Leave a Reply