danielgtaylor / aglio

An API Blueprint renderer with theme support that outputs static HTML
4.75k stars 480 forks source link

Display of resource headings in navigation (apiary vs. aglio) #309

Open anrie opened 7 years ago

anrie commented 7 years ago

Hey,

I stumbled across a rendering issue in the navigation while starting to sketch an API on apiary.io and transferring the results (via "Download API Blueprint") to aglio.

This is the said documentation on apiary.io: http://docs.laddrtest.apiary.io/#reference/laddrs Notice the sections for Team and Teams in in the navigation.

If I render the exported blueprint file with aglio (2.3) the menu structure looks different.

The Team and Teams headings get omitted and instead the headings for the actions ("Retrieve a Team", "List Teams") are moved to the top level. (I tried different themes but the issue remained).

If the syntax is correct and the renderer for apiary isn't simply more forgiving than aglio then this looks like a bug, right?


This is how aglio renders the menu: aglio-nav.png

And the corresponding HTML:

<ul>
  <li>
    <a href="#laddrs-laddrs">Laddrs</a>
    <ul>
      <li><a href="#laddrs-laddrs-get"><span class="badge get"><i class="fa fa-arrow-down"></i></span>Retrieve Laddrs</a></li>
      <li><a href="#laddrs-laddrs-post"><span class="badge post"><i class="fa fa-plus"></i></span>Create a Laddr</a></li>
    </ul>
  </li>
  <li>
    <a href="#laddrs-laddr">Laddr</a>
    <ul>
      <li><a href="#laddrs-laddr-get"><span class="badge get"><i class="fa fa-arrow-down"></i></span>Retrieve a Laddr</a></li>
      <li><a href="#laddrs-laddr-delete"><span class="badge delete"><i class="fa fa-times"></i></span>Delete a Laddr</a></li>
    </ul>
  </li>
  <li><a href="#laddrs-teams-get"><span class="badge get"><i class="fa fa-arrow-down"></i></span>List Teams</a></li>
  <li><a href="#laddrs-team-get"><span class="badge get"><i class="fa fa-arrow-down"></i></span>Retrieve a Team</a></li>
</ul>
danbovey commented 6 years ago

If the resource only has one action, the title get's hidden:

olio-theme/templates/mixins.jade#L49

Using a custom template engine (forking olio-theme), I took the if/else out so that every action is nested under a title, even if there's just one.