The highest tagged major version is
Documentation
¶
Overview ¶
Package toc provides support for building a Table of Contents from a goldmark Markdown document.
The package operates in two stages: inspection and rendering. During inspection, the package analyzes an existing Markdown document, and builds a Table of Contents from it.
markdown := goldmark.New(...) parser := markdown.Parser() doc := parser.Parse(text.NewReader(src)) tocTree, err := toc.Inspect(doc, src)
During rendering, it converts the Table of Contents into a list of headings with nested items under each as a goldmark Markdown document. You may manipulate the TOC, removing items from it or simplifying it, before rendering.
if len(tocTree.Items) == 0 {
// No headings in the document.
return
}
tocList := toc.RenderList(tocTree)
You can render that Markdown document using goldmark into whatever form you prefer.
renderer := markdown.Renderer() renderer.Render(out, src, tocList)
The following diagram summarizes the flow of information with goldmark-toc.
src
+--------+ +-------------------+
| | goldmark/Parser.Parse | |
| []byte :---------------------------> goldmark/ast.Node |
| | | |
+---.----+ +-------.-----.-----+
| | |
'----------------. .-----------------' |
\ / |
\ / |
| |
| toc.Inspect |
| |
+----v----+ |
| | |
| toc.TOC | |
| | |
+----.----+ |
| |
| toc/Renderer.Render |
| |
+---------v---------+ |
| | |
| goldmark/ast.Node | |
| | |
+---------.---------+ |
| |
'-------. .--------------'
\ /
|
goldmark/Renderer.Render |
|
v
+------+
| HTML |
+------+
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RenderList ¶
RenderList renders a table of contents as a nested list with a sane, default configuration for the ListRenderer.
If the TOC is nil or empty, nil is returned. Do not call Goldmark's renderer if the returned node is nil.
Types ¶
type Extender ¶
type Extender struct {
// ListID is the id for the list of TOC items rendered in the HTML.
//
// See the documentation for Transformer.ListID for more information.
ListID string
// TitleID is the id for the Title heading rendered in the HTML.
//
// See the documentation for Transformer.TitleID for more information.
TitleID string
// Title is the title of the table of contents section.
// Defaults to "Table of Contents" if unspecified.
Title string
// TitleDepth is the heading depth for the Title.
// Defaults to 1 (<h1>) if unspecified.
TitleDepth int
// MinDepth is the minimum depth of the table of contents.
// Headings with a level lower than the specified depth will be ignored.
// See the documentation for MinDepth for more information.
//
// Defaults to 0 (no limit) if unspecified.
MinDepth int
// MaxDepth is the maximum depth of the table of contents.
// Headings with a level greater than the specified depth will be ignored.
// See the documentation for MaxDepth for more information.
//
// Defaults to 0 (no limit) if unspecified.
MaxDepth int
// Compact controls whether empty items should be removed
// from the table of contents.
//
// See the documentation for Compact for more information.
Compact bool
}
Extender extends a Goldmark Markdown parser and renderer to always include a table of contents in the output.
To use this, install it into your Goldmark Markdown object.
md := goldmark.New(
// ...
goldmark.WithParserOptions(parser.WithAutoHeadingID()),
goldmark.WithExtensions(
// ...
&toc.Extender{
},
),
)
This will install the default Transformer. For more control, install the Transformer directly on the Markdown Parser.
NOTE: Unless you've supplied your own parser.IDs implementation, you'll need to enable the WithAutoHeadingID option on the parser to generate IDs and links for headings.
type Item ¶
type Item struct {
// Title of this item in the table of contents.
//
// This may be blank for items that don't refer to a heading, and only
// have sub-items.
Title []byte
// ID is the identifier for the heading that this item refers to. This
// is the fragment portion of the link without the "#".
//
// This may be blank if the item doesn't have an id assigned to it, or
// if it doesn't have a title.
//
// Enable AutoHeadingID in your parser if you expected these to be set
// but they weren't.
ID []byte
// Items references children of this item.
//
// For a heading at level 3, Items, contains the headings at level 4
// under that section.
Items Items
}
Item is a single item in the table of contents.
type ListRenderer ¶
type ListRenderer struct {
// Marker for elements of the list, e.g. '-', '*', etc.
//
// Defaults to '*'.
Marker byte
}
ListRenderer builds a nested list from a table of contents.
For example,
# Foo ## Bar ## Baz # Qux // becomes - Foo - Bar - Baz - Qux
type TOC ¶
type TOC struct {
// Items holds the top-level headings under the table of contents.
//
// Items is empty if there are no headings in the document.
Items Items
}
TOC is the table of contents. It's the top-level object under which the rest of the table of contents resides.
type Transformer ¶
type Transformer struct{}
Transformer is a Goldmark AST transformer adds a TOC to the top of a Markdown document.
To use this, either install the Extender on the goldmark.Markdown object, or install the AST transformer on the Markdown parser like so.
markdown := goldmark.New(...)
markdown.Parser().AddOptions(
parser.WithAutoHeadingID(),
parser.WithASTTransformers(
util.Prioritized(&toc.Transformer{}, 100),
),
)
NOTE: Unless you've supplied your own parser.IDs implementation, you'll need to enable the WithAutoHeadingID option on the parser to generate IDs and links for headings.
Source Files