Module: Kramdown::AsciiDoc

Defined in:: lib/kramdown-asciidoc/api.rb,
lib/kramdown-asciidoc/cli.rb,
lib/kramdown-asciidoc/writer.rb,
lib/kramdown-asciidoc/version.rb,
lib/kramdown-asciidoc/converter.rb,
lib/kramdown-asciidoc/preprocessors.rb

Defined Under Namespace

Modules: Preprocessors Classes: Cli, Converter, Writer

Constant Summary collapse

DEFAULT_PARSER_OPTS =

{
  auto_ids: false,
  hard_wrap: false,
  html_to_native: true,
  input: 'GFM',
}

DEFAULT_PREPROCESSORS =

[
  (Preprocessors.method :extract_front_matter),
  (Preprocessors.method :replace_toc),
  (Preprocessors.method :trim_before_leading_comment),
]

VERSION =

'2.1.0'

Class Method Summary collapse

.convert(markdown, opts = {}) ⇒ String^?

Converts a Markdown string to an AsciiDoc string and either returns the result or writes it to a file.
.convert_file(markdown_file, opts = {}) ⇒ String^?

Converts a Markdown file to AsciiDoc and writes the result to a file or the specified destination.

Class Method Details

.convert(markdown, opts = {}) ⇒ `String`^?

Converts a Markdown string to an AsciiDoc string and either returns the result or writes it to a file.

Parameters:

markdown (String, IO) —

the Markdown source to convert to AsciiDoc.
opts (Hash) (defaults to: {}) —

additional options to configure the behavior of the converter.

Options Hash (opts):

:auto_ids (Boolean) — default: false —

controls whether converter automatically generates an explicit ID for any section title (aka heading) that doesn’t already have an ID assigned to it.
:auto_id_prefix (String) — default: nil —

the prefix to add to an auto-generated ID.
:auto_id_separator (String) — default: '-' —

the separator to use in auto-generated IDs.
:lazy_ids (Boolean) — default: false —

controls whether to drop the ID if it matches the auto-generated ID value.
:wrap (Symbol) — default: :preserve —

the line wrapping behavior to apply (:preserve, :ventilate, or :none).
:heading_offset (Integer) — default: 0 —

the heading offset to apply to heading levels.
:auto_links (Boolean) — default: true —

whether to allow raw URLs to be recognized as links.
:attributes (Hash) — default: {} —

additional AsciiDoc attributes to add to header of output document; reserved attributes, like stem, may be overridden; some attributes may impact conversion, such as idprefix and idseparator
:imagesdir (String) — default: nil —

the prefix to remove from image references found in the Markdown document; if not specified, the value of the imagesdir attribute is used
:encode (Symbol) — default: true —

whether to reencode the source to UTF-8.
:preprocessors (Array<Proc>) — default: [] —

a list of preprocessors functions to execute on the cleaned Markdown source.
:postprocessors (Array<Proc>) — default: [] —

a list of functions through which to run the output document.
:postprocess (Proc) — default: nil —

a function through which to run the output document (if :postprocessors is falsy).
:to (String, Pathname) — default: nil —

the path to which to write the output document.

Returns:

(String, nil) —

the converted AsciiDoc or nil if the :to option is specified.

# File 'lib/kramdown-asciidoc/api.rb', line 41

def self.convert markdown, opts = {}
  if markdown.respond_to? :read
    markdown = markdown.read
    encode = true
  else
    encode = opts[:encode]
  end
  unless encode == false || (markdown.encoding == UTF_8 && !(markdown.include? CR))
    markdown = markdown.encode UTF_8, universal_newline: true
  end
  markdown = markdown.rstrip
  markdown = markdown.slice 1, markdown.length while markdown.start_with? LF
  parser_opts = DEFAULT_PARSER_OPTS.merge opts
  attributes = (parser_opts[:attributes] = (parser_opts[:attributes] || {}).dup)
  ((opts.fetch :preprocessors, DEFAULT_PREPROCESSORS) || []).each do |preprocessor|
    markdown = preprocessor[markdown, attributes]
  end
  asciidoc = (kramdown_doc = ::Kramdown::Document.new markdown, parser_opts).to_asciidoc
  (opts[:postprocessors] || Array(opts[:postprocess])).each do |postprocessor|
    asciidoc = (postprocessor.arity == 1 ? postprocessor[asciidoc] : postprocessor[asciidoc, kramdown_doc]) || asciidoc
  end
  asciidoc += LF unless asciidoc.empty?
  if (to = opts[:to])
    if ::Pathname === to || (!(to.respond_to? :write) && (to = ::Pathname.new to.to_s))
      to.dirname.mkpath
      to.write asciidoc, encoding: UTF_8
    else
      to.write asciidoc
    end
    nil
  else
    asciidoc
  end
end

.convert_file(markdown_file, opts = {}) ⇒ `String`^?

Converts a Markdown file to AsciiDoc and writes the result to a file or the specified destination.