Produce an outline of an HTML document
Expand usage instructions in readme
Document expected HTML structure in readme
Remove Depth field of Section



You can also use your local clone with git send-email.


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)