Produce an outline of an HTML document

New mailing list added

10 months ago

New git repository added

10 months 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)