Monday, February 17, 2025
HomeCSSA Versatile Markdown Shortcode for Eleventy

A Versatile Markdown Shortcode for Eleventy


When writing weblog posts in Markdown information I usually discover myself needing so as to add HTML components that aren’t accounted for in Markdown. Some frequent ones are <apart> components, the place I embody content material tangentially associated to the submit itself, or exterior references.

Having to incorporate HTML in Markdown is form of a ache, as a result of when you begin writing HTML, you’ll be able to’t then use Markdown inside it: all the pieces contained in the HTML component should even be HTML. That is fairly annoying for components the place you may wish to embody a number of paragraphs or hyperlinks, for instance. The markdown writing expertise is way extra nice.

Shortcodes

I take advantage of the static website generator Eleventy for this weblog, and I made a decision to utilize an important Eleventy characteristic: shortcodes.

Easy shortcodes

Shortcodes are created with a Javascript operate within the Eleventy config file for a undertaking. There are two forms of shortcodes in Eleventy. The less complicated of the 2 takes various arguments and will be rendered with a single line in a Markdown file. For instance, if we created a shortcode known as “apart”, which renders an <apart> component with a single line of textual content, it might work like this utilizing the Nunjucks templating language, which this weblog makes use of:


{% apart "That is an apart" %}

Different templating languages work in a different way, and the Eleventy docs embody references for utilizing shortcodes in varied templating languages.

To create the straightforward shortcode in our eleventy.config.js file we will use Eleventy’s addShortcode operate. Right here’s the way it appears to be like:

eleventy.addShortcode("apart", (content material) => {
	return `<apart>${content material}</apart>
})

Right here’s how that renders in HTML:

<apart>That is an apart</apart>

This isn’t all that totally different to simply writing the HTML within the first place, so that you may marvel why we’d hassle with a shortcode. It’s way more helpful nevertheless, after we wish to render extra verbose HTML, resembling including courses or nested components. Right here’s one known as “hotlink”, which I take advantage of for rendering a hyperlink that appears like a button:


{% hotlink 'https://css-tricks.com', 'Learn it on CSS Methods' %}

It’s outlined as follows:

eleventyConfig.addShortcode('hotlink', (url, title, goal = '_blank') => {
  return `<a category="hotlink" href="${url}" goal=${goal}>${title}</a>`
})

Paired shortcodes for extra verbose content material

A easy shortcode most likely isn’t going to chop it in all circumstances although. There’s a great likelihood that in our <apart> we would wish to embody hyperlinks, a number of paragraphs, or different components, which the straightforward shortcode doesn’t permit.

For this we will use a paired shortcode. This permits us to make use of a template tag with markdown content material inside it, which suggests we get the superior expertise of writing markdown as a substitute of HTML. Right here’s how we will embody an <apart> with a heading and a number of paragraphs:


{% apart %}
## Heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim advert minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
{% endaside %}

A paired shortcode is outlined utilizing the addPairedShortcode operate within the Eleventy config file:

eleventyConfig.addPairedShortcode('apart', (content material) => {
  return `<apart>${content material}</apart>`
})

This renders the markdown content material as HTML inside our <apart> component.

A extra versatile shortcode

Though this instance works simply nice, it solely offers us an <apart> component. We might enhance the utility of this shortcode in order that it permits us to render any HTML component, and with a customized class too. Let’s regulate the code in eleventy.config.js:

eleventyConfig.addPairedShortcode(
  'component',
  (content material, el = 'apart', className) => {
    return `<${el} class="${className}">${content material}</${el}>`
  }
)

Our operate now takes three arguments: content material is the markdown between our opening and shutting template tags. The second and third arguments outline the component and an optionally available class identify respectively. We’ll embody a default worth of ’apart’ for the component, as we don’t need it to each be nothing.

That is how we’ll embody it in our markdown file:


{% component 'apart', 'pink' %}
## Heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim advert minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
{% endelement %}

This can render an <apart> component with a category of “pink” in our HTML.

RELATED ARTICLES

LEAVE A REPLY

Please enter your comment!
Please enter your name here

Most Popular

Recent Comments