I'm a flip-flopper when it comes to collapsible sections. Sometimes I think they're great, and other times I think they're problematic.

Collapsible headings. Place your cursor in the heading. On the HOME tab, in the Paragraph group, click the dialog box launcher. In the Paragraph dialog box, click the checkbox next to Collapsed by default.

A while ago I converted nearly all of my help's subheadings into collapsible sections. I trend toward longer help pages, and the collapsible heading sections seemed like a natural way to provide a kind of clickable TOC. Readers could see up-front all the sections on the page and go directly to the section they needed. No need to scroll and scroll. Collapsible sections, it seemed, provided a way to reduce long pages into a more usable form.

And so I went about collapsing my heading sections. That's when I started noticing how problematic collapsible sections get.

1. In Word 2010, go to the File tab, click the large Check for Issues button, and select Inspect Document: In Word 2007, Inspect Document is under the Microsoft Office Button and the Prepare menu item. Now uncheck all boxes EXCEPT Headers, Footers, and Watermarks. Note: This tool also remove any watermarks from your document.
2. Select the header and the text that you would like to make into a section. (An example header: 'Penn State' and then the text could be a description of the university.) 2. Click the Collapsible Section button. The Collapsible Section dialog box will open. The selected text will display in the Header and Text areas.
3. Apr 22, 2019 To create an expand/collapse section in a Microsoft Word source document 1. In your Microsoft Word source document, identify a topic that contains text for which you want to create an expand/collapse section.

Problem #1: Pages get too long

If you can collapse your heading sections, your pages can get really long because you can just keep adding more and more sections without feeling like the page is too massive.

This may seem cool at first, since it means you can reduce the overall number of pages in your help material considerably. You can potentially reduce the unique page count to a third of the normal size, without forcing readers to look at infinitely scrollable pages.

However, long pages are often harder to manage. There comes a point when there's simply too much information on one page. The human mind does a better job processing information when the information is divided into smaller chunks (to an extent -- the chunks can't be too small or you lose context).

For me, a good page size is anywhere between about 500 and 1,500 words or so. But when you start hitting the 2,000 + word count range, it doesn't seem to work as a regular web page.

If you make your pages shorter, the need for collapsing sections decreases. Some topics may be only 300 to 600 words long. For those pages, do you still collapse the section headings? It looks silly if you do, and inconsistent if you don't.

This pretty much sums up the problem. Shorter pages don't need collapsible sections. The majority of tech writers create help in short topics rather than long topics (often because they're single sourcing), so that's why you rarely see collapsible sections used in help material -- short pages just don't need them.

Problem #2: Where to start collapsing

Another problem with collapsible headings is figuring out where to start collapsing them. If you have an introductory paragraph on your page, following by maybe 5 or 6 subheadings, most likely you'd just start collapsing each subheading.

But if that introductory paragraph is rather short, maybe 1-2 sentences, the page looks mostly blank. You have all of this empty space due to the collapsed headings.

This is not to say that another style technique that uses collapsible sections couldn't be successful. Check out this help page from Google called Using Keyword Planner to get keyword ideas and traffic estimates. Here the author decided to collapse only tasks.

Collapsible Headers In Word

The collapsed sections don't leave the page looking empty. In fact, they do a pretty good job at reducing the page size in a reader-friendly way.

But I wonder how this strategy works across an entire help site. Are all lists collapsed, or just some lists on pages that seem long? What if the page consists primarily of task steps and not concepts?If the collapsing is done in a mostly arbitrary way, isn't that inconsistency going to create confusion for readers, who will wonder why some sections are collapsed while others aren't?

Problem #3: Loss of immediate scannability

As a reader, I like to generally scan a page without having to manually click buttons to reveal the text. Although it can be nice to pick and choose what parts of the page I want to see, more often than not, I don't want to be burdened by opening up every single section I want to see. When you collapse heading sections, you force readers to do a lot more work just to read the page.

For example, here's the welcome page for Flare's help. Lots of sections are collapsed.

This might be a good thing, since you can go directly to the section you want. But it also means you have to click the page repeatedly just to see what each section contains.

Collapsing sections like this requires the subheadings to be more precise and clear. The subheadings need to do a stellar job at telling me exactly what's in the section. That way I won't have to guess with each click, wondering what information it contains.

I have to confess that when my collapsed subheadings are stacked like this, they're a lot less clear. At least when subheadings aren't collapsed, they also serve as a welcome break and pause for the reader, regardless of what the words actually say.

Problem #4: Linking

Linking may seem like a problem only inherent in the collapsible technique I was using, but since our help is on Drupal, we implemented the Collapse Text module. You can roll your own expand/collapse code, like I did here at Sample Expand and Collapse Code with Twisting Buttons, but using the existing module was simply easier (at first).

It turns out that for each section you want to collapse, you have to format it like this:

Now, what happens when you want to link to this section? Can you add an ID value to the link? No, the module chokes on it. You have to add an empty style tag with an ID inside the collapsed section.

The section opens automatically when the user goes to this spot, but since the ID is below the actual title, the title is slightly out of sight in the browser window.

The only workaround is to use a special class that offsets the position, like this:

When a user clicks a link with this class, the user's position gets offset 30 pixels at the top. To use this class in the context of the module, your links end up looking like this:

It's just kind of crappy kluge-like code. Most likely another write would come along, assume a wysiwyg editor inserted this jargon, and delete it.

While I mentioned wysiwyg, if you flip into your wysiwyg view, all of these heading titles are hard to find, because the wysiwyg editor only recognizes the heading tags (such as h2).

I haven't even mentioned the blow to SEO that happens when you strip out your h2 tags and replace them with bracketed material. The brackets are actually shortcodes that get converted to HTML when you view the page in the browser. So the final code looks like this:

Try styling that. You'll be hitting Inspect Element for quite a while just trying to figure out what controls what.

To be fair, the module author probably didn't intend to use this technique with headings, but that's how I was using it. I only note all this to show that what seems fairly simple gets much more complicated as you work out the details.

In retrospect, if implementing collapsible sections, use the jQuery technique I referenced earlier and apply it to an existing style. Then you can turn the collapsed sections on or off almost instantly.

Problem #5: Searches

A final problem is with search results. If a user searches for a keyword contained in the collapsed sections, the sections don't expand to show the reader where the keyword is. The reader would need to expand each section on the page to figure out where the keyword is on the page.

Collapsible Headings In Word 2016

This becomes rather tedious for the reader, so you might think oh, let's just put an Expand All button and Collapse All button on the page. This functionality isn't included in the Drupal module by default, so again, you have to either roll your own (discarding the module), or expand the module's functionality.

Then, assuming you get the thing working, you have to decide whether you'll include the Expand / Collapse buttons on every page by default or only on select pages. You'll no doubt want it on select pages, because you certainly don't want Expand / Collapse buttons on pages where there aren't any collapsed sections.

To add the buttons selectively on the page, you'll need to define a style element and add some jQuery to trigger a script when the element is clicked. This means more scripts and more styles, adding to your loading page's loading time. Not a huge deal here, but it's more hassle. (I actually have no idea how to automatically expand a specific collapsed section that contains a keyword on a search results page.)

Is all of this extra programming worth it? I don't think so.

A better solution

Although I've pointed out a lot of the problems with collapsible sections (both technical problems and with usability), collapsible sections could come in handy in places. I do like how Google has used collapsible sections to shrink various lists on the page. But ultimately I decided that a table of contents feature on the top (automated based on h2 tags) is a better solution.

With the table of contents method, the page is long but the reader can easily jump to the right section. This model offers both scannability and selectability. You can see a demo page here on a test Drupal site I'm playing with (leveraging the TOC Filter module). Readers are already familiar with this model because it's the same model Wikipedia uses.

About Tom Johnson

I'm a technical writer based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.

Allows notebook to have collapsible sections, separated by headings.

Any markdown heading cell (that is, one which begins with 1-6 # characters),becomes collapsible once rendered.

The collapsed/expanded status of the headings is stored in the cell metadata,and reloaded on notebook load.

Collapsible Headers In Word

Options¶

The extension offers a few options for how to display and toggle the collapsedstatus of headings, each of which can be enabled, disabled or configured fromthe nbextensions config page:

• Command-mode keyboard shortcuts, (enabled by default, and set to left andright arrow keys to collapse/expand sections, or go to the previous/nextheading, plus shift-right to select a heading cell’s section, shift-a/b toinsert a heading above/below the current cell, ctrl-shift-left andctrl-shift-right to collapse/uncollapse all headings).Bindings are also configurable from the config page
• A toggle control in the input prompt area of each heading cell (as seen inthe screenshot below, enabled by default)
  • Configurable icons and icon color for the toggle control (by default, greyright/down carets are used)
  • The option to make the toggle control into a button (by default it’s just aclickable icon)
• Mathematica-style grouping brackets around each collapsible section on theright of the notebook. Single-clicking a bracket will select all cells in thesection (hold shift to extend existing selection), while double-clicking thebracket toggles the section’s collpased/expanded status (disabled by default)
  • Bracket width is configurable, defaults to 10 (px)
• A gray bracketed ellipsis added to the end of each collapsed heading,indicating hidden content (disabled by default)
• A toolbar button to collapse the nearest heading to the curently selectedcell (disabled by default)
• Collapse/uncollapse sections when ToC2 sections are collapsed/uncollapsed
• A toolbar button to collapse/uncollapse all headings (disabled by default)
• Shift more-significant headings’ collapse controls further to the left

css¶

The extension add the css class collapsible_headings_collapsed to eachcollapsed heading cell, which you could use for custom css rules, such asadding a bottom border to collapsed headings, to visually distinguish them abit more.

The toggle controls’ icons currently spin by 360 degrees when the heading getscollapsed or uncollapsed, via a css transition property (not in IE).If this annoys you,you could turn it off using the following rule in your custom.css:

Internals¶

Heading cells which are collapsed have a value set in the cell metadata, sothat

The extension patches some Jupyter methods:

• TextCell.prototype.execute is patched to add/remove the toggle buttons,as well as update the visibility of any cells below the new one.
• Notebook.prototype.select is patched to make sure any collapsed headingswhich would be hiding the new selection get uncollapsed (expanded).
• Notebook.prototype.undelete and Notebook.prototype.delete_cells arepatched to trigger an update of which cells should be visible or hidden.
• Tooltip._show is patched to toggle the div.cell{position:relative;}css rule of while the tooltip displays, as otherwise it interferes with thetooltip’s position-determining logic. Since this method is not part of thepublic API (leading underscore), this may break in future, but it shoulddegrade in a non-catastrophic manner, with the result that the tooltip willappear at the top of the notebook document, rather than where the cursor iscurrently.

The extension also patches two existing Jupyter actions: those triggered incommand mode by the up/down arrow keys. Ordinarily, these select the cellabove/below the current selection. Once patched by collapsible_headings, theyhave the same behaviour, but skip over any cells which have been hidden (by acollapsed heading, or, in fact, by any other mechanism).

Finally, collapsible_headings registers two new actions, namelycollapsible_headings:collapse_heading andcollapsible_headings:uncollapse_heading, which are used by the keyboardshortcuts (if used), and can be called as with any other action.

The previously-provided preprocessor has been retired in favour of an exporterwhich embeds functionality correctly. See the [exporting section] for details.If you have questions, comments, or would like alterations (particularly fornbconvert support, of which I don’t have much experience), get in touch(@jcb91)and I’ll see what I can do :)

Exporting¶

It is possible to export most of the features of collapsible_headings to html.The process is to embed the relevant css & js files into the html output, withsuitable functionality for a non-live notebook.

This is accomplished through use of the ExporterInliner class and itsassociated inliner.tpl template, provided as part of thejupyter_contrib_nbextensions.nbconvert_support module.To convert to html embedding collapsible headings functionality, use html_chexporter, with a command like