fedora-ci / docs

#6 Enable table of contents for each page
Opened by psss. Modified

Open
Close Issue

It would be good to have a list of headings of the current page displayed in the left menu. Not sure whether it is possible to be done automatically in antora. @pbokoc recommended two ways: Manually add items into the nav.adoc file:

  • https://pagure.io/fedora-docs/install-guide/blob/master/f/modules/install-guide/nav.adoc

or by adding a :toc: tag into the page (but that takes quite some space of the page):

  • https://raw.githubusercontent.com/CentOS/docs-installation-guide/master/modules/install-guide/pages/Kickstart2.adoc
  • https://docs.centos.org/en-US/centos/install-guide/Kickstart2/

Ideally these should be autogenerated similarly as it does readthedocs, for example:

  • https://fmf.readthedocs.io/en/devel/features.html

@asamalik, any hint whether this can be done in some elegant way?

Not sure if that could be generated, since the nav.yml defines the structure of the docs, meaning what pages are the top-level, sub-pages, etc. Not sure where would it get the structure from if you wanted to generate it.

As for the headings, I don't think you can add them to the menu automatically, either.

As for the headings, I don't think you can add them to the menu automatically, either.

Hm, that surprises me a bit as it seems like a basic functionality. Perhaps this could be a good candidate for an antora enhancement? @ph0zzy, would you be willing to look into that?

I think the implementation should not be too complicated: When generating the page it's only necessary to check all headings and for each add a link to corresponding anchor. Optional level value could specify which heading levels should be displayed.

@psss I think for now we can deal with :toc: tag. Changing behavior of antora is something for long term goals.
:toc: tag has same behavior as "content" in old wiki. I can add it to newly added pages.
https://pagure.io/fedora-ci/docs/pull-request/13
Edited by ph0zzy

Yeah, I see. Table of contents at the top of the page is ugly and takes up a bunch of space but it is probably the best thing we can now do. I would still like to find a way how to move this to the left column. Let's keep this issue open and propose antora enhancement.

LGTM thanks:)

LGTM thanks:)

Please ignore, wrong PR :)
Metadata
None
None
None
None
None
Static archive. pagure.io was sunset in 2026; this is a read-only snapshot.
Red Hat Logo

Fedora is sponsored by Red Hat. Learn more about the relationship between Red Hat and Fedora »

© Red Hat, Inc. and others.