resolves asciidoctor#1658 Call Document#<< (asciidoctor#1681)

resolves asciidoctor#1658

packages/core/spec/share/asciidoctor-spec.cjs

@@ -980,7 +980,7 @@ paragraph 3
         const doc = asciidoctor.load(`= Title
 
 == Section A`)
-        const sectionB = asciidoctor.Section.create(doc, 2, false, { attributes: { foo: 'bar' } })
+        const sectionB = asciidoctor.Section.create(doc, 2, true, { attributes: { foo: 'bar' } })
         sectionB.setTitle('Section B')
         doc.append(sectionB)
         const sections = doc.findBy({ context: 'section' })
@@ -989,10 +989,11 @@ paragraph 3
         expect(secondSection.getName()).to.equal('Section B')
         expect(secondSection.getTitle()).to.equal('Section B')
         expect(secondSection.getSectionName()).to.be.undefined()
-        expect(secondSection.isNumbered()).to.equal(false)
+        expect(secondSection.isNumbered()).to.equal(true)
         expect(secondSection.isSpecial()).to.equal(false)
         expect(secondSection.getCaption()).to.be.undefined()
         expect(secondSection.getAttribute('foo')).to.equal('bar')
+        expect(secondSection.getNumeral()).to.equal('1')
       })
 
       it('should set role', function () {

packages/core/src/asciidoctor-core-api.js

@@ -777,7 +777,8 @@ AbstractBlock.prototype.getSections = function () {
  * @memberof AbstractBlock
  */
 AbstractBlock.prototype.getNumeral = function () {
-  return this.$numeral()
+  const numeral = this.$numeral()
+  return numeral === Opal.nil ? undefined : numeral
 }
 
 /**
@@ -1471,6 +1472,18 @@ AbstractNode.prototype.normalizeAssetPath = function (assetRef, assetName, autoC
  */
 const Document = Opal.Asciidoctor.Document
 
+/**
+ * Append a content Block to this Document.
+ * If the child block is a Section, assign an index to it.
+ * @param {AbstractBlock} block - the child Block to append to this parent Block
+ * @returns {AbstractBlock} - the parent block to which this block was appended.
+ * @memberof Document
+ */
+Document.prototype.append = function (block) {
+  this['$<<'](block)
+  return this
+}
+
 /**
  * Returns the SyntaxHighlighter associated with this document.
  *