asciidoctor 3.0.4 → 4.0.0-alpha.1

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (C) 2019 Dan Allen, Guillaume Grossetie, Anthonny Quérouil and the Asciidoctor Project
+Copyright (C) 2019-present Dan Allen, Guillaume Grossetie, Anthonny Quérouil and the Asciidoctor Project
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,9 +1,13 @@
 # Asciidoctor.js: AsciiDoc in JavaScript powered by Asciidoctor
 
-Asciidoctor.js brings AsciiDoc to the JavaScript world!
+This package is a convenience wrapper that bundles `@asciidoctor/core` and the Asciidoctor CLI.
+It provides a native JavaScript implementation of Asciidoctor with no compilation step.
 
-This project uses [Opal](https://opalrb.com/) to transpile [Asciidoctor](http://asciidoctor.org), a modern implementation of AsciiDoc, from Ruby to JavaScript to produce _asciidoctor.js_.
-The _asciidoctor.js_ script can be run on any JavaScript platform, including Node.js, GraalVM and, of course, a web browser.
+The API is asynchronous: all parsing and conversion operations return a `Promise`.
+
+## Requirements
+
+Node.js >= 24
 
 ## Install
 
@@ -13,23 +17,19 @@ $ npm i asciidoctor --save
 
 ## Usage
 
-Here is a simple example that converts AsciiDoc to HTML5:
+### Convert a string
 
 **sample.js**
 
 ```javascript
 import asciidoctor from 'asciidoctor'
 
-const Asciidoctor = asciidoctor() // ①
-const content = 'http://asciidoctor.org[*Asciidoctor*] ' +
-  'running on https://opalrb.com[_Opal_] ' +
-  'brings AsciiDoc to Node.js!'
-const html = Asciidoctor.convert(content) // ②
-console.log(html) // ③
+const content = 'https://asciidoctor.org[*Asciidoctor*] running on Node.js!'
+const html = await asciidoctor.convert(content) // ①
+console.log(html) // ②
 ```
-1. Instantiate the Asciidoctor.js library
-2. Convert AsciiDoc content to HTML5 using Asciidoctor.js
-3. Print the HTML5 output to the console
+1. Convert AsciiDoc content to HTML5 — the call returns a `Promise` and must be awaited
+2. Print the HTML5 output to the console
 
 Save the file as _sample.js_ and run it using the `node` command:
 
@@ -41,11 +41,52 @@ You should see the following output in your terminal:
 
 ```html
 <div class="paragraph">
-<p><a href="http://asciidoctor.org"><strong>Asciidoctor</strong></a> running on <a href="http://opalrb.com"><em>Opal</em></a> brings AsciiDoc to Node.js!</p>
+<p><a href="https://asciidoctor.org"><strong>Asciidoctor</strong></a> running on Node.js!</p>
 </div>
 ```
 
-If you want to know more about Asciidoctor.js, please read the [User Manual](https://docs.asciidoctor.org/asciidoctor.js/latest/).
+### Convert a file
+
+**convert-file.js**
+
+```javascript
+import { convertFile } from 'asciidoctor'
+
+await convertFile('document.adoc', { safe: 'safe' })
+```
+
+### Load without converting
+
+Use `load` when you need to inspect the parsed document model before (or instead of) converting:
+
+**load.js**
+
+```javascript
+import { load } from 'asciidoctor'
+
+const doc = await load('== Hello, World!\n\nThis is Asciidoctor.')
+console.log(doc.getTitle())    // Hello, World!
+console.log(doc.getBlocks())   // array of top-level blocks
+const html = await doc.convert()
+console.log(html)
+```
+
+## CLI
+
+The `asciidoctor` command is available after installation:
+
+```console
+$ asciidoctor document.adoc
+```
+
+Common options:
+
+```console
+$ asciidoctor -b html5 -a toc document.adoc
+$ asciidoctor -o - document.adoc          # output to stdout
+$ asciidoctor --help                       # show all options
+$ asciidoctor --help syntax                # show AsciiDoc syntax reference
+```
 
 ## Contributing
 
@@ -57,6 +98,10 @@ The [Contributing](https://github.com/asciidoctor/asciidoctor.js/blob/main/CONTR
 
 If you want to write code, the [Contributing Code](https://github.com/asciidoctor/asciidoctor.js/blob/main/CONTRIBUTING-CODE.adoc) guide will help you to get started quickly.
 
+## Changelog
+
+Refer to the [CHANGELOG](https://github.com/asciidoctor/asciidoctor.js/blob/main/CHANGELOG.adoc) for a complete list of changes.
+
 ## Copyright
 
 Copyright (C) 2013-present Dan Allen, Guillaume Grossetie, Anthonny Quérouil and the Asciidoctor Project.

package/bin/asciidoctor

@@ -1,9 +1,6 @@
 #!/usr/bin/env node
-  
-'use strict'
 
-process.title = 'asciidoctor'
-const { Options, Invoker } = require('@asciidoctor/cli')
+import { run } from '../lib/cli.js'
 
-const options = new Options().parse(process.argv)
-new Invoker(options).invoke()
+process.title = 'asciidoctor'
+await run()

package/data/reference/syntax.adoc

@@ -0,0 +1,289 @@
+= AsciiDoc Syntax
+:icons: font
+:stem:
+:toc: left
+:url-docs: https://asciidoctor.org/docs
+:url-gem: https://rubygems.org/gems/asciidoctor
+
+A brief reference of the most commonly used AsciiDoc syntax.
+You can find the full documentation for the AsciiDoc syntax at {url-docs}.
+
+== Paragraphs
+
+A normal paragraph.
+Line breaks are not preserved.
+// line comments, which are lines that start with //, are skipped
+
+A blank line separates paragraphs.
+
+[%hardbreaks]
+This paragraph carries the `hardbreaks` option.
+Notice how line breaks are now preserved.
+
+ An indented (literal) paragraph disables text formatting,
+ preserves spaces and line breaks, and is displayed in a
+ monospaced font.
+
+[sidebar#id.role]
+A style, ID, and/or role gives a paragraph (or block) special meaning, like this sidebar.
+
+NOTE: An admonition paragraph, like this note, grabs the reader's attention.
+
+TIP: Convert this document using the `asciidoctor` command to see the output produced from it.
+
+== Text Formatting
+:hardbreaks:
+
+.Constrained (applied at word boundaries)
+*strong importance* (aka bold)
+_stress emphasis_ (aka italic)
+`monospaced` (aka typewriter text)
+"`double`" and '`single`' typographic quotes
++passthrough text+ (substitutions disabled)
+`+literal text+` (monospaced with substitutions disabled)
+
+.Unconstrained (applied anywhere)
+**C**reate+**R**ead+**U**pdate+**D**elete
+fan__freakin__tastic
+``mono``culture
+
+.Replacements
+A long time ago in a galaxy far, far away...
+(C) 1976 Arty Artisan
+I believe I shall--no, actually I won't.
+
+.Macros
+// where c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements, etc.
+The European icon:flag[role=blue] is blue & contains pass:[************] arranged in a icon:circle-o[role=yellow].
+The pass:c[->] operator is often referred to as the stabby lambda.
+Since `pass:[++]` has strong priority in AsciiDoc, you can rewrite pass:c,a,r[C++ => C{pp}].
+// activate stem support by adding `:stem:` to the document header
+stem:[sqrt(4) = 2]
+
+:!hardbreaks:
+== Attributes
+
+ // define attributes in the document header; must be flush with left margin
+ :name: value
+
+You can download and install Asciidoctor {asciidoctor-version} from {url-gem}.
+C{pp} is not required, only Ruby.
+Use a leading backslash to output a word enclosed in curly braces, like \{name}.
+
+== Links
+
+[%hardbreaks]
+https://example.org/page[A webpage]
+link:../path/to/file.txt[A local file]
+xref:document.adoc[A sibling document]
+mailto:hello@example.org[Email to say hello!]
+
+== Anchors
+
+[[idname,reference text]]
+// or written using normal block attributes as `[#idname,reftext=reference text]`
+A paragraph (or any block) with an anchor (aka ID) and reftext.
+
+See <<idname>> or <<idname,optional text of internal link>>.
+
+xref:document.adoc#idname[Jumps to anchor in another document].
+
+This paragraph has a footnote.footnote:[This is the text of the footnote.]
+
+== Lists
+
+=== Unordered
+
+* level 1
+** level 2
+*** level 3
+**** level 4
+***** etc.
+* back at level 1
++
+Attach a block or paragraph to a list item using a list continuation (which you can enclose in an open block).
+
+.Some Authors
+[circle]
+- Edgar Allen Poe
+- Sheri S. Tepper
+- Bill Bryson
+
+=== Ordered
+
+. Step 1
+. Step 2
+.. Step 2a
+.. Step 2b
+. Step 3
+
+.Remember your Roman numerals?
+[upperroman]
+. is one
+. is two
+. is three
+
+=== Checklist
+
+* [x] checked
+* [ ] not checked
+
+=== Callout
+
+// enable callout bubbles by adding `:icons: font` to the document header
+[,ruby]
+----
+puts 'Hello, World!' # <1>
+----
+<1> Prints `Hello, World!` to the console.
+
+=== Description
+
+first term:: description of first term
+second term::
+description of second term
+
+== Document Structure
+
+=== Header
+
+ // header must be flush with left margin
+ = Document Title
+ Author Name <author@example.org>
+ v1.0, 2019-01-01
+
+=== Sections
+
+ // must be flush with left margin
+ = Document Title (Level 0)
+ == Level 1
+ === Level 2
+ ==== Level 3
+ ===== Level 4
+ ====== Level 5
+ == Back at Level 1
+
+=== Includes
+
+ // must be flush with left margin
+ include::basics.adoc[]
+
+ // define -a allow-uri-read to allow content to be read from URI
+ include::https://example.org/installation.adoc[]
+
+== Blocks
+
+--
+open - a general-purpose content wrapper; useful for enclosing content to attach to a list item
+--
+
+// recognized types include CAUTION, IMPORTANT, NOTE, TIP, and WARNING
+// enable admonition icons by setting `:icons: font` in the document header
+[NOTE]
+====
+admonition - a notice for the reader, ranging in severity from a tip to an alert
+====
+
+====
+example - a demonstration of the concept being documented
+====
+
+.Toggle Me
+[%collapsible]
+====
+collapsible - these details are revealed by clicking the title
+====
+
+****
+sidebar - auxiliary content that can be read independently of the main content
+****
+
+....
+literal - an exhibit that features program output
+....
+
+----
+listing - an exhibit that features program input, source code, or the contents of a file
+----
+
+[,language]
+----
+source - a listing that is embellished with (colorized) syntax highlighting
+----
+
+```language
+fenced code - a shorthand syntax for the source block
+```
+
+[,attribution,citetitle]
+____
+quote - a quotation or excerpt; attribution with title of source are optional
+____
+
+[verse,attribution,citetitle]
+____
+verse - a literary excerpt, often a poem; attribution with title of source are optional
+____
+
+++++
+pass - content passed directly to the output document; often raw HTML
+++++
+
+// activate stem support by adding `:stem:` to the document header
+[stem]
+++++
+x = y^2
+++++
+
+////
+comment - content which is not included in the output document
+////
+
+== Tables
+
+.Table Attributes
+[cols=>1h;2d,width=50%,frame=topbot]
+|===
+| Attribute Name | Values
+
+| options
+| header,footer,autowidth
+
+| cols
+| colspec[;colspec;...]
+
+| grid
+| all \| cols \| rows \| none
+
+| frame
+| all \| sides \| topbot \| none
+
+| stripes
+| all \| even \| odd \| none
+
+| width
+| (0%..100%)
+
+| format
+| psv {vbar} csv {vbar} dsv
+|===
+
+== Multimedia
+
+image::screenshot.png[block image,800,450]
+
+Press image:reload.svg[reload,16,opts=interactive] to reload the page.
+
+video::movie.mp4[width=640,start=60,end=140,options=autoplay]
+
+video::aHjpOzsQ9YI[youtube]
+
+video::300817511[vimeo]
+
+== Breaks
+
+// thematic break (aka horizontal rule)
+---
+
+// page break
+<<<

package/index.js

@@ -1 +1,2 @@
-module.exports = require('@asciidoctor/core')
+export { default } from '@asciidoctor/core'
+export * from '@asciidoctor/core'

package/lib/cli.js

@@ -0,0 +1,257 @@
+import { parseArgs } from 'node:util'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join, resolve, isAbsolute, dirname, sep } from 'node:path'
+import {
+  getVersion as _getVersion,
+  getCoreVersion,
+  Timings,
+  Extensions,
+  LoggerManager,
+  convert,
+  convertFile,
+} from '@asciidoctor/core'
+
+const require = createRequire(import.meta.url)
+
+const FAILURE_LEVELS = {
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  WARNING: 2,
+  ERROR: 3,
+  FATAL: 4,
+}
+
+const DOT_RELATIVE_RX = new RegExp(`^\\.{1,2}[/${sep.replace('\\', '\\\\')}]`)
+
+const HELP_TEXT = `asciidoctor [options...] files...
+Translate the AsciiDoc source file or file(s) into the backend output format (e.g., HTML 5, DocBook 5, etc.)
+By default, the output is written to a file with the basename of the source file and the appropriate extension
+
+Options:
+  -b, --backend <backend>           set output format backend
+  -d, --doctype <doctype>           document type [article, book, manpage, inline]
+  -o, --out-file <file>             output file; use '' or '-' for STDOUT
+  -S, --safe-mode <mode>            safe mode level [unsafe, safe, server, secure]
+  -e, --embedded                    suppress enclosing document structure
+  -s, --no-header-footer            suppress enclosing document structure
+  -n, --section-numbers             auto-number section titles in the HTML backend
+  -B, --base-dir <dir>              base directory containing the document and resources
+  -D, --destination-dir <dir>       destination output directory
+      --failure-level <level>       minimum logging level that triggers non-zero exit code [INFO, WARN, ERROR, FATAL]
+  -q, --quiet                       suppress warnings
+      --trace                       include backtrace information on errors
+  -v, --verbose                     enable verbose mode
+  -t, --timings                     enable timings mode
+  -T, --template-dir <dir>          directory with custom converter templates (repeatable)
+  -E, --template-engine <engine>    template engine to use for custom converter templates
+  -a, --attribute <key[=value]>     document attribute to set (repeatable)
+  -r, --require <library>           require the specified library before executing the processor (repeatable)
+  -V, --version                     display the version and runtime environment
+      --help [syntax]               show this help; show AsciiDoc syntax overview if topic is 'syntax'`
+
+function parseCliArgs(argv) {
+  const args = argv.slice(2)
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: false,
+    options: {
+      backend: { type: 'string', short: 'b' },
+      doctype: { type: 'string', short: 'd' },
+      'out-file': { type: 'string', short: 'o' },
+      'safe-mode': { type: 'string', short: 'S' },
+      embedded: { type: 'boolean', short: 'e' },
+      'no-header-footer': { type: 'boolean', short: 's' },
+      'section-numbers': { type: 'boolean', short: 'n' },
+      'base-dir': { type: 'string', short: 'B' },
+      'destination-dir': { type: 'string', short: 'D' },
+      'failure-level': { type: 'string' },
+      quiet: { type: 'boolean', short: 'q' },
+      trace: { type: 'boolean' },
+      verbose: { type: 'boolean', short: 'v' },
+      timings: { type: 'boolean', short: 't' },
+      'template-dir': { type: 'string', short: 'T', multiple: true },
+      'template-engine': { type: 'string', short: 'E' },
+      attribute: { type: 'string', short: 'a', multiple: true },
+      require: { type: 'string', short: 'r', multiple: true },
+      version: { type: 'boolean', short: 'V' },
+      help: { type: 'boolean' },
+    },
+  })
+  return { values, positionals, args }
+}
+
+function buildOptions(values, extraAttrs = []) {
+  const {
+    backend,
+    doctype,
+    'safe-mode': safeMode,
+    embedded,
+    'no-header-footer': noHeaderFooter,
+    'section-numbers': sectionNumbers,
+    'base-dir': baseDir,
+    'destination-dir': destinationDir,
+    'out-file': outFile,
+    'template-dir': templateDir,
+    'template-engine': templateEngine,
+    quiet,
+    verbose,
+    timings,
+    trace,
+    'failure-level': failureLevelStr = 'FATAL',
+    attribute: cliAttributes,
+  } = values
+
+  const level = failureLevelStr.toUpperCase()
+  const failureLevel = FAILURE_LEVELS[level] ?? FAILURE_LEVELS.FATAL
+
+  const attributes = [...extraAttrs]
+  if (sectionNumbers) attributes.push('sectnums')
+  if (cliAttributes) attributes.push(...cliAttributes)
+
+  const standalone = !(embedded || noHeaderFooter)
+  const verboseMode = quiet ? 0 : verbose ? 2 : 1
+
+  const options = {
+    standalone,
+    safe: safeMode ?? 'unsafe',
+    verbose: verboseMode,
+    timings: timings ?? false,
+    trace: trace ?? false,
+    attributes,
+    mkdirs: true,
+  }
+
+  if (backend) options.backend = backend
+  if (doctype) options.doctype = doctype
+  if (baseDir != null) options.base_dir = baseDir
+  if (destinationDir != null) options.to_dir = destinationDir
+  if (templateDir) options.template_dirs = templateDir
+  if (templateEngine) options.template_engine = templateEngine
+
+  const toStdout = outFile === '' || outFile === "''" || outFile === '-'
+  if (toStdout) {
+    options.to_file = false
+  } else if (outFile !== undefined) {
+    options.to_file = outFile
+  }
+
+  return { options, failureLevel, toStdout }
+}
+
+function requireLibrary(requirePath, cwd = process.cwd()) {
+  if (DOT_RELATIVE_RX.test(requirePath)) {
+    requirePath = resolve(cwd, requirePath)
+  } else if (!isAbsolute(requirePath)) {
+    const paths = [cwd, dirname(import.meta.dirname)].map((s) =>
+      join(s, 'node_modules')
+    )
+    requirePath = require.resolve(requirePath, { paths })
+  }
+  return require(requirePath)
+}
+
+function prepareProcessor(values) {
+  const requirePaths = values.require
+  if (!requirePaths) return
+  for (const requirePath of requirePaths) {
+    const lib = requireLibrary(requirePath)
+    if (lib && typeof lib.register === 'function') {
+      lib.register(Extensions)
+    }
+  }
+}
+
+function getVersion() {
+  const pkg = JSON.parse(
+    readFileSync(join(import.meta.dirname, '..', 'package.json'), 'utf8')
+  )
+  return `Asciidoctor.js ${_getVersion()} (Asciidoctor ${getCoreVersion()}) [https://asciidoctor.org]
+Runtime Environment (node ${process.version} on ${process.platform})
+CLI version ${pkg.version}`
+}
+
+function readFromStdin() {
+  return new Promise((resolve, reject) => {
+    let data = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('readable', () => {
+      const chunk = process.stdin.read()
+      if (chunk !== null) data += chunk
+    })
+    process.stdin.on('error', reject)
+    process.stdin.on('end', () => resolve(data.replace(/\n$/, '')))
+  })
+}
+
+async function exit(failureLevel) {
+  const logger = LoggerManager.getLogger()
+  const maxSeverity = logger.getMaxSeverity()
+  const code = maxSeverity !== null && maxSeverity >= failureLevel ? 1 : 0
+  process.exit(code)
+}
+
+export async function run(argv = process.argv) {
+  const { values, positionals, args } = parseCliArgs(argv)
+
+  if (values.version || (values.verbose && args.length === 1)) {
+    console.log(getVersion())
+    process.exit(0)
+  }
+
+  if (values.help) {
+    if (positionals[0] === 'syntax') {
+      console.log(
+        readFileSync(
+          join(import.meta.dirname, '..', 'data', 'reference', 'syntax.adoc'),
+          'utf8'
+        )
+      )
+    } else {
+      console.error(HELP_TEXT)
+    }
+    process.exit(0)
+  }
+
+  prepareProcessor(values)
+  const { options, failureLevel, toStdout } = buildOptions(values)
+
+  // Configure logger verbosity
+  const logger = LoggerManager.getLogger()
+  if (values.quiet)
+    logger.setLevel(3) // ERROR
+  else if (values.verbose) logger.setLevel(0) // DEBUG
+
+  const files = positionals.filter((f) => f !== '-')
+  const isStdin =
+    positionals.includes('-') ||
+    (files.length === 0 && args[args.length - 1] === '-')
+
+  if (isStdin) {
+    const data = await readFromStdin()
+    const output = await convert(data, { ...options, to_file: false })
+    process.stdout.write(output)
+  } else if (files.length > 0) {
+    for (const file of files) {
+      if (values.verbose) console.log(`converting file ${file}`)
+      if (values.timings) {
+        const timings = Timings.create()
+        const fileOptions = { ...options, timings }
+        if (toStdout) fileOptions.to_file = false
+        const result = await convertFile(file, fileOptions)
+        if (toStdout && typeof result === 'string') process.stdout.write(result)
+        timings.printReport(process.stderr, file)
+      } else {
+        const result = await convertFile(file, options)
+        if (toStdout && typeof result === 'string') process.stdout.write(result)
+      }
+    }
+  } else {
+    console.error(HELP_TEXT)
+    process.exit(0)
+  }
+
+  await exit(failureLevel)
+}