<commit_before>**Travis CI:** ![Latest test](https://travis-ci.org/GGadow/html_toc.svg?branch=master)

#HtmlToc

HtmlToc is a Ruby module that post-processes an HTML document to built a table of contents and insert it at a specified location. It takes in the source text of the page, and returns the modified text.

##About

The gem consists of a single module, <span style="color:#009900;">HtmlToc</span>, which exposes a single public method, <span style="color:#009900;">process</span>. 

<span style="color:#009900;">#process</span> starts by performing a case-insensitive search for a token, **\[\[toc\]\]**. If no token is found, the unmodified source text is return. 

If the token is found, <span style="color:#009900;">#process</span> scans for header tags falling within a provided range; if the header does not already have an id attribute, one is added. If no matching headers are found, the token is removed and the modified source text is returned.

If headers are found, a link is generated for each matching header. The link text is taken from the header text, and the link's href points to the header's id. Each link wrapped in a div tag; the div is given a class name that matches is level relative to the search range. The link divs are wrapped in a few more divs with unique ids to create the table of contents. Lastly, the table of contents replaces the token and the modified source is returned. The classes and id allow the page to be styled in accordance with the website's design context. The resulting table of contents might look like this:

<div style="border:solid 1px #000000;margin-left:1em;">

&lt;div id='__toc'&gt;<br/>
&nbsp;&nbsp;&lt;div id='__toc_header'&gt;Contents&lt;/div&gt;<br/>
&nbsp;&nbsp;&lt;div id='__toc_content' style='display:block'&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_1'&gt;&lt;a href='#id__1'&gt;1 First (1<sup>st</sup>) major header&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_2'&gt;&lt;a href='#id__5'&gt;1.1 Minor header 1&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_3'&gt;&lt;a href='#id__11'&gt;1.1.1 Detail the first&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_3'&gt;&lt;a href='#already_here_1'&gt;1.1.2 Detail the second&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_2'&gt;&lt;a href='#already_here_2'&gt;1.2 Minor header 2&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_1'&gt;&lt;a href='#already_here_3'&gt;2 Second major header&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_2'&gt;&lt;a href='#id__2'&gt;2.1 Minor header 3&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_3'&gt;&lt;a href='#id__12'&gt;2.1.1 Detail the third&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_3'&gt;&lt;a href='#already_here_4'&gt;2.1.2 Detail the fourth&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_2'&gt;&lt;a href='#already_here_5'&gt;2.2 Minor header 4&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&lt;/div&gt;<br/>
&lt;/div&gt;

</div>

##Use

**<span style="color:#009900;">HtmlToc.process</span> &nbsp;&nbsp; source** &nbsp;&nbsp; *h_tags* &nbsp;&nbsp; *show_label* &nbsp;&nbsp; *use_numbers*

>**source** is a string holding the HTML source.

>*h_tags* is an optional Enumerable giving the integer indexes of the header tags that will be used to the table of contents. The method will iterate through *h_tags* using <span style="color:#009900;">#each</span> to build the regular expression <span style="color:#800000;">/&lt;h#{x}(?: .\*?)?&gt;(.\*?)&lt;\/h#{x}&gt;/</span> that will find the desired header tags. If omitted, the range (2..6) is assumed.

>*show_label* is an optional boolean. If **true**, the table of contents will include a span coded to call <span style="color:#800000">onclick = 'ShowHideToc();'</span>. This stub can be linked to a Javascript method to toggle the visibility of the table of contents. If omitted, **false** is assumed.

>*use_numbers* is an optional boolean. If **true**, the table of contents entries will have outline index numbers; otherwise, no numbers will be included. If an intervening header is missing &mdash; say, you have an h3 followed by an h5 &mdash; an index of zero will be used to indicate the missing h4. If omitted, **false* is assumed.

##Additional files

See **sample/html_toc.css** for an example how to style the table of contents.<br/><commit_msg>2014-12-09 c<commit_after>**Travis CI:** ![Latest test](https://travis-ci.org/GGadow/html_toc.svg?branch=master)

#HtmlToc

HtmlToc is a Ruby module that post-processes an HTML document to built a table of contents and insert it at a specified location. It takes in the source text of the page, and returns the modified text.

##About

The gem consists of a single module, <span style="color:#009900;">HtmlToc</span>, which exposes a single public method, <span style="color:#009900;">process</span>. 

<span style="color:#009900;">#process</span> starts by performing a case-insensitive search for a token, **\[\[toc\]\]**. If no token is found, the unmodified source text is return. 

If the token is found, <span style="color:#009900;">#process</span> scans for header tags falling within a provided range; if the header does not already have an id attribute, one is added. If no matching headers are found, the token is removed and the modified source text is returned.

If headers are found, a link is generated for each matching header. The link text is taken from the header text, and the link's href points to the header's id. Each link wrapped in a div tag; the div is given a class name that matches is level relative to the search range. The link divs are wrapped in a few more divs with unique ids to create the table of contents. Lastly, the table of contents replaces the token and the modified source is returned. The classes and id allow the page to be styled in accordance with the website's design context. The resulting table of contents might look like this:

<div style="border:solid 1px #000000;margin-left:1em;">

&lt;div id='__toc'&gt;<br/>
&nbsp;&nbsp;&lt;div id='__toc_header'&gt;Contents&lt;/div&gt;<br/>
&nbsp;&nbsp;&lt;div id='__toc_content' style='display:block'&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_1'&gt;&lt;a href='#id__1'&gt;1 First (1<sup>st</sup>) major header&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_2'&gt;&lt;a href='#id__5'&gt;1.1 Minor header 1&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_3'&gt;&lt;a href='#id__11'&gt;1.1.1 Detail the first&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_3'&gt;&lt;a href='#already_here_1'&gt;1.1.2 Detail the second&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_2'&gt;&lt;a href='#already_here_2'&gt;1.2 Minor header 2&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_1'&gt;&lt;a href='#already_here_3'&gt;2 Second major header&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_2'&gt;&lt;a href='#id__2'&gt;2.1 Minor header 3&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_3'&gt;&lt;a href='#id__12'&gt;2.1.1 Detail the third&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_3'&gt;&lt;a href='#already_here_4'&gt;2.1.2 Detail the fourth&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_2'&gt;&lt;a href='#already_here_5'&gt;2.2 Minor header 4&lt;/a&gt;&lt;/div&gt;<br/>
&nbsp;&nbsp;&lt;/div&gt;<br/>
&lt;/div&gt;

</div>

##Use

**<span style="color:#009900;">HtmlToc.process</span> &nbsp;&nbsp; source** &nbsp;&nbsp; *h_tags* &nbsp;&nbsp; *show_label* &nbsp;&nbsp; *use_numbers*

>**source** is a string holding the HTML source.

>*h_tags* is an optional Enumerable giving the integer indexes of the header tags that will be used to the table of contents. The method will iterate through *h_tags* using <span style="color:#009900;">#each</span> to build the regular expression <span style="color:#800000;">/&lt;h#{x}(?: .\*?)?&gt;(.\*?)&lt;\/h#{x}&gt;/</span> that will find the desired header tags. If omitted, the range (2..6) is assumed.

>*show_label* is an optional boolean. If **true**, the table of contents will include a span coded to call <span style="color:#800000">onclick = 'ShowHideToc();'</span>. This stub can be linked to a Javascript method to toggle the visibility of the table of contents. If omitted, **false** is assumed.

>*use_numbers* is an optional boolean. If **true**, the table of contents entries will have outline index numbers; otherwise, no numbers will be included. If an intervening header is missing &mdash; say, you have an h3 followed by an h5 &mdash; an index of zero will be used to indicate the missing h4. If omitted, **false* is assumed.

##Additional files

See **sample/html_toc.css** for an example of how to style the table of contents.<br/>
{'fraction_non_alphanumeric': 0.1659732866214145, 'fraction_numerical': 0.02496168162907817, 'mean_word_length': 6.153484729835552, 'pattern_counts': {'":': 0, '<': 73, '<?xml version=': 0, '>': 81, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3327785', 'n_tokens_mistral': 3290, 'n_tokens_neox': 3058, 'n_words': 1007}