### Clone Repository and Install Dependencies Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/CONTRIBUTING-CODE.adoc Clone the Asciidoctor.js repository and install project dependencies using npm. This is the initial setup step for any contributor. ```bash git clone https://github.com/asciidoctor/asciidoctor.js.git cd asciidoctor.js npm i ``` -------------------------------- ### Admonition Block (Example) Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/packages/asciidoctor/data/reference/syntax.adoc Use the `example` block type (`==== ... ====`) to present a demonstration of a concept. ```asciidoc [NOTE] ==== admonition - a notice for the reader, ranging in severity from a tip to an alert ==== ==== example - a demonstration of the concept being documented ==== ``` -------------------------------- ### Example API Doc Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/extend/pages/extensions/postprocessor.adoc This is a sample AsciiDoc file used to demonstrate the postprocessor extension. ```adoc = API Reference == Authentication Send your API key in the request header: [source,shell] ---- curl -H "Authorization: Bearer " https://api.example.com/v1/users ---- ``` -------------------------------- ### Example JSON Data Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/extend/pages/extensions/include-processor.adoc This is a sample JSON file that will be included and processed by the extension. ```json { "version": "3.1.0", "node-min": "18" } ``` -------------------------------- ### CLI Tests Setup Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/CONTRIBUTING-CODE.adoc Imports and setup for command-line interface (CLI) tests in Asciidoctor.js. Includes Node.js built-in modules for testing and child process spawning. ```js import { test, describe } from 'node:test' import assert from 'node:assert/strict' import { spawnSync } from 'node:child_process' import { join, dirname } from 'node:path' import { fileURLToPath } from 'node:url' const __dirname = dirname(fileURLToPath(import.meta.url)) const CLI = join(__dirname, '..', 'bin', 'asciidoctor') ``` -------------------------------- ### Checklist Example Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/packages/asciidoctor/data/reference/syntax.adoc Create checklists using list items with `[x]` for checked items and `[ ]` for unchecked items. ```asciidoc * [x] checked * [ ] not checked ``` -------------------------------- ### Description List Example Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/packages/asciidoctor/data/reference/syntax.adoc Create description lists using `term:: description` syntax. ```asciidoc first term:: description of first term second term:: description of second term ``` -------------------------------- ### Snippet A Example Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/packages/core/test/fixtures/include-file.adoc This is the first tagged snippet from the included file. ```asciidoc snippetA content ``` -------------------------------- ### Install Asciidoctor.js CLI with npm Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/cli/pages/install.adoc Install Asciidoctor.js and the CLI globally using npm. This makes the `asciidoctor` command available system-wide. ```bash npm i -g asciidoctor ``` -------------------------------- ### Asciidoctor.js CLI Version Output Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/cli/pages/install.adoc This is an example of the output you should expect when verifying the Asciidoctor.js CLI installation. ```text Asciidoctor.js 4.0.0-alpha.0 (Asciidoctor 2.0.26) [https://asciidoctor.org] Runtime Environment (node v24.14.1 on darwin) CLI version 4.0.0-alpha.0 ``` -------------------------------- ### Snippet B Example Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/packages/core/test/fixtures/include-file.adoc This is the second tagged snippet from the included file. ```asciidoc snippetB content ``` -------------------------------- ### Verify Asciidoctor.js CLI Installation Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/cli/pages/install.adoc Execute this command to confirm that the Asciidoctor.js CLI has been installed successfully and is accessible on your system's PATH. ```bash asciidoctor --version ``` -------------------------------- ### Install Asciidoctor.js CLI with Yarn Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/cli/pages/install.adoc If you prefer Yarn, you can install Asciidoctor.js and the CLI globally using this command. This makes the `asciidoctor` command available system-wide. ```bash yarn global add asciidoctor ``` -------------------------------- ### CLI Usage Example Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/extend/pages/extensions/block-processor.adoc This command shows how to apply the `callout-block.js` extension when converting an AsciiDoc file using the Asciidoctor CLI. ```bash $ asciidoctor --extension ./callout-block.js sample-callout-doc.adoc ``` -------------------------------- ### Install Asciidoctor.js with npm Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/setup/pages/install.adoc Use this command to install the Asciidoctor.js core package using npm. Ensure you have an active Node LTS release installed. ```bash $ npm i @asciidoctor/core ``` -------------------------------- ### Install Asciidoctor.js with Yarn Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/setup/pages/install.adoc Alternatively, install the Asciidoctor.js core package using Yarn. This is a direct replacement for the npm installation command. ```bash yarn add @asciidoctor/core ``` -------------------------------- ### Configure Self-Hosted highlight.js Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/extend/pages/syntax-highlighter/syntax-highlighting.adoc Demonstrates how to configure Asciidoctor.js to load highlight.js assets from a self-hosted location instead of a CDN. Set the `highlightjsdir` attribute to the base URL of your installation. ```javascript await convert(content, { standalone: true, attributes: { 'source-highlighter': 'highlightjs', 'highlightjsdir': '/assets/highlight.js', }, }) ``` -------------------------------- ### Core Tests Setup Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/CONTRIBUTING-CODE.adoc Import necessary modules for writing core tests in Asciidoctor.js. Includes test runners, assertion utilities, and custom harness functions. ```js import { test, describe } from 'node:test' import assert from 'node:assert/strict' import { convertStringToEmbedded, documentFromString } from './harness.js' import { assertXpath } from './helpers.js' ``` -------------------------------- ### Get Asciidoctor.js CLI Help Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/cli/pages/quick-tour.adoc Execute this command to display the full help message for the Asciidoctor.js CLI, including all available options. ```bash asciidoctor --help ``` -------------------------------- ### Server-Side Highlighting with highlight.js (npm) Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/extend/pages/syntax-highlighter/syntax-highlighting.adoc A minimal example demonstrating how to implement a server-side syntax highlighter using the highlight.js npm package. This processes source code at conversion time, embedding highlighted markup directly into the HTML. ```javascript import { load, SyntaxHighlighterBase } from '@asciidoctor/core' import hljs from 'highlight.js' // npm install highlight.js class HljsServerHighlighter extends SyntaxHighlighterBase { handlesHighlighting() { return true // <1> } ``` -------------------------------- ### API Usage Example Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/extend/pages/extensions/block-processor.adoc This JavaScript code demonstrates how to register and use the `CalloutBlock` extension with Asciidoctor Core programmatically. ```javascript import { Extensions, convertFile } from '@asciidoctor/core' import { register } from './callout-block.js' const registry = Extensions.create() register(registry) const html = await convertFile('sample-callout-doc.adoc', { to_file: false, extension_registry: registry }) console.log(html) // // ``` -------------------------------- ### Run Core Test Suite under Deno Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/CONTRIBUTING-CODE.adoc Execute the Asciidoctor.js core test suite using Deno. Requires Deno to be installed and specific permissions to be granted. ```bash npm run test:deno -w @asciidoctor/core ``` -------------------------------- ### Node.js Setup with CommonJS Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/setup/pages/install.adoc Import the Asciidoctor.js convert function in a Node.js environment using CommonJS syntax. This is useful for older Node.js projects or specific build setups. ```js const { convert } = require('@asciidoctor/core') ``` -------------------------------- ### Writing CLI Tests Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/CONTRIBUTING-CODE.adoc Example of a CLI test case. It uses the `cli` helper function to run the Asciidoctor binary with a flag and asserts the exit status and standard output. ```js describe('My CLI feature', () => { test('--my-flag behaves correctly', () => { const result = cli(['--my-flag']) assert.equal(result.status, 0) assert.match(result.stdout, /expected output/) }) }) ``` -------------------------------- ### Basic Browser Setup with ES Modules Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/setup/pages/install.adoc Import the Asciidoctor.js convert function in a script tag for browser environments using ES modules. Local testing requires serving files through a server due to CORS. ```html ``` -------------------------------- ### Run CLI Test Suite under Deno Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/CONTRIBUTING-CODE.adoc Execute the Asciidoctor.js CLI test suite using Deno. Requires Deno to be installed and specific permissions to be granted. ```bash npm run test:deno -w asciidoctor ``` -------------------------------- ### Callout List Example Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/packages/asciidoctor/data/reference/syntax.adoc Use callouts in code blocks to provide explanations for specific lines. Enable callout bubbles by setting `:icons: font` in the document header. ```asciidoc // enable callout bubbles by adding `:icons: font` to the document header [,ruby] ---- puts 'Hello, World!' # <1> ---- <1> Prints `Hello, World!` to the console. ``` -------------------------------- ### Convert Document with Registered Custom Converter Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/extend/pages/converter/custom-converter.adoc After registering a custom converter, load and convert a document to see the custom transformations applied. This example demonstrates converting a document with sections using the custom logic. ```js import { ConverterFactory, load } from '@asciidoctor/core' ConverterFactory.register(new CustomConverter(), ['html5']) const doc = await load(`= Title == Section 1 == Section 2`) console.log(await doc.convert()) // Prints: // // Section 1 // Section 2 // ``` -------------------------------- ### Unordered List Example Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/packages/asciidoctor/data/reference/syntax.adoc Create nested unordered lists using asterisks. Attach a block or paragraph to a list item using a list continuation. ```asciidoc * 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). ``` -------------------------------- ### Ordered List Example Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/packages/asciidoctor/data/reference/syntax.adoc Create nested ordered lists using periods. Use block attributes like `[upperroman]` to change the numbering style. ```asciidoc . Step 1 . Step 2 .. Step 2a .. Step 2b . Step 3 .Remember your Roman numerals? [upperroman] . is one . is two . is three ``` -------------------------------- ### Video Block Syntax Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/packages/asciidoctor/data/reference/syntax.adoc Embed videos using the `video::` macro. You can specify the filename, width, start and end times, and options like autoplay. ```asciidoc video::movie.mp4[width=640,start=60,end=140,options=autoplay] ``` -------------------------------- ### Sidebar Block Example Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/packages/asciidoctor/data/reference/syntax.adoc Use the `sidebar` block type (`**** ... ****`) for auxiliary content that can be read independently of the main content. ```asciidoc **** sidebar - auxiliary content that can be read independently of the main content **** ``` -------------------------------- ### Customize `
` Wrapper

Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/extend/pages/syntax-highlighter/custom-syntax-highlighter.adoc

Override the `format()` method in `SyntaxHighlighterBase` to control the HTML wrapper for source blocks. Call `node.content()` to get the processed source and return the desired `
` structure.

```js
import { SyntaxHighlighterBase } from '@asciidoctor/core'

class MinimalHighlighter extends SyntaxHighlighterBase {
  async format(node, lang, opts) {
    const content = await node.content()
    return `
${content}
`
  }
}
```

--------------------------------

### Writing Core Tests

Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/CONTRIBUTING-CODE.adoc

Example of a core test case using `describe` and `test` for asynchronous Asciidoctor.js conversion. Asserts the output of embedded Asciidoc input.

```js
describe('My feature', () => {
  test('does the right thing', async () => {
    const output = await convertStringToEmbedded('some _asciidoc_ input')
    assertXpath(output, '//em[text()="asciidoc"]', 1)
  })
})
```

--------------------------------

### Get Built-in Converter and Handle Unknown Formats in Asciidoctor.js

Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/CHANGELOG.adoc

Illustrates how to retrieve a built-in converter (e.g., 'html5') and demonstrates that calling `ConverterFactory.for` with an unknown format returns undefined. Useful for checking converter availability.

```js
const builtinHtml5Converter = asciidoctor.ConverterFactory.for('html5')
builtinHtml5Converter.convert()

asciidoctor.ConverterFactory.for('foo') // undefined
```

--------------------------------

### Node.js Setup with ES Modules

Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/setup/pages/install.adoc

Import the Asciidoctor.js convert function in a Node.js environment using ES module syntax. This is the standard way to import modules in modern Node.js.

```js
import { convert } from '@asciidoctor/core'
```

--------------------------------

### Configure Pug Doctype with Cache Disabled

Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/extend/pages/converter/template-converter.adoc

Example demonstrating how to disable the template cache and configure a specific Pug doctype for XML output. This ensures that template configurations are re-applied on subsequent conversions.

```javascript
import { convert } from '@asciidoctor/core'

const options = {
  safe: 'safe',
  doctype: 'inline',
  backend: 'html5',
  template_dir: '/path/to/templates/pug',
  template_cache: false, // disable template cache
}

console.log(await convert(`image:cat.png[]`, options)) // 
console.log(await convert('image:cat.png[]', Object.assign(options, {
  template_engine_options: {
    pug: {
      doctype: 'xml'
    }
  }
}))) // 
```

--------------------------------

### Convert Document with Options

Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/processor/pages/convert-options.adoc

Use the `convert` function to process content with specified options, such as safe mode and attributes. This example shows how to set the `safe` option to 'server' and define custom attributes like `showtitle` and `icons`.

```js
import { convert } from '@asciidoctor/core'

const content = '= Document title'
const html = await convert(content, { safe: 'server', attributes: { showtitle: true, icons: 'font' } })
console.log(html)
// 
Document title

```

--------------------------------

### Use helper function in a video.js template

Source: https://github.com/asciidoctor/asciidoctor.js/blob/main/docs/modules/extend/pages/converter/template-converter.adoc

This example demonstrates how to use exported functions from `helpers.js` within a template. The `getAssetUriScheme` function is called to construct a YouTube embed URL.

```js
export default function ({ node, _, helpers }) {
  const target = node.getAttribute('target')
  const document = node.getDocument()
  const src = `${helpers.getAssetUriScheme(document)}//www.youtube.com/embed/${target}` // <1>
  return `