Asciidoc numbered sections, but only part of document

Question

I'm using Ascii doc to make rest documentation with Spring Restdocs. I have an overview section and then a section with operations. I want the operations to have numbered sections, but I don't want the overview and other sections to be included in the numbering. Also, I'd like to not have the "operations" header have a number, because that's the only section that's numbered, so it makes little sense.

So, what I have is something like this:

= Web service title header

[preface]
== Overview
overview text

=== Overview sub section 1
stuff

=== Overview sub section 2
more stuff

== Operations

:sectnums:

include::oauth2-scopes.adoc[]

include::oauth2-clients.adoc[]

And then controller-1.adoc looks like this:

=== OAuth2 Scopes
==== Get scope
operation::get-scope[]

==== Get all scopes
operation::get-all-scopes[]

When this is rendered, the structure itself is great, the sections inside of "operations" are numbered. But, the problem is that the numbers are weird.

It seems the "operation" header is forced to be numbered one, even though there's no number there and the subsequent numbers seem to know that the number is suppressed.

I hope that this is enough to go by. I'm not super experienced with Asciidoc, so I may be missing something.

I've thought of using a multilevel numbered list, but I want it rendered as headers with anchors, not just a regular list.

---

Edit: I'm working around it by putting the heading "Operations" and the same level as the included sections (level 2). This makes the TOC indentation off, but it's less distracting than the numbers being messed up.

Edit 2: I was wanting Operations to be at level two (==) and the name of the controller to be level three (===). I want the controllers to be numbered. It doesn't make much sense to have the section title be numbered 1 and then the things I actually want enumerated to be numbered 1.1.

Answer 1

I am not sure if I understand your question correctly.

• If you need to optimise the weird numbering, make sure to reduce the level (from === to == etc.) This will fix that.

• If you want to switch off the numbering at some point, set a ":sectnums!:" at the needed postition.

But if I am completely on the wrong track, please try to reformulate your question. And if you add a screenshot, please make sure it fits to your example ;-)

Answer 2

You could probably use counters.

== Operations

:!level2:
:level1: {counter:level1}
=== {level1}. OAuth2 Scopes

:!level3:
:level2: {counter:level2}
==== {level1}.{level2}. Get Scope

:level3: {counter:level3}
===== {level1}.{level2}.{level3}. Example Request

[source,shell]
----
$ curl 'http://localhost:8080/scopes/scope1' -i -X GET
----

:level3: {counter:level3}
===== {level1}.{level2}.{level3}. HTTP request

[source,http]
----
GET /scopes/scope1 HTTP/1.1
----

Answer 3

I see many times questions about different numbering in Asciidoc. There are questions about how to number examples, pictures, etc.

If you are stuck in the limitations of Asciidoc with such a non-formatting, rather procedural feature, you could use the Jamal preprocessor integrated into Ascidoctor. Disclaimer: I created Jamal.

For a simple three-step installation, 1. download zip, 2. extract, 3. restart IntelliJ read the documentation

https://github.com/verhas/jamal/blob/master/jamal-asciidoc/README.adoc

In the snippet package of Jamal you can use counter macros to number anything, formatting in any way you like.