arve0 / markdown-it-header-sections

similar to pandoc's --section-divs for markdown-it

markdown-it-header-sections

Renders this markdown

# Header 1
Text.
### Header 2
Lorem?
## Header 3
Ipsum.
# Last header
Markdown rules!

to this output (without indentation)

<section>
  <h1>Header 1</h1>
  <p>Text.</p>
  <section>
    <h3>Header 2</h3>
    <p>Lorem?</p>
  </section>
  <section>
    <h2>Header 3</h2>
    <p>Ipsum.</p>
  </section>
</section>
<section>
  <h1>Last header</h1>
  <p>Markdown rules!</p>
</section>

If you add attrs, anchor or any other plugin that adds attributes to header-tokens, sections will have the same attributes (which is useful for styling).

E.g., with attrs enabled before header-sections:

var md = require('markdown-it')()
  .use(require('markdown-it-attrs'))
  .use(require('markdown-it-header-sections'))

this markdown

# great stuff {.jumbotron}
lorem

click me {.btn .btn-default}

renders to

<section class="jumbotron">
  <h1 class="jumbotron">great stuff</h1>
  <p>lorem</p>
  <p class="btn btn-default">click me</p>
</section>

Install

npm install markdown-it-header-sections

Usage

var md = require('markdown-it')();
md.use(require('markdown-it-header-sections'));

var src = '# first header\n';
src += 'lorem\n\n'
src += '## second header\n';
src += 'ipsum';

console.log(md.render(src));

demo as jsfiddle

markdown-it-header-sections's Issues

Peer Headers with the second Header in a blockquote causes a bad section close

That subject line probably makes little sense, so here's an example. If you put this in the jsfiddle in the readme, you'll see the bad output:

const src = `## Great stuff {.jumbotron}
lorem

___
> ## section 2
> click me {.btn .btn-default}`;

results in

<section class="jumbotron">

<h2 class="jumbotron">eat stuff</h2>

<p>lorem</p>

<hr>

<blockquote class="btn btn-default">

</section>

<section>

<h2>section 2</h2>

<p>click me</p>

</section>

</blockquote>

I'm going to make an attempt at fixing this and will submit a PR if I get it, but wanted to post here first incase you know a quick fix.

crash if header is in list items

it seems this crashes markdown-it-header-sections:

- foo
  ### sss

- bar
  ### bar

[Feature request] Add a level option

Similar to https://github.com/valeriangalliat/markdown-it-anchor, it would be nice to wrap only certain level of heading into sections.

level	Minimum level to apply anchors on or array of selected levels.	1

Is that something you'd be interested in having added to this plugin?

markdown-it-header-sections causes infinite loop in parsing incorrect order of headers

try the following test case by executing npm test then you will see the FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - process out of memory.

diff --git a/test.js b/test.js
index 11940ee..db746ed 100644
--- a/test.js
+++ b/test.js
@@ -103,5 +103,27 @@ describe('markdown-it-header-sections', function(){
     var res = md.render(src);
     assert.equal(expected, res);
   });
+  it('should parse incorrect order of headers', function(){
+    var src = multiline.stripIndent(function(){/*
+      #### Header 4
+      Text.
+      ### Header 3
+      Hello!
+    */});
+    var expected = multiline.stripIndent(function(){/*
+      <section>
+      <h4>Header 4</h4>
+      <p>Text.</p>
+      <section>
+      <h3>Header 3</h3>
+      <p>Hello!</p>
+      </section>
+      </section>
+
+    */});
+    md.use(headerSections);
+    var res = md.render(src);
+    assert.equal(expected, res);
+  });

 });

Use Thematic Breaks (or Horizontal Rules) as Explicit Section Breaks

There is currently no way to get this HTML from any Markdown with this plugin:

<section>
  <h1>Upper-Level Heading</h1>
  <p>upper-level section</p>
  <section>
    <h2>Lower-Level Heading</h2>
    <p>lower-level section</p>
  </section>
  <p>upper-level section again!</p>    <!-- this is impossible right now -->
</section>

It would be possible, though, if you treated thematic breaks (---, *** or ___) as explicit section breaks.

Upper-Level Heading
===================

upper-level section

Lower-Level Heading
-------------------

lower-level section

---

upper-level section again!

The three different available types could even be used for slightly different meanings:

• *** end the current section
• --- end all sections but the top level, except when the current context is the top level and in that case also start a new section
• ___ plain old <hr />

Related discussion from CommonMark Discourse

• Horizontal Rule or Thematic Break
• Explicit Section not possible
• Horizontal Rules as Hierarchical Section Breaks etc.

Breaks Functionality with VuePress & Potentially Other Frameworks

See: VuePress/Issues/1203

TLDR:
Some frameworks specifically parse h for IDs; and in the case of VuePress, some of its functionality is broken because of how this extension moves the ID from h to section.

I modified the code to:
- @ the main loop: remove the part that moves the ID from h to section
- @ openSection: give the section an ID equivalent to section--original-id

I was going to submit it as a pull request, however, for some reason it's not working as I expected.

The issue I ran into is that even though I maintained the same data structure of [["id", "some-id"]] from the original code, for some reason it's not actually being applied to the rendered page.

Instead, I'm seeing

<section foo="undefined">
  <h2 id="foo">

where I would expect

<section id="section--foo">
  <h1 id="foo">

Not sure if there's something I'm missing within markdown-it-header-sections, or if this is happening somewhere within markdown-it or elsewhere.

When copying attrs, only one should have the id

Thanks for making this markdown-it plugin, working great!

My one issue is that when it copies attributes from the heading tag, it includes the id attribute. IDs should be unique within a page, so either the heading tag or the section tag should have the id, but not both.