Inkmark

https://github.com/yaroslav/inkmark
Admin
Very fast, feature-packed, AI-first Markdown gem for Ruby with CommonMark and GFM support.
Tokens:81,778
Snippets:789
Trust Score:9.5
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install dependencies with Bundler

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmarker-readme.md

Installs the gem dependencies listed in the Gemfile.

```bash
$ bundle
```

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

### Markdown list example

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmark-spec.md

Shows the equivalent Markdown for the AsciiDoc example, using indentation to indicate nesting and continuation.

```markdown
1.  List item one.

    List item one continued with a second paragraph followed by an
    Indented block.

        $ ls *.sh
        $ mv *.sh ~/tmp

    List item continued with a third paragraph.

2.  List item two continued with an open block.

    This paragraph is part of the preceding list item.

    1. This list is nested and does not require explicit item continuation.

       This paragraph is part of the preceding list item.

    2. List item b.

    This paragraph belongs to item two of the outer list.
```

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

### Install inkmark with Bundler

Source: https://github.com/yaroslav/inkmark/blob/main/README.md

Adds the inkmark gem to the Gemfile and installs it. Requires Ruby 3.3+; the gem is precompiled so no compiler toolchain is needed.

```shell
bundle add inkmark
```

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

### Install gem manually

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmarker-readme.md

Installs the commonmarker gem directly without Bundler.

```bash
$ gem install commonmarker
```

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

### Run benchmark harness

Source: https://github.com/yaroslav/inkmark/blob/main/README.md

Install the benchmark harness and run it locally. Requires the benchmark group to be enabled via bundle config.

```bash
bundle config set with benchmark
bundle install
bundle exec rake benchmark
```

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

### Bootstrap and compile Commonmarker locally

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmarker-readme.md

Run these commands after cloning the repository to set up the development environment and compile the native extension. If there are no errors, the setup is complete.

```shell
script/bootstrap
bundle exec rake compile
```

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

### Example .env file contents

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/large-4k.md

Add your application configuration to your .env file in the root of your project. These variables will be available in ENV whenever your application loads.

```shell
S3_BUCKET=YOURS3BUCKET
SECRET_KEY=YOURSECRETKEYGOESHERE
```

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

### Install Redcarpet 2.3.0 for Ruby 1.8.7

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/redcarpet-readme.md

Installs Redcarpet version 2.3.0 for use with Ruby 1.8.7.

```shell
$ [sudo] gem install redcarpet -v 2.3.0
```

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

### Use Inkmark presets and override options

Source: https://github.com/yaroslav/inkmark/blob/main/README.md

Shows how to use the built-in presets (`:recommended`, `:gfm`, `:trusted`) and override individual options. The `:recommended` preset is a good starting point; `:trusted` passes raw HTML through and is dangerous—only use with fully trusted content.

```ruby
# Recommended profile
Inkmark.to_html(md, options: { preset: :recommended })

# Recommended profile with stats and table of contents
Inkmark.to_html(md, options: { preset: :recommended, statistics: true, toc: true })

# Recommended profile, but disable smart punctuation
Inkmark.to_html(md, options: { preset: :recommended, smart_punctuation: false })

# Just GFM (the default)
Inkmark.to_html(md)
Inkmark.to_html(md, options: { preset: :gfm })     # equivalent

# Recommended profile with a tightened link-host allowlist
Inkmark.to_html(md, options: {
  preset: :recommended,
  links:  { allowed_hosts: ["*.example.com"] }
})

# Trusted content (raw HTML passes through—use with care)
Inkmark.to_html(internal_doc, options: { preset: :trusted })
```

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

### Install dotenv gem in Gemfile

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/large-4k.md

Add this line to the top of your application's Gemfile and run bundle install. It loads dotenv only in development and test groups.

```ruby
gem 'dotenv', groups: [:development, :test]
```

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

### AsciiDoc list example

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmark-spec.md

Shows a complex list in AsciiDoc with continuation, indented block, and nested list. The indented block contains shell commands.

```asciidoc
1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.

2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.

a. This list is nested and does not require explicit item
continuation.
+
This paragraph is part of the preceding list item.

b. List item b.

This paragraph belongs to item two of the outer list.
--
```

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

### Convert Markdown to HTML with Commonmarker.to_html

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmarker-readme.md

Use Commonmarker.to_html to convert Markdown to HTML. The example shows the output for the input '*Hello* world!', which is '<p><em>Hello</em> world!</p>'.

```ruby
puts Commonmarker.to_html('*Hello* world!')

# <p><em>Hello</em> world!</p>
```

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

### Example of scheme filtering with javascript: and data: URLs

Source: https://github.com/yaroslav/inkmark/blob/main/README.md

Demonstrates scheme filtering with example inputs and outputs. A javascript: link is unwrapped to its text, and a data: image drops to its alt text. Scheme filtering applies only to Markdown-emitted links and images; raw HTML inside raw_html: true content is not filtered.

```ruby
opts = { links: { allowed_schemes: ["http", "https"] } }

Inkmark.to_html("[click](javascript:alert(1))", options: opts)
# => "<p>click</p>\n"

Inkmark.to_html("![pic](data:image/svg+xml,<svg/onload=evil()>)",
               options: { images: { allowed_schemes: ["http", "https"] } })
# => "<p>pic</p>\n"   # dropped to alt text
```

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

### Commonmarker.to_html with parse and render options

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmarker-readme.md

Passes parse and render options as a hash with symbol keys to Commonmarker.to_html. The example enables smart punctuation parsing and disables hard line breaks in rendering. Options are passed as a nested hash under the :options key.

```ruby
Commonmarker.to_html('"Hi *there*"', options:{
  parse: { smart: true },
  render: { hardbreaks: false}
})
```

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

### Add inkmark to Gemfile

Source: https://github.com/yaroslav/inkmark/blob/main/README.md

Alternative installation: manually add the gem to the Gemfile. Requires Ruby 3.3+; the gem is precompiled so no compiler toolchain is needed.

```ruby
gem "inkmark"
```

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

### Both left and right-flanking delimiter run examples

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmark-spec.md

Delimiter runs that are both left-flanking and right-flanking, as defined in the CommonMark spec.

```markdown
 abc***def
"abc"_"def"
```

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

### Collect images missing alt text with #walk

Source: https://github.com/yaroslav/inkmark/blob/main/README.md

Use `#walk` to fire handlers without producing HTML, for analysis. This example collects images missing alt text and raises an error if any are found.

```ruby
# Check that every image has alt text
md = Inkmark.new(source)
missing_alt = []
md.on(:image) { |img| missing_alt << img.dest if img.text.empty? }
md.walk
raise "Images missing alt text: #{missing_alt.join(', ')}" if missing_alt.any?
```

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

### Suppress elements with delete

Source: https://github.com/yaroslav/inkmark/blob/main/README.md

Call `delete` on any event to omit it from the output. Children are suppressed along with their parent. The example deletes all images and headings whose text starts with `INTERNAL:`.

```ruby
md.on(:image)   { |img| img.delete }                                  # all images
md.on(:heading) { |h|   h.delete if h.text.start_with?("INTERNAL:") } # by content
```

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

### Redcarpet::Render::HTML.new

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/redcarpet-readme.md

Initializes an HTML renderer with various rendering options.

```APIDOC
## Redcarpet::Render::HTML.new

### Description
Initializes an HTML renderer with various rendering options.

### Method
Redcarpet::Render::HTML.new(render_options = {})

### Parameters
#### Options
- **:filter_html** (Boolean) - Optional - Do not allow any user-inputted HTML in the output.
- **:no_images** (Boolean) - Optional - Do not generate any `<img>` tags.
- **:no_links** (Boolean) - Optional - Do not generate any `<a>` tags.
- **:no_styles** (Boolean) - Optional - Do not generate any `<style>` tags.
- **:escape_html** (Boolean) - Optional - Escape any HTML tags. This option has precedence over `:no_styles`, `:no_links`, `:no_images` and `:filter_html`.
- **:safe_links_only** (Boolean) - Optional - Only generate links for protocols which are considered safe.
- **:with_toc_data** (Boolean) - Optional - Add HTML anchors to each header in the output HTML.
- **:hard_wrap** (Boolean) - Optional - Insert HTML `<br>` tags inside paragraphs where the original Markdown document had newlines.
- **:xhtml** (Boolean) - Optional - Output XHTML-conformant tags. This option is always enabled in the `Render::XHTML` renderer.
- **:prettify** (Boolean) - Optional - Add prettyprint classes to `<code>` tags for google-code-prettify.
- **:link_attributes** (Hash) - Optional - Hash of extra attributes to add to links.

### Example
```ruby
renderer = Redcarpet::Render::HTML.new(no_links: true, hard_wrap: true)
```
```

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

### Install Redcarpet gem

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/redcarpet-readme.md

Installs the Redcarpet gem. Requires Ruby 1.9.2 or later (or Rubinius in 1.9 mode) as of Redcarpet 3.0.

```shell
$ [sudo] gem install redcarpet
```

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

### Redcarpet::Markdown.new

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/redcarpet-readme.md

Initializes a Markdown processor with a renderer and optional extensions.

```APIDOC
## Redcarpet::Markdown.new

### Description
Initializes a Markdown processor with a renderer and optional extensions.

### Method
Redcarpet::Markdown.new(renderer, extensions = {})

### Parameters
#### Renderer
- **renderer** (Object) - Required - The renderer instance to use for output.

#### Extensions
- **autolink** (Boolean) - Optional - Automatically generate links for URLs and email addresses.
- **tables** (Boolean) - Optional - Enable Markdown table syntax.

### Example
```ruby
markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML, autolink: true, tables: true)
```
```

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

### Filter events with parent_kind and ancestor_kinds

Source: https://github.com/yaroslav/inkmark/blob/main/README.md

Uses ancestor_kinds and parent_kind to filter events based on context. The image example deletes images inside links; the paragraph example processes only top-level paragraphs.

```ruby
# Skip decorative images that are already inside a link
md.on(:image) { |img| img.delete if img.ancestor_kinds.include?(:link) }

# Only process top-level paragraphs
md.on(:paragraph) do |p|
  next unless p.parent_kind.nil?
  # ... only top-level paragraphs reach here
end
```

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

### Load multiple .env files with dotenv

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/large-4k.md

Pass in multiple files and they will be loaded in order. The first value set for a variable will win.

```ruby
require 'dotenv'
Dotenv.load('file1.env', 'file2.env')
```

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

### Backtick code span edge cases

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmark-spec.md

Examples from the CommonMark spec showing that unclosed backtick strings are treated as literal backticks, and that opening and closing backtick strings must be equal in length. Each example shows the Markdown input followed by the expected HTML output.

```markdown
```foo``
.
<p>```foo``</p>
```

```markdown
`foo
.
<p>`foo</p>
```

```markdown
`foo``bar``
.
<p>`foo<code>bar</code></p>
```

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

### Shortcut reference link

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmark-spec.md

Shortcut reference link: [foo] is equivalent to [foo][].

```markdown
[foo]

[foo]: /url "title"
```

```html
<p><a href="/url" title="title">foo</a></p>
```

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

### Run script with dotenv CLI

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/large-4k.md

Use the dotenv executable to load .env before launching your application.

```console
$ dotenv ./script.rb
```

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

### Right-flanking delimiter run examples

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmark-spec.md

Delimiter runs that are right-flanking but not left-flanking, as defined in the CommonMark spec.

```markdown
 abc***
 abc_
"abc"**
"abc"_
```

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

### Syntax highlighter plugin usage with theme option

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmarker-readme.md

Shows how to render Markdown with syntax highlighting using the Commonmarker.to_html method and a syntax_highlighter plugin. Pass a theme name from the pre-existing set, such as "InspiredGitHub", to override the default "base16-ocean.dark" theme. The output is an HTML <pre> block with inline styles for syntax highlighting.

```ruby
code = <<~CODE
  ```ruby
  def hello
    puts "hello"
  end
  ```
CODE

# pass in a theme name from a pre-existing set
puts Commonmarker.to_html(code, plugins: { syntax_highlighter: { theme: "InspiredGitHub" } })

# <pre style="background-color:#ffffff;" lang="ruby"><code>
# <span style="font-weight:bold;color:#a71d5d;">def </span><span style="font-weight:bold;color:#795da3;">hello
# </span><span style="font-weight:bold;color:#a71d5d;">puts </span><span style="color:#a71d5d;">
```

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

### Left-flanking delimiter run examples

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmark-spec.md

Delimiter runs that are left-flanking but not right-flanking, as defined in the CommonMark spec.

```markdown
***abc
  _abc
**"abc"
 _"abc"
```

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

### BBEdit filter folder path

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/redcarpet-benchmark.md

Folder path for installing Markdown.pl as a BBEdit filter on Mac OS X.

```text
BBEdit Support/Unix Support/Unix Filters/
```

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

### Run spec tests with spec_tests.py

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmark-spec.md

Command to run the conformance tests against a Markdown program. Replace PROGRAM with the path to the program. The script is accompanied by the spec.txt file.

```bash
python test/spec_tests.py --spec spec.txt --program PROGRAM
```

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

### Neither left nor right-flanking delimiter run examples

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmark-spec.md

Delimiter runs that are neither left-flanking nor right-flanking, as defined in the CommonMark spec.

```markdown
abc *** def
a _ b
```

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

### Nested emphasis parsing

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmark-spec.md

An example of nested emphasis markers, questioning the precedence rules for emphasis and strong emphasis parsing.

```markdown
*foo *bar* baz*
```

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

### Access environment variable in Ruby

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/large-4k.md

After dotenv loads, these variables will be available in ENV. This example shows accessing the S3_BUCKET variable.

```ruby
config.fog_directory = ENV['S3_BUCKET']
```

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

### Initialize Redcarpet::Render::HTML renderer

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/redcarpet-readme.md

Initializes an HTML renderer with render options. Available flags include :filter_html, :no_images, :no_links, :no_styles, and :escape_html.

```ruby
Redcarpet::Render::HTML.new(render_options = {})
```

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

### Convert Markdown to Markdown with Inkmark

Source: https://github.com/yaroslav/inkmark/blob/main/README.md

Shows the class-method shortcut and instance form for converting Markdown to Markdown. The instance form uses the same options object for both to_markdown and to_html outputs.

```ruby
# Class-method shortcut
Inkmark.to_markdown("**bold** :rocket:", options: { emoji_shortcodes: true })
# => "**bold** 🚀"

# Instance form—the same options object drives both outputs
g = Inkmark.new(source, options: {
  emoji_shortcodes: true,
  links: { allowed_hosts: ["trusted.com", "*.trusted.com"] }
})
g.to_markdown   # filtered Markdown for pipeline
g.to_html       # rendered HTML for display
```

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

### Intraword emphasis with asterisks vs underscores

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/commonmark-spec.md

Examples showing that intraword emphasis is restricted to asterisks, while underscores inside words do not create emphasis.

```markdown
internal emphasis: foo*bar*baz
no emphasis: foo_bar_baz
```

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

### Supply options to Inkmark

Source: https://github.com/yaroslav/inkmark/blob/main/README.md

Shows four ways to supply options to Inkmark: as a hash at construction, via mutable accessor, via process-wide defaults with Inkmark.configure, or by replacing defaults wholesale with Inkmark.default_options.

```ruby
# As a hash at construction
Inkmark.to_html(md, options: { math: true, tables: false })

# Via mutable accessor
g = Inkmark.new(md)
g.options.math = true
g.options.tables = false
g.to_html

# Process-wide defaults, set once in your application initializer
Inkmark.configure do |options|
  options.math = true
  options.links = { nofollow: true }
end
Inkmark.new(md).to_html  # picks up the defaults

# Or replace them wholesale
Inkmark.default_options = { preset: :recommended, math: true }
```

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

### Redcarpet::Render::HTML_TOC.new

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/redcarpet-readme.md

Initializes a renderer that outputs a table of contents in HTML based on the headers of the Markdown document.

```APIDOC
## Redcarpet::Render::HTML_TOC.new

### Description
Initializes a renderer that outputs a table of contents in HTML based on the headers of the Markdown document.

### Method
Redcarpet::Render::HTML_TOC.new(nesting_level = nil)

### Parameters
#### Options
- **nesting_level** (Integer or Range) - Optional - Allows rendering only headers at certain levels.
```

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

### Run script with dotenv CLI and -i flag

Source: https://github.com/yaroslav/inkmark/blob/main/benchmarks/assets/large-4k.md

The -i or --ignore flag ignores missing files. If .env.local does not exist, this will ignore it and only load .env.

```console
$ dotenv -i -f ".env.local,.env" ./script.rb
```
Tokens:
Raw