danielgtaylor / aglio

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

Anchors for headers with HTML #162

Open winniehell opened 9 years ago

winniehell commented 9 years ago

Using aglio 2.0.4 with olio 1.2.1, the following

# Group <strong>Important</strong> Stuff

## Bar <span class="badge"><i class="fa fa-plane"></i></span>

leads to the following HTML

<section id="strong-important-strong-stuff" class="resource-group">
  <h2 class="group-heading"><strong>Important</strong> Stuff
    <a href="#strong-important-strong-stuff" class="permalink">¶</a>
  </h2>
  <h2 id="header-bar-span-class-badge-i-class-fa-fa-plane-i-span-">Bar 
    <span class="badge"><i class="fa fa-plane"></i></span> 
    <a class="permalink" href="#header-bar-span-class-badge-i-class-fa-fa-plane-i-span-" aria-hidden="true">¶</a>
  </h2>
</section>

Though the generated anchors are straight forward, the following seems more natural to me:

<section id="important-stuff" class="resource-group">
  <h2 class="group-heading"><strong>Important</strong> Stuff
    <a href="#important-stuff" class="permalink">¶</a>
  </h2>
  <h2 id="header-bar">Bar 
    <span class="badge"><i class="fa fa-plane"></i></span> 
    <a class="permalink" href="#header-bar" aria-hidden="true">¶</a>
  </h2>
</section>

so that you can refer to Important Stuff by #important-stuff and to Bar by #header-bar

In my opinion HTML tags and their attributes should be ignored when generating anchors.

winniehell commented 9 years ago

The special case that content of HTML tags should not occur in the anchors either like in the following, can wait for special syntax in my opinion:

## <i class="material-icons">settings_input_component</i> Settings

There is a CommonMark discussion about HTML attributes in Markdown and kramdown already supports it.