Asciidoc files guidelines

[jambulud]

Common structure for master files:

• master.asciidoc:
  All includes must be at level 0 and no titles (=, ==, ===, ...), for example:

include::general/master-general-start[leveloffset=0]
include::devon4j.wiki/master-devon4j[leveloffset=0]
include::devon4ng.wiki/master-devon4ng[leveloffset=0]

• master-*.asciidoc (devon4ng, devon4j, cicdgen, ...):
  • Must have ONLY ONE level 0 title, and it must be the first title (=).
  • No includes at level 0
  • Each include must be under one title X, and its level offset must be X+1:
    = is level 0 --> No includes at level 0.
    == is level 1 --> leveloffset=2 (because 1+1 = 2)
    === is level 2 --> leveloffset=3 (because 2 + 1 = 3)

Bad:

 = devon4ng

include::architecture[leveloffset=1]
include::meta-architecture[leveloffset=1]

== Layers

include::components-layer[leveloffset=2]
include::services-layer[leveloffset=2]

Good:

= devon4ng
    
// NO includes here  
   
== Architecture

include::architecture[leveloffset=2]
include::meta-architecture[leveloffset=2]

== Layers

include::components-layer[leveloffset=2]
include::services-layer[leveloffset=2]

• as a default rule, all the .asciidoc files should:
  • Must have ONLY ONE level 0 title, and it must be the first title (=).
  • The rest of the content must be in their own levels starting with level 1 (==)
  • Must not jump levels (writing something at level 4 without specifying level 3, 2, 1 and 0)

Bad:

// inside architecture.asciidoc file
== Some section 1
I'm under nothing, there is not level 0 and I'm level 1

==== 
My parent should be something at level 2, but I'm under level 1. My level is 3.

Good:

// inside architecture.asciidoc file

= Archtiecture

== Some section 1
I'm under architecture level 0 title. I'm level 1.

=== Other section
Im under some section 1. I'm level 2 and my parent is level 1

== Some section 2
Im under architecture level 0 title. I'm level 1