Table of contents as JSON
Every manual is rendered with a toc. at its root: what pages there
are, in the order the table of contents puts them and nested the way it nests
them.
{
"project": {
"title": "TYPO3 Explained",
"version": "main",
"permalink": "https://docs.typo3.org/permalink/t3coreapi:{anchor}@main"
},
"pages": [
{
"path": "Index",
"html": "Index.html",
"md": "Index.md",
"title": "TYPO3 Explained",
"anchor": "api-overview",
"pages": [
{
"path": "Introduction/Index",
"html": "Introduction/Index.html",
"md": "Introduction/Index.md",
"title": "Introduction",
"anchor": "introduction"
}
]
},
{
"orphan": true,
"path": "404",
"html": "404.html",
"md": "404.md",
"title": "Content was removed",
"anchor": "not-found"
}
]
}
What the project says is said once, at the top:
- title
- The title of the manual.
- version
- The version it was rendered as, or
""for a manual that names none. - permalink
- The permalink of every page at once: put a page's
anchorwhere{anchor}is.""for a manual that declares no interlink shortcode and therefore has no permalinks.
Each page carries only what is its own:
- path
- The page within the manual, relative to this file and without an extension:
the name the page has in both of its forms. Works in a local render and
under
docs.alike, as do the two links below.typo3. org - html
- The page's HTML, relative to this file:
pathwith.html. Left out when the manual was not rendered to HTML page by page. - md
- The page's Markdown, relative to this file:
pathwith.md, and what an agent reading the manual should follow. Left out when the manual was not rendered to Markdown page by page. - title
- The title of the page.
- anchor
- The label the page is known by: its own if it declares one, otherwise the id
derived from its title. Fill it into the project's
permalink. - pages
- The pages this one's table of contents leads to, in its order. Left out where there are none.
- orphan
- Present and
trueon a page no table of contents leads to. Listed all the same, because the file is published, and a table of contents that silently drops published pages is worse than one that says where they stand.
Why it exists
A tool that wants to read a manual has to learn its shape first, and until now
nothing published said it. objects. comes closest, but it is an
index rather than a table of contents: a flat map without order or nesting,
which repeats the project title and version in every one of its entries and
knows only .html addresses.
Saying those things once is most of the difference in size. For TYPO3 Explained,
982 pages, objects. is 4.2 MB and toc. is 553 KB --
36 KB against 335 KB once compressed.
Note
The file lists pages, not the headings inside them. Those are in
objects., which stays the place to look up a single anchor.
See Changelog index as JSON for the Core Changelog, which is rendered with an index of its entries on top of this.