### Start Custom Pygments Installation Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/syntax-highlighting/pages/pygments.adoc Use this to specify a custom directory for Pygments. This is useful if you have a non-standard installation. ```ruby Pygments.start '/path/to/pygments' ``` -------------------------------- ### Setup Bash Alias for Development Mode Source: https://github.com/asciidoctor/asciidoctor/blob/main/CONTRIBUTING.adoc Example of setting up a Bash alias to easily execute the Asciidoctor development script from any directory. ```bash alias asciidoctor-dev="/path/to/asciidoctor/bin/asciidoctor" ``` -------------------------------- ### Ruby Hello World Example Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/syntax-highlighting/pages/index.adoc A simple 'Hello, World!' example in Ruby, intended for syntax highlighting. ```ruby puts "Hello, World!" ``` -------------------------------- ### Install Required Gems Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/convert/pages/templates.adoc Install the tilt, slim, and concurrent-ruby gems using Bundler or gem install. These are necessary for using Slim templates with Asciidoctor. ```ruby gem 'tilt' gem 'slim' gem 'concurrent-ruby' ``` ```bash $ bundle ``` ```bash $ gem install tilt slim concurrent-ruby ``` -------------------------------- ### Install npm Packages Source: https://github.com/asciidoctor/asciidoctor/blob/main/src/stylesheets/README.adoc Install the necessary npm packages before running build or lint scripts. ```bash npm i ``` -------------------------------- ### Install the AsciiMath Gem Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/stem/pages/asciimath-gem.adoc Run this command to install the AsciiMath gem, which enables AsciiMath to MathML translation for DocBook output. ```bash $ gem install asciimath ``` -------------------------------- ### Install Python and Pygments Gem Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/syntax-highlighting/pages/pygments.adoc Installs Python using the system's package manager and then installs the pygments.rb gem. This is a cross-platform CLI installation method. ```bash $ "$(which apt-get || which dnf || yum || brew)" install python # <.> $ gem install pygments.rb # <.> ``` -------------------------------- ### Complete Example: Logging in a DSL Extension Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/extensions/pages/logging.adoc A full example demonstrating how to include logging within a DSL-defined block processor, including processing and creating content. ```ruby Asciidoctor::Extensions.register do block :custom do singleton_class.include Asciidoctor::Logging on_context :paragraph process do |parent, reader, attrs| logger.warn 'We are logging!' create_paragraph parent, reader.lines, attrs end end end ``` -------------------------------- ### Install Asciidoctor with MacPorts Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/install/pages/macos.adoc Execute this command to install the Asciidoctor port using MacPorts. Ensure MacPorts is installed first. ```bash $ sudo port install asciidoctor ``` -------------------------------- ### Install Tilt and Slim Gems Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/convert/pages/templates.adoc Install the tilt and slim gems using the gem command if you are not using Bundler. These gems are required for Asciidoctor to process Slim templates. ```bash $ gem install tilt slim ``` -------------------------------- ### Install Asciidoctor with Homebrew Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/install/pages/macos.adoc Use this command to install the Asciidoctor gem via Homebrew. Ensure Homebrew is installed first. ```bash $ brew install asciidoctor ``` -------------------------------- ### Video Inclusion (MP4) Source: https://github.com/asciidoctor/asciidoctor/blob/main/data/reference/syntax.adoc Example of embedding an MP4 video with specified width, start, and end times, and autoplay option. ```asciidoc video::movie.mp4[width=640,start=60,end=140,options=autoplay] ``` -------------------------------- ### Example Asciidoc with Man Link Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/extensions/pages/inline-macro-processor.adoc This is an example of Asciidoc syntax using the 'man' inline macro to link to a man page. ```asciidoc See man:gittutorial[7] to get started. ``` -------------------------------- ### Install Asciidoctor via gem install Source: https://github.com/asciidoctor/asciidoctor/blob/main/README.adoc Manually install or upgrade the Asciidoctor gem using the gem command. ```bash $ gem install asciidoctor ``` -------------------------------- ### Install Rouge Gem Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/syntax-highlighting/pages/rouge.adoc Install the Rouge gem using the system's package manager. ```bash $ gem install rouge ``` ```bash $ sudo apt-get install ruby-rouge ``` ```bash $ sudo dnf install rubygem-rouge ``` ```bash $ sudo pacman -S ruby-rouge ``` -------------------------------- ### Install Asciidoctor via Bundler Source: https://github.com/asciidoctor/asciidoctor/blob/main/README.adoc Install the Asciidoctor gem after adding it to your Gemfile. ```bash $ bundle ``` -------------------------------- ### Install Prerelease Asciidoctor Gem Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/install/pages/ruby-packaging.adoc Install a prerelease version (e.g., release candidate) of the Asciidoctor gem using the `--pre` option. Note that prerelease versions may not always be newer than the latest stable version. ```bash $ gem install asciidoctor --pre ``` -------------------------------- ### Table Attributes Example Source: https://github.com/asciidoctor/asciidoctor/blob/main/data/reference/syntax.adoc This example demonstrates Asciidoctor syntax for defining table attributes like columns, frame, and width. ```asciidoc .Table Attributes [cols=>1h;2d,width=50%,frame=ends] |=== | Attribute Name | Values | options | header,footer,autowidth | cols | colspec[;colspec;...] | grid | all \| cols \| rows \| none | frame | all \| sides \| ends \| none | stripes | all \| even \| odd \| none | width | (0%..100%) | format | psv {vbar} csv {vbar} dsv |=== ``` -------------------------------- ### Example AsciiDoc Document Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/convert/pages/templates.adoc A simple AsciiDoc file containing an unordered list that will be styled using a custom template. ```asciidoc * cats * dogs * birds ``` -------------------------------- ### Install Pre-release Asciidoctor via RubyGems Source: https://github.com/asciidoctor/asciidoctor/blob/main/README.adoc Install a pre-release version of the Asciidoctor gem, such as a release candidate. ```bash gem install asciidoctor --pre ``` -------------------------------- ### Install Pry Debugger Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/convert/pages/templates.adoc Install the Pry gem to enable interactive debugging. This is useful for inspecting Asciidoctor's object hierarchy during template rendering. ```bash $ gem install pry ``` -------------------------------- ### Create AsciiDoc Document Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/html-backend/pages/index.adoc Example AsciiDoc content for a document. Ensure the file is saved with the .adoc extension. ```asciidoc include::example$my-document.adoc[tags=title;body] ``` -------------------------------- ### Define a Basic Custom Stylesheet Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/html-backend/pages/custom-stylesheet.adoc Create a CSS file to define custom styles. This example sets the text color to red. ```css body { color: #ff0000; } ``` -------------------------------- ### Example Plain Text Output Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/convert/pages/custom.adoc This is an example of the plain text output generated from an AsciiDoc document using the custom text converter. ```text Document Title Section Title This is the main content. ``` -------------------------------- ### Gemfile for Tilt and Slim Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/convert/pages/templates.adoc Declare the tilt and slim gems in your Gemfile to use Slim templates with Asciidoctor. Ensure you run `bundle` to install them. ```ruby gem 'tilt' gem 'slim' ``` -------------------------------- ### Get Asciidoctor CLI help Source: https://github.com/asciidoctor/asciidoctor/blob/main/README.adoc Display available flags and switches for the Asciidoctor command-line interface. ```bash $ asciidoctor --help ``` -------------------------------- ### Example HTML Output with Attributes Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/convert/pages/custom.adoc Illustrates the HTML output generated by the custom converter when a paragraph includes an ID, role, and title. ```html

What is a wolpertinger? A wolpertinger is a ravenous beast.

``` -------------------------------- ### Install Asciidoctor via MacPorts Source: https://github.com/asciidoctor/asciidoctor/blob/main/README.adoc Use this command to install the Asciidoctor gem if you have MacPorts installed. ```bash sudo port install asciidoctor ``` -------------------------------- ### Initialize Bundler for Project Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/install/pages/ruby-packaging.adoc Create a Gemfile in your project's root directory to manage project-specific gem dependencies. This command initializes a new Gemfile. ```bash $ bundle init ``` -------------------------------- ### Install Asciidoctor on Debian/Ubuntu Source: https://github.com/asciidoctor/asciidoctor/blob/main/README.adoc Use the APT package manager to install Asciidoctor on Debian, Ubuntu, and related distributions. The -y flag automatically confirms the installation. ```shell sudo apt-get install -y asciidoctor ``` -------------------------------- ### Use Custom Highlight.js Library Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/syntax-highlighting/pages/highlightjs.adoc Use a personal copy of Highlight.js by creating a custom bundle, downloading it, and placing it in a folder named `highlight`. Then, set the `:highlightjsdir:` attribute in your AsciiDoc header or use the CLI flag. ```asciidoc :highlightjsdir: highlight ``` -------------------------------- ### Install Asciidoctor on macOS with Homebrew Source: https://github.com/asciidoctor/asciidoctor/blob/main/README.adoc Install the asciidoctor gem on macOS using Homebrew, the popular package manager. Ensure Homebrew is installed first by following its official instructions. ```shell brew install asciidoctor ``` -------------------------------- ### Ruby Syntax Highlighting Example Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/ROOT/pages/features.adoc Demonstrates how to use AsciiDoc syntax for displaying Ruby code with syntax highlighting. Specify the language in the block delimiter. ```ruby phrase = "I love AsciiDoc" puts phrase ``` -------------------------------- ### Configure Rouge Style and Activate Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/syntax-highlighting/pages/rouge.adoc Activate Rouge and set a specific color theme using the `rouge-style` attribute. Includes a Ruby code example. ```asciidoc :source-highlighter: rouge :rouge-style: monokai [,ruby] ---- puts "Hello, Rouge!" ---- ``` -------------------------------- ### Install Asciidoctor on Fedora/CentOS/RHEL Source: https://github.com/asciidoctor/asciidoctor/blob/main/README.adoc Install Asciidoctor on RPM-based Linux distributions like Fedora, CentOS, and RHEL using the DNF package manager. The -y flag confirms the installation. ```shell sudo dnf install -y asciidoctor ``` -------------------------------- ### Navigate to Directory Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/get-started/pages/index.adoc Use the `cd` command to switch to the directory where your AsciiDoc document is saved before running Asciidoctor. ```bash cd directory-name ``` -------------------------------- ### Verify Asciidoctor CLI installation Source: https://github.com/asciidoctor/asciidoctor/blob/main/README.adoc Check if the Asciidoctor command-line interface is installed and accessible. ```bash $ asciidoctor --version ``` -------------------------------- ### Listing Block Example Source: https://github.com/asciidoctor/asciidoctor/blob/main/data/reference/syntax.adoc Use the 'listing' block for program input, source code, or file contents. It's suitable for displaying code snippets. ```text listing - an exhibit that features program input, source code, or the contents of a file ``` -------------------------------- ### Build API Documentation with Yard Source: https://github.com/asciidoctor/asciidoctor/blob/main/CONTRIBUTING.adoc Command to build the API documentation locally using Yard. Assumes Yard options are configured in .yardopts. ```bash bundle exec yard ``` -------------------------------- ### Create Prism.js Syntax Highlighter Adapter Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/syntax-highlighting/pages/custom.adoc Implement a new adapter for the Prism.js client-side syntax highlighter. This adapter only needs to implement methods for client-side highlighting. ```ruby require 'asciidoctor/syntax_highlighter/base' class PrismSyntaxHighlighter < Asciidoctor::SyntaxHighlighter::Base def format(source, lang, opts = {}) # Use Prism.js to highlight the source code # For example, using a shell command: # "prism --languages=#{lang} --no-line-numbers -- #{source}" # Or, if you have the Prism.js library loaded in your Ruby environment: # Prism.highlight(source, Prism::Language.get_by_name(lang)) # For this example, we'll just wrap the source in a pre tag # with a class for Prism.js to pick up. %(
#{escape_html(source)}
) end def docinfo? false end def docinfo(doc, format, opts) nil end end Asciidoctor::SyntaxHighlighter.register 'prism', PrismSyntaxHighlighter ``` -------------------------------- ### Specify Template Directory and Engine (CLI) Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/convert/pages/templates.adoc Use the -r option to load a JAR file containing templates and the -T option to specify the template directory. The -E option sets the template engine. ```bash $ asciidoctor -r /path/to/templates.jar -T uri:classloader:/path/to/templates -E slim doc.adoc ``` -------------------------------- ### List Output Files Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/html-backend/pages/index.adoc Verify the generated HTML file exists in the directory after conversion. ```bash $ ls my-document.adoc my-document.html ``` -------------------------------- ### Initialize Pygments Ruby Script Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/syntax-highlighting/pages/pygments.adoc This script is intended to be run before invoking Asciidoctor for the first time to set up Pygments. ```ruby require 'pygments' ``` -------------------------------- ### Get HTML5 Converter Class Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/convert/pages/custom.adoc Use `Asciidoctor::Converter.for` to get the converter class registered for a specific backend, such as `html5`. ```ruby Asciidoctor::Converter.for 'html5' ``` -------------------------------- ### AsciiMath Expression Example Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/stem/pages/mathjax.adoc An example of a mathematical expression written in AsciiMath syntax. When processed by MathJax, this will be rendered as a formatted mathematical equation. ```asciimath e = sum_(n=0)^oo 1 / n! ``` -------------------------------- ### Sample AsciiDoc with Front Matter Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/extensions/pages/preprocessor.adoc This AsciiDoc file includes front matter delimited by '---' which can be processed by a preprocessor extension. ```asciidoc --- tags: [announcement, website] --- = Document Title content [subs=+attributes] .Captured front matter ---- --- {front-matter} --- ---- ``` -------------------------------- ### Example DITA XML Output Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/convert/pages/custom.adoc This is an example of the DITA XML output generated from an AsciiDoc document using the custom DITA converter. ```xml Document Title
Section Title

This is the main content.

 ``` -------------------------------- ### Install Asciidoctor on Alpine Linux Source: https://github.com/asciidoctor/asciidoctor/blob/main/README.adoc Use the apk package manager to install the asciidoctor gem on Alpine Linux. This command requires sudo privileges. ```shell sudo apk add asciidoctor ``` -------------------------------- ### Exclude First Block from Results Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/api/pages/find-blocks.adoc The `find_by` method includes the starting block in its results. To exclude it, slice the result array starting from the second element. ```ruby puts doc.find_by.slice 1..-1 ``` -------------------------------- ### Preview HTML in Terminal Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/html-backend/pages/index.adoc Convert AsciiDoc to HTML and pipe the output to `w3m` for terminal preview. ```bash $ asciidoctor my-document.adoc -o - | w3m - -T text/html ``` -------------------------------- ### Install Asciidoctor via RubyGems Source: https://github.com/asciidoctor/asciidoctor/blob/main/README.adoc Install the Asciidoctor gem using the gem command. It's recommended to use a Ruby version manager like RVM. ```bash gem install asciidoctor ``` -------------------------------- ### Test Open Block Syntax with Minitest Source: https://github.com/asciidoctor/asciidoctor/blob/main/CONTRIBUTING.adoc Example of testing AsciiDoc open block syntax using Minitest. It defines input, renders it, and asserts CSS/XPath expressions. ```ruby test 'should render content bounded by two consecutive hyphens as an open block' do input = <<-EOS -- This is an open block. -- EOS result = render_embedded_string input assert_css '.openblock', result, 1 assert_css '.openblock p', result, 1 assert_xpath '/div[@class="openblock"]//p[text()="This is an open block."]', result, 1 end ``` -------------------------------- ### Install Asciidoctor on Arch Linux Source: https://github.com/asciidoctor/asciidoctor/blob/main/README.adoc Install the asciidoctor package on Arch Linux and its derivatives using the pacman package manager. This command requires sudo privileges. ```shell sudo pacman -S asciidoctor ``` -------------------------------- ### Running the fopub Script Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/docbook-backend/pages/index.adoc Command to convert a DocBook XML file to PDF using the fopub script. This assumes fopub has been cloned from its repository. ```bash $ ./fopub README.xml ``` -------------------------------- ### Java Interface Example with Formatting Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/syntax-highlighting/pages/index.adoc An example of a Java interface within a source block that incorrectly uses AsciiDoc text formatting, which can interfere with syntax highlighting. ```asciidoc [,java,subs=+quotes] ---- interface OrderRepository extends CrudRepository { *List* findByCategory(String category); Order findById(long id); } ---- ``` -------------------------------- ### Registering and Using the Preprocessor Extension Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/extensions/pages/preprocessor.adoc This Ruby code demonstrates how to register a custom preprocessor extension with Asciidoctor and then convert a file using that extension. ```ruby Asciidoctor::Extensions.register do preprocessor FrontMatterPreprocessor end Asciidoctor.convert_file 'sample-with-front-matter.adoc', safe: :safe ``` -------------------------------- ### Register and Use Docinfo Processor Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/extensions/pages/docinfo-processor.adoc Shows how to register the custom Docinfo Processor with Asciidoctor and how to convert a file while passing the Google Analytics account ID as an attribute. ```ruby Asciidoctor::Extensions.register do docinfo_processor GoogleAnalyticsDocinfoProcessor end Asciidoctor.convert_file 'sample.adoc', safe: :safe, attributes: 'google-analytics-account=UA-ABCXYZ123' ``` -------------------------------- ### Example AsciiDoc Man Page Source Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/manpage-backend/pages/index.adoc This is an example of an AsciiDoc document structured for a man page. It declares the `manpage` doctype and follows the expected section order and content format. ```asciidoc ifndef::examples[] :examples: ../examples endif::[] = eve(1) == NAME eve - example man page == SYNOPSIS *eve* [OPTION]... [FILE]... == DESCRIPTION This is an example man page for the `eve` command. == OPTIONS * -h, --help:: Display this help and exit. * -v, --version:: Output version information and exit. == AUTHOR Written by the Asciidoctor team. == REPORTING BUGS Report bugs to ``` -------------------------------- ### Install Asciidoctor Mathematical Gem Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/stem/pages/mathematical.adoc Install the asciidoctor-mathematical gem using the Ruby package manager. Note that this gem has native dependencies that may require specific build tools and libraries. ```bash $ gem install asciidoctor-mathematical ``` -------------------------------- ### Produce XHTML using Backend Option Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/html-backend/pages/index.adoc Generate XHTML output by specifying the `xhtml5` backend option with the `asciidoctor` command. ```bash $ asciidoctor -b xhtml5 my-document.adoc ``` -------------------------------- ### Install Asciidoctor Gem with Bundler Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/install/pages/ruby-packaging.adoc Add the Asciidoctor gem to your Gemfile and install it using Bundler. Always run executables with `bundle exec` to ensure the correct gem version is used. ```ruby gem 'asciidoctor', '{release-version}' ``` ```bash $ bundle ``` ```bash $ bundle exec asciidoctor ``` -------------------------------- ### Activate Highlight.js Source: https://github.com/asciidoctor/asciidoctor/blob/main/docs/modules/syntax-highlighting/pages/highlightjs.adoc To activate Highlight.js, add the `:source-highlighter:` attribute to your AsciiDoc file header. This will link to the Highlight.js library and stylesheet hosted on a CDN. ```asciidoc :source-highlighter: highlight.js ``` -------------------------------- ### Install Asciidoctor Gem Source: https://github.com/asciidoctor/asciidoctor/blob/main/README.adoc Add the Asciidoctor gem to your Gemfile to manage its version. ```ruby gem 'asciidoctor', '{release-version}' ``` -------------------------------- ### Build Default Stylesheet Source: https://github.com/asciidoctor/asciidoctor/blob/main/src/stylesheets/README.adoc Run the npm build script to regenerate the default stylesheet. ```bash npm run build ``` -------------------------------- ### Wistia Video Inclusion Source: https://github.com/asciidoctor/asciidoctor/blob/main/data/reference/syntax.adoc Example of embedding a Wistia video using its ID. ```asciidoc video::e4a27b971d[wistia] ```