Document Catalog Hierarchy Writing and Rendering Errors

[无数]

There are authoring errors and there are rendering errors. These errors are simple, but can make it difficult to distinguish the hierarchy of elements and will lead to not knowing how to write the configuration file.

Just take the docker compose file document as an example

1. link services
   There is an exception to the indentation of the directory here. But the source code is correct. Maybe it's a bug in the rendering of the web front-end application
   

2. link network
   The driver here is at a level above all the elements that follow as headers, such as host or none, yet in the subsequent code examples, it feels like they are actually at the same level. This is a clear contradiction
   

   The source code is just wrong, driver is ###, others are ####

3. link volume
   Here there is a similar problem to 2. The difference is that it has the correct source code, both ###, yet the rendering hierarchy is wrong.
   

4. There are obvious problems with the rendering, other than the ones mentioned above.

   4-1 Link Version
   In this document, the source code for the title is: Version top-level element
   However the rendering is:Version and name top-level element I know this is the name in the document outline
   

   4-2 The front-end always takes the title of the document outline as the first title of the document page and renders it as h1, while ignoring the title in the source code and not even bothering to render it.
   The source code again always has ## as the top-level title, as if there is no #.
   So the front-end just renders h1 and the next layer is h3
   Like here: https://docs.docker.com/compose/compose-file/05-services/
   

   Why is this? It makes you think that there is some non-essential accommodation between the front-end developers and the documentation writers. This may have caused trouble.

[Allie Sadler]

Thanks for raising the issue @wushu037. The docs team is aware of the rendering issues. We'll shortly be moving over from Jekyl to Hugo. We're hoping this will fix this issue.

[无数]

@aevesdocker Okay, It probably needs to be repeated that it's not only the rendering that's the problem, but also the title hierarchy in the source code.