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,
lib/kramdown-asciidoc/core_ext/regexp/is_match.rb

Defined Under Namespace

Modules: CoreExt, 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

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.



41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
# 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.

Parameters:

  • markdown_file (String, File)

    the Markdown file or file path 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

  • :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 document if the :to option is specified and is falsy, otherwise nil.



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
# File 'lib/kramdown-asciidoc/api.rb', line 98

def self.convert_file markdown_file, opts = {}
  if ::File === markdown_file
    markdown = markdown_file.read
    markdown_file = markdown_file.path
    encode = true
  else
    markdown = ::File.read markdown_file, mode: 'r:UTF-8', newline: :universal
    encode = false
  end
  if (to = opts[:to])
    to = ::Pathname.new to.to_s unless ::Pathname === to || (to.respond_to? :write)
  elsif !(opts.key? :to)
    to = (::Pathname.new markdown_file).sub_ext '.adoc'
    raise ::IOError, %(input and output cannot be the same file: #{markdown_file}) if to.to_s == markdown_file.to_s
  end
  convert markdown, (opts.merge to: to, encode: encode)
end