Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add section numbers in the spec (at least as optional?) #37

Open
dneto0 opened this issue Sep 20, 2023 · 1 comment
Open

add section numbers in the spec (at least as optional?) #37

dneto0 opened this issue Sep 20, 2023 · 1 comment
Labels
component Fix or change to an antora component repository needed feature request New behavior or content navigation improve site navigation
Milestone

Comments

@dneto0
Copy link

dneto0 commented Sep 20, 2023

The site looks really nice and is very responsive!

When looking at the spec, I'd like to see chapter and section numbers like in the ordinary rendering of the spec.

  1. I think it's useful when referring to the spec externally, to reference a numbered-and-named section.

  2. It helps keep me oriented.
    e.g. I know section 14 is descriptors, and section 15 is shader interfaces. :-)

@oddhack
Copy link
Collaborator

oddhack commented Sep 21, 2023

I'm neutral on this. It would require some work as Antora treats each chapter ('page') as a separate document and does not number them, which apparently is consistent with modern HTML docs practice, but can be done in the conversion script that translates asciidoctor markup to Antora conventions. Chapter / section numbers do change when an extension adds a new chapter, or when a chapter gets split (as we would have to do to address KhronosGroup/Vulkan-Docs#2231).

An advantage of the Antora presentation is that deep links will be much faster as they don't require loading the whole enormous single-page spec document, while page names are stable even across adding new chapters, unlike the 'chunked' HTML build published in the registry today.

@oddhack oddhack added feature request New behavior or content navigation improve site navigation component Fix or change to an antora component repository needed labels Jan 29, 2024
@oddhack oddhack added this to the Deferred milestone Jan 30, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
component Fix or change to an antora component repository needed feature request New behavior or content navigation improve site navigation
Projects
None yet
Development

No branches or pull requests

2 participants