Warning
Hello this is a Warning callout. Does it work?
` tag that wraps a `` tag.
To add this feature, we will need to check for every `` tag in our document and replace the content with a wrapping relatively position `` that adds a button to copy the content.
First, let's add the partial:
```erb
<%# app/views/shared/_code_block_with_button.html.erb %>
<%= code_block_html.html_safe %>
```
This partial receives the `code_block_html` and the `code_content` variables from the renderer:
```ruby
module Marksmith
class Renderer
def initialize(body:)
@body = body
end
def render
doc = Commonmarker.to_html(@body, **options)
post_process(doc)
end
private
def post_process(doc)
nokogiri_doc = Nokogiri::HTML.fragment(doc)
no_follow_if_external(nokogiri_doc)
add_copy_buttons_to_code_blocks(nokogiri_doc)
nokogiri_doc.to_html
end
def no_follow_if_external(doc)
doc.css('a').each do |link|
href = link['href']
next unless href
if external_link?(href)
current_rel = link['rel']
if current_rel
link['rel'] = "#{current_rel} nofollow" unless current_rel.include?('nofollow')
else
link['rel'] = 'nofollow'
end
end
end
doc.to_html
end
def add_copy_buttons_to_code_blocks(doc)
doc.css('pre > code').each do |code_block|
html = ApplicationController.render(
partial: 'shared/code_block_with_button',
locals: {
code_block_html: code_block.parent.to_html,
code_content: code_block.content
}
)
# Replace the original code block with our enhanced version
code_block.parent.replace(Nokogiri::HTML.fragment(html))
end
end
def external_link?(href)
!href.include?("avohq.io")
end
def options
{
options: {
parse: {
smart: true,
},
render: {
escape: false,
unsafe: true,
},
extension: {
alerts: true,
},
},
plugins: {
syntax_highlighter: {
theme: "cobalt2",
path: Rails.root.join("app", "assets", "themes").to_s
},
}
}
end
end
end
```
Now, we add a Stimulus controller to handle the actual copying:
```javascript
import { Controller } from "@hotwired/stimulus"
export default class extends Controller {
static values = {
source: String
}
connect() {
this.isCopying = false
}
copy(event) {
if (this.isCopying) return
this.isCopying = true
const button = event.currentTarget
const originalButtonHTML = button.innerHTML
const textToCopy = this.sourceValue;
navigator.clipboard.writeText(textToCopy)
.then(() => {
button.innerHTML = this.successButtonHTML
setTimeout(() => {
button.innerHTML = originalButtonHTML
this.isCopying = false
}, 1500)
})
.catch(() => {
this.isCopying = false
})
}
get successButtonHTML() {
return `
`
}
}
```
Now, our copy-to-clipboard feature should be working correctly:
{{gumlet video_id="67d21e5fefcecbdea746a1d7" width="1514" height="852" /}}
{{info}}
We're using the browser's native clipboard copy functionality. It might not work on some browsers and have limited functionality. You can try a library like **clipboard.js** in case it's not working for you.
{{/info}}
## Adding custom embed support
Markdown is supposed to be portable: moving Markdown content from one editor to another, should produce the same results.
However, it's very unlikely that every application that needs to parse Markdown has the same requirements, and occasionally, we need to compromise somewhere in the middle.
That's why adding a feature like **custom Markdown embeds** implies that our Markdown is no longer portable, at least not entirely.
Let's learn how to add the feature and explore a solution to make it as portable as we can:
### Self-closing embeds
To keep this section short, we will be exploring how to add self-closing shortcodes, that look like this: `{{shortcode /}}`.
They can also include parameters: `{{shortcode key="value" /}}` that we can use inside the partials.
If you want to see how to add other types of shortcodes like block shortcodes or VitePress styled shortcodes, feel free to check our [shortcodes with Rails](https://avohq.io/blog/marksmith-shortcodes) article where we explore different alternatives for this feature.
The first thing we need to do is create a `ShortcodeParser` class that will be responsible for:
- Receiving HTML and replacing the shortcode instances with HTML from an associated partial.
- Parsing the params into local variables that are passed to the partials.
- Handling possible errors.
Let's start by defining the class with an initializer and a `parse` method which will be responsible for transforming the shortcode string into the actual HTML:
```ruby
module Marksmith
class ShortcodeParser
attr_reader :document
def initialize(document)
@document = document
end
def parse
doc = Nokogiri::HTML.fragment(document).to_html
doc.gsub!(/\{\{(\w+)(.*?)\/\}\}/) do |match|
name = $1
param_string = $2
params = parse_params(param_string)
render_shortcode(name, params)
end
doc
end
## parse_params and render_shortcode implementation pending
end
end
```
Here, the `parse` instance method takes an HTML document and, using a regular expression, extracts data from the shortcode string with it's params and produces the shortcode HTML.
The regular expression states that the string we're matching against must start with two opening curly braces, then it captures one or more words, and it assigns it to the `$1` variable available within the block it receives.
Then, we have another capture group `(.*?)` which lazily matches any character except for a newline happening zero or more times. This part captures the params string, which can be something like `id="12345" name="best-video"` and assigns it to the `$2` variable.
However, we need to define the `parse_params` method to transform that string into a hash that correctly represents the key-value pair relation:
```ruby
def parse_params(param_string)
params = {}
normalized = param_string.to_s.gsub(/[“”]/, '"')
normalized.strip.scan(/(\w+)\s*=\s*"([^"]*)"/).each do |key, value|
params[key.to_sym] = value
end
params
end
```
This method introduces a new regular expression with two capture groups as well.
The first capture group expects one or more word characters (a-zA-Z0-9_) one or more times. This is the key part of the hash.
Then, the Regex declares another capture group surrounded by quotes which is `"([^"]*)"`: it states that we expect the expression to be around quotes and the capture group matches anything that's not a double quote because we know that as soon as a double quote appears we can consider that to be the closing quote.
This is the `value` part of the hash.
Between these two capture groups we have `\s*=\s*` which matches zero or more whitespace characters before and after the equal sign.
Using this Regex, we will match the string `id="4" name="Steven"` to the hash `{ :id => "4", :name => "Steven"}`.
But, to access those parameters from the view, we need to render it using the `render_shorcode` method:
```ruby
def render_shortcode(name, params)
begin
ApplicationController.render(
partial: "shortcodes/#{name}",
locals: { params: params },
layout: false,
)
rescue => error
Rails.logger.error("Error rendering shortcode #{name}: #{error.message}")
end
end
```
This method simply calls `ApplicationController.render` requesting a partial that matches the name extracted from the shortcode, passing the params as local variables and using the `layout: false` to avoid having a layout surrounding the partial.
We're rescuing and logging if any error occurs so we can better troubleshoot our feature in case of failure.
The complete `ShortcodeParser` class definition:
```ruby
module Marksmith
class ShortcodeParser
attr_reader :document
def initialize(document)
@document = document
end
def parse
document.gsub!(/\{\{(\w+)(.*?)\/\}\}/) do |match|
name = $1
param_string = $2
params = parse_params(param_string)
render_shortcode(name, params)
end
Nokogiri::HTML.fragment(document)
end
private
def parse_params(param_string)
params = {}
normalized = param_string.to_s.gsub(/[“”]/, '"')
normalized.strip.scan(/(\w+)\s*=\s*"([^"]*)"/).each do |key, value|
params[key.to_sym] = value
end
params
end
def render_shortcode(name, params)
begin
ApplicationController.render(
partial: "shortcodes/#{name}",
locals: { params: params },
layout: false,
)
rescue => error
Rails.logger.error("Error rendering shortcode #{name}: #{error.message}")
end
end
end
end
```
And, the final `Marksmith::Renderer` version:
```ruby
module Marksmith
class Renderer
def initialize(body:)
@body = body
end
def render
doc = Commonmarker.to_html(@body, **options)
post_process(doc)
end
private
def post_process(doc)
nokogiri_doc = Nokogiri::HTML.fragment(doc)
no_follow_if_external(nokogiri_doc)
add_copy_buttons_to_code_blocks(nokogiri_doc)
ShortcodeParser.new(nokogiri_doc.to_html).parse
end
def no_follow_if_external(doc)
doc.css('a').each do |link|
href = link['href']
next unless href
if external_link?(href)
current_rel = link['rel']
if current_rel
link['rel'] = "#{current_rel} nofollow" unless current_rel.include?('nofollow')
else
link['rel'] = 'nofollow'
end
end
end
doc.to_html
end
def add_copy_buttons_to_code_blocks(doc)
doc.css('pre > code').each do |code_block|
html = ApplicationController.render(
partial: 'shared/code_block_with_button',
locals: {
code_block_html: code_block.parent.to_html,
code_content: code_block.content
}
)
# Replace the original code block with our enhanced version
code_block.parent.replace(Nokogiri::HTML.fragment(html))
end
end
def external_link?(href)
!href.include?("avohq.io")
end
def options
{
options: {
parse: {
smart: true,
},
render: {
escape: false,
unsafe: true,
},
extension: {
alerts: true,
},
},
plugins: {
syntax_highlighter: {
theme: "cobalt2",
path: Rails.root.join("app", "assets", "themes").to_s
},
}
}
end
end
end
```
And now, we have custom embeds:
{{info}}
If you wonder why we're normalizing the params string using `param_string.to_s.gsub(/[“”]/, '"')` it's because Commonmarker changes quotes to curly quotes when the `smart` parsing option is set to `true`.
{{/info}}
### Stripping shortcodes
Portability is an important characteristic of Markdown and adding the custom embeds or shortcode feature.
If we want to generate a shortcode-free version of the post's body, we can add a `render_without_shortcodes` method in the renderer, or even in the `Post` class itself:
```ruby
def render_without_shortcodes
body.gsub(/\{\{(\w+)(.*?)\/\}\}/, "")
end
```
This Regex will replace self-closing shortcodes with an empty character.
If you add other types of shortcodes with more advanced features, you will need to edit the Regex and test against more complex and robust scenarios.
## Summary
The Commonmarker gem is a suitable option if we wish to introduce **GitHub-flavored Markdown** into a Ruby or Rails application.
It wraps the `comrak` Rust library, which implements the Commonmark spec, and provides us with a very flexible alternative to rendering Markdown.
It comes with several extensions that divert from the standard Markdown syntax and, by default, provide a similar experience to how GitHub renders Markdown.
But the fun doesn't stop there, it adds extensions that help us control how Markdown is rendered, and we can add as many or as little as we want.
The same thing goes with plugins like `syntax_highlighter` which we can use to customize how code blocks are styled and also allows us to define our custom themes without requiring for external dependencies.
Furthermore, we can traverse the AST that the gem generates to modify the HTML that's generated. We used that to force the `https` protocol on links and make external links rendered as plain-text.
When the AST traversing gets a little short, we resort to using Nokogiri to parse the generated HTML to produce two outcomes: make external links `nofollow` and add a copy-to-clipboard button for code blocks.
Then, we added a basic shortcode feature using Nokogiri as well to produce custom embeds with parameters, and we added the ability to strip shortcodes from the post's body.
All in all, the Commonmarker gem is a great alternative to produce **GitHub-flavored Markdown** for our Ruby or Rails applications as it's customizable, fast and produces a good experience without much customization.
I hope you enjoyed this article and that you can apply some of these tips to your projects.
Have a good one and happy coding!