Produce an outline of an HTML document

New mailing list added

2 years ago

New git repository added

2 years ago


Outliner produces an outline of an HTML document in markdown format, suitable for use as a table of contents.


For a 64-bit Linux system, you can download a binary from the release page on SourceHut.

Otherwise, if you have the Go compiler set up on your system, you can install from source:

$ go install -v git.sr.ht/\~javiljoen/outliner@latest


To generate an outline, pass the HTML document via stdin to the outliner command:

$ outliner < test.html
1. [Section A](#a)
    1. [Section A.1](#a1)
        1. [Section A.1.i](#a1i)
        2. [Section A.1.ii](#a1ii)
    2. [Section A.2](#a2)
2. [Section B](#b)

The input HTML is expected to have the following structure:

  • Each section and subsection below the main container element (i.e. after the title, preamble, etc.) is encapsulated in a <section> element.
  • Each section/subsection has a section heading within an <h2>, <h3>, or <h4> element, as a direct child of the <section> element. (Sections below the level of subsubsection are not included in the outline.)
  • The id attribute must be set on the <section> element (not the heading element). This will serve as the link target in the generated outline.

As an illustration, here is a document with a single section conforming to this structure. (See the test.html file in the project repo for a more complex example.)

  <h1>Article Title</h1>

  <section id="a">
    <h2>Section A</h2>
    <p>Lorem ipsum ...</p>


Note: If the HTML is generated by Pandoc, the expected structure can be obtained by using the --section-divs flag.

$ pandoc --section-divs README.md | outliner
1. [Installation](#installation)
2. [Usage](#usage)