Last edited · 31 revisions  

 


See also the official documentation:
Help Center > Members Manual > Working with wiki pages > Organizing wiki pages


A wiki page can be just a few paragraphs of information, or it can hold a substantial document. As with any document, when it gets longer, it helps to have some organization to the information.

Using Header styles helps the author organize the information.

Having an automatically maintained Table of Contents allows the reader to quickly find the desired section of the document and also create a link to the section.

As a GMF member, you can help by adding to or correcting this article, or ask/comment in GMF@'s messages.

 

Overview

The Table of Contents ("ToC") feature works in conjunction with the paragraph format styles Header 1 through Header 6. As a result, it is available in wiki pages authored in HTML and Markdown, but not in Plain Text. This paragraph is in normal style, but the line above ("Overview") has been marked with Header 1 style. That style uses a larger default font size and is automatically included in the ToC.

A heading on a page that is to be included in the ToC box can be an external web link, or to another wiki page, or to anywhere else. What appears in the ToC box is the "Text to display" for the link (what appears on the wiki page) and does not need to be the actual URL.

Pages that use the ToC allow you to not only mention the location of information but allow you to create a link right to a subtopic on a page. Here are examples linking to subtopics on the home page of this wiki:

Note: Putting a preamble above the ToC, as this page has, makes the page easier to read and looks much better if you make it a Sticky Wiki Page

Not WYSIWYG

One of the weaknesses of the current ToC implementation in HTML pages is that it does not operate in a What You See Is What You Get ("WYSIWYG") fashion. That is, while you are in the edit mode for a page, when you use the ToC button to insert a ToC, you will not see the generated ToC; instead, you will see only a text marker, something that looks like this:

[​TOC:Example Table of Contents:1​]

NOTE: The text of the ToC should be in paragraph format (not heading format) or it looks really funky. Check the formatting style.

When you save the page, that marker will be converted into the filled-in and formatted ToC.

Once you've inserted the ToC marker into the page, do not use the button to update or edit the marker. Instead edit the marker itself (it is just text in the editor). This is another way in which the current implementation is not WYSIWYG. A future improvement to the ToC feature might change this.

When working in Markdown pages, or as a work-round to issues with the ToC button in HTML pages, you can simply type the ToC marker. Follow the format shown above, with the keyword TOC, the title, and the header depth separated by colons and inside of square brackets.

When you format text as a heading, a default font size is applied; however, once you apply the header style/level (through the Formats dropdown, i.e., h1, h2, h3...), you can modify its format, i.e., how the heading appears on the wiki page (font family, pt size, bolded, italicized, etc.). How a heading appears on the wiki page does not affect how the heading appears in the ToC block itself - that display box does not pick up the formatting of each heading. You can, however, format how the ToC box itself appears using the basic text formatting tools (bold, italic) but not the extended formatting toolbar (font family, pt size, etc.). For example, go back and look: the ToC for this page was formatted as italic (by formatting the line [TOC:Example Table of Contents:1] as italic.

When using a ToC, always start using Header 1, even if it looks too big; otherwise, the ToC doesn't appear properly. Subtopics should decrease by next smaller size:

Header 1

  • Header 2
    • Header 3
      • Header 4 and so on

References

Table of Contents feature in wiki pages, beta@ #6948, Mark Fletcher, 2016-03-28

Basic writing and formatting syntax, GitHub-Flavored Markdown.

Link checking your wiki

There are extensions for Firefox for checking links:

https://addons.mozilla.org/en-US/firefox/addon/linkchecker/

https://addons.mozilla.org/en-US/firefox/addon/pinger/

If you are unfamiliar with the process of installing an extension, Wiki Link Checking explains it step by step

The official Groups.io user documentation is in the Groups.io Help Center.