secnum - Add section numbering to headings in HTML files


  secnum [options] <infile> [outfile]


secnum adds section numbering to HTML files. Section numbers are added to existing heading tags. The numbers are calculated automatically based on the type of heading tag and the number of each type of heading already seen. No additional options or tags are required for secnum to work. Section numbers will be added to the headings of a specified HTML file, and the whole file (with numbered sections) written to a new file. If given the -toc option, secnum will create a table of contents, rather than a numbered HTML file.

secnum is a preprocessor. It must be run on the HTML file prior to making the HTML available for display.

By default, numbering starts with the <H2> tag and goes through <H6> No numbering is added for the <H6> tag. The -section option allows section numbering to start with heading tag <H1>, <H4>, or whatever heading tag the user wants.

If any heading levels are skipped, then secnum assumes that the skipped heading levels should be implied. For example, take the case of the next heading after an <H2> heading being an <H4> heading. The missing <H3> heading may be handled explicitly or implicitly. The explicit handling would skip the numbering, giving a section number like "1.0.1". Implicit handling for the missing heading level would result in a section number like "1.1.1". secnum provides implicit handling for missing heading levels. If the missing heading is later inserted, then all will be well, since secnum functions as a pre-processor and will account for the new header.

Given this set of heading tags:

    <h1>A Document</h1>
    <h2>A Section</h2>
    <h3>A Subsection</h3>
    <h4>A Subsubsection</h4>
    <h4>A Another Subsubsection</h4>
    <h3>Another Subsection</h3>
    <h4>And Still Another Subsubsection</h4>
    <h6>An Ill-advised, Skipped Sub6section</h6>
    <h2>Another Section</h2>

secnum will rewrite the heading text to be:

    <h1>A Document</h1>
    <h2>1 A Section</h2>
    <h3>1.1 A Subsection</h3>
    <h4>1.1.1 A Subsubsection</h4>
    <h4>1.1.2 Another Subsubsection</h4>
    <h3>1.2 Another Subsection</h3>
    <h4>1.2.1 And Still Another Subsubsection</h4>
    <h6> An Ill-advised, Skipped Subsection</h6>
    <h2>2 Another Section</h2>

The input file (infile) must be specified. The output file (outfile) is optional. If the outfile is not given, then the output filename is constructed from the input filename. If infile ends in ".html", ".HTML", ".htm", or ".HTM", then the secnum suffix is inserted before that dotted file extension. Otherwise, the secnum suffix is appended to the filename. The secnum suffix is -numbered. The command "secnum foo.html" will result in the foo-numbered.html as the output file.

The input HTML file may be modified in place if the -overwrite option is given and an output file is not specified. The command "secnum -overwrite foo.html" will result in the section-numbered HTML being written to foo.html. This is irreversible and should be used with caution. Once a file is overwritten, the section numbers are embedded in the original file.

secnum can be run in a simple daemon mode. This is useful while writing new HTML content. secnum will run continuously and periodically check if the specified file has been updated. If so, secnum will perform its regular header numbering and write the modified HTML to the specified output file. This may only be used when the input file and output files have different names.

Why A Preprocessor?

HTML does not provide a nice, easy method for providing automatically renumbered section headings. A variety of methods may be used to automatically add section numbers, each method with its own advantages and disadvantages.

- CSS can automatically add section numbers, but the section numbers aren't selectable in the browser, and skipped heading levels aren't handled nicely.

- Javascript and PHP can be added to handle automatic section numbers, but it is likely to add complexity to each numbered heading in each file. (The author is not a Javascript or PHP developer, so this assessment should be taken with a grain of salt.)

- secnum handles automatic section numbering, the resulting section numbers are selectable in the browser, and it does "The Right Thing" for skipped heading levels. However, it is a pre-processor and this isn't useful for live HTML files. (The author uses secnum during the writing of HTML-based documentation. After the documentation is finished, the unnumbered HTML is saved for later modification and the secnum-modified HTML is the version available for general use.)

Each method is useful in different situations. Use the method that best suits your own needs.


Please be aware of the following when using secnum:

In time, secnum may be modified so the warnings will no longer be of concern.


secnum takes the following options:


Wayne Morrison,


Copyright 2015 Wayne Morrison

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.