The route /graph_guide does not respect the HTML format described in the documentation

Documentation : https://github.com/neo4j-contrib/neo4j-guides/blob/master/docs/html-guides.adoc

You can take a look at:

:play https://guides.neo4j.com/graph-examples/northwind-recommendation-engine/graph_guide

It looks like the rendering is broken (i.e. the sections). For reference, here's what we generate today for the following content:

Recently, I was asked to pitch a method for providing recommendations.  Luckily, armed with the knowledge obtained from talks from Max De Marzi and https://skillsmatter.com/skillscasts/7298-modelling-a-recommendation-engine-a-worked-example[Mark Needham^] at a recent  Neo4j London Meetups, I knew this could be easily achieved with Neo4j.

The key issue with recommendation engines comes from the data.
Luckily, Neo4j comes bundled with the Northwind Graph Example.
The Northwind database is an infamous dataset containing purchase history that has been used to teach relational databases for years and was a great place to start.

You can import the Northwind database into a graph by following the http://neo4j.com/developer/guide-importing-data-and-etl/["Import Data into Neo4j"^] post on Neo4j or type the following into Neo4j's browser, e.g. empty database in Neo4j Desktop or a https://neo4j.com/sandbox[blank sandbox^].

----
:play northwind graph
----

<html>
<body>
<!-- ... -->
<slide class="row-fluid">
  <div class="col-sm-12">
    <h3></h3>
    <br>
    <h3>Recently, I was asked to pitch a method for providing recommendations. Luckily, armed with the knowledge obtained from talks from Max De Marzi and <a
      href="https://skillsmatter.com/skillscasts/7298-modelling-a-recommendation-engine-a-worked-example" target="_blank" rel="noopener">Mark Needham</a> at a recent Neo4j London
      Meetups, I knew this could be easily achieved with Neo4j.</h3>
    <br>
  </div>
</slide>
<slide class="row-fluid">
  <div class="col-sm-12">
    <h3></h3>
    <br>
    <h3>The key issue with recommendation engines comes from the data.
      Luckily, Neo4j comes bundled with the Northwind Graph Example.
      The Northwind database is an infamous dataset containing purchase history that has been used to teach relational databases for years and was a great place to start.</h3>
    <br>
  </div>
</slide>
<slide class="row-fluid">
  <div class="col-sm-12">
    <h3></h3>
    <br>
    <h3>
      You can import the Northwind database into a graph by following the 
      <a href="http://neo4j.com/developer/guide-importing-data-and-etl/" target="_blank" rel="noopener">"Import Data into Neo4j"</a> post on Neo4j 
      or type the following into Neo4j’s browser, e.g. empty database in Neo4j Desktop or a <a href="https://neo4j.com/sandbox" target="_blank" rel="noopener">blank sandbox</a>.
    </h3>
    <br>
  </div>
</slide>
<slide class="row-fluid">
  <div class="col-sm-12">
    <h3></h3>
    <br>
    <div>:play northwind graph</div>
    <br>
  </div>
</slide>
<!-- ... -->
</body>
</html>

According to the documentation, we should instead generate something like:

<html>
<body>
<slide class="row-fluid">
  <div class="col-sm-12">
    <p>
      Recently, I was asked to pitch a method for providing recommendations. Luckily, armed with the knowledge obtained from talks from Max De Marzi and <a
      href="https://skillsmatter.com/skillscasts/7298-modelling-a-recommendation-engine-a-worked-example" target="_blank" rel="noopener">Mark Needham</a> at a recent Neo4j London
      Meetups, I knew this could be easily achieved with Neo4j.
    </p>
  </div>
</slide>
<slide class="row-fluid">
  <div class="col-sm-12">
    <p>
      The key issue with recommendation engines comes from the data.
      Luckily, Neo4j comes bundled with the Northwind Graph Example.
      The Northwind database is an infamous dataset containing purchase history that has been used to teach relational databases for years and was a great place to start.
    </p>
  </div>
</slide>
<slide class="row-fluid">
  <div class="col-sm-12">
    <p>
      You can import the Northwind database into a graph by following the
      <a href="http://neo4j.com/developer/guide-importing-data-and-etl/" target="_blank" rel="noopener">"Import Data into Neo4j"</a> post on Neo4j 
      or type the following into Neo4j’s browser, e.g. empty database in Neo4j Desktop or a <a href="https://neo4j.com/sandbox" target="_blank" rel="noopener">blank sandbox</a>.
    </p>
  </div>
</slide>
<slide class="row-fluid">
  <div class="col-sm-12">
    <figure>
      <pre class="pre-scrollable code runnable">:play northwind graph</pre>
    </figure>
  </div>
</slide>
</body>
</html>

This is mostly related to the fact that some graph gists are not using a proper AsciiDoc document structure.

Let's take an example:

This is a paragraph.

This is another paragraph.

This is yet another paragraph.

----
:play northwind graph
----

Now let's get started.

== Dataset

As you can see...

The above AsciiDoc document will produce the following (simplified) Abstract Syntax Tree:

{
  "type": "document",
  "blocks": [
    {
      "type": "paragraph"
    },
    {
      "type": "paragraph"
    },
    {
      "type": "paragraph"
    },
    {
      "type": "listing"
    },
    {
      "type": "paragraph"
    },
    {
      "type": "section",
      "blocks": [
        {
          "type": "paragraph"
        }
      ]
    }
  ]
}

Here, we need to decide when we should create a new slide. Should we create a new slide for each block? should we create one slide for everything that isn't contained in a section?

In order to get a proper document structure, we need to add a document title. Once this is done, everything before the first section is a "preamble":

{
  "type": "document",
  "blocks": [
    {
      "type": "preamble",
      "blocks": [
        {
          "type": "paragraph"
        },
        {
          "type": "paragraph"
        },
        {
          "type": "paragraph"
        },
        {
          "type": "listing"
        },
        {
          "type": "paragraph"
        }
      ]
    },
    {
      "type": "section",
      "blocks": [
        {
          "type": "paragraph"
        }
      ]
    }
  ]
}

As you can see, we now have two "top-level" blocks, one preamble and one section. In this case, we can create one slide for the preamble and one slide for the section.

To address this issue, we could mandate a proper document structure when a new graph gist is submitted and/or we could improve the template to handle more cases.

neo4j-contrib / graphgist-portal-v3

The route /graph_guide does not respect the HTML format described in the documentation #54