JTFDI Library
just the focus do it    •    
Creator Economy
       •       
Media
       •       
Marketing
       •       
Eating & Drinking
       •       
Commerce
       •       
Customer Relationships
       •       
Reading
       •       
Tech-stack
       •       
Productivity
       •       
Startup
       •       
Technology
       •       
Business
       •       
•    just the focus do it    •     just the focus do it    
Docs
Mag
Writing
Blog
Try it for Free

DecapCMS Markdown Guide: Handling URLs with Parentheses for Text Fragment Highlighting

2023-07-27
, most recent update.

Solving URL Parentheses Conflict in DecapCMS (formerly NetlifyCMS): A Guide for Text Fragment Highlighting

This guide, based on experiences using DecapCMS (formerly NetlifyCMS), provides a solution for handling URLs that include parentheses in Markdown, a common issue when using text fragment highlighting. Ensure your Markdown parser correctly interprets your URLs and your links work as expected.

Introduction

In the course of writing an article in Markdown on Github and building the site with Netlify using DecapCMS (formerly known as NetlifyCMS), a common problem was encountered. This problem is associated with a popular URL syntax for text fragment linking (also known as 'fragmention') which is often used for highlighting specific parts of webpages.

I.e., I wanted to instantly highlight the part of the text in a source, that the concept of “Sixteenth HD1080” is a computationally favorable: https://en.wikipedia.org/wiki/Sixteenth_HD1080#:~:text=HD1080%20is%201920x1080%20pixels%2C%20so,arithmetic%20shift%20right%204%20bits%29

The syntax is as follows: a URL followed by '#:~:text=' and then the specific text that you want to highlight. This can be quite useful when you want to point someone directly to a specific part of a webpage. For example:

https://en.wikipedia.org/wiki/Example_Page#:~:text=Example%20Text(Example)

Here, the text "Example Text(Example)" on the Wikipedia page "Example_Page" would be highlighted when the link is followed.

However, when using this syntax in Markdown documents, a problem arises. Markdown uses parentheses to define the start and end of a URL in link syntax, and the parentheses in the 'fragmention' syntax can interfere with this. This can lead to the Markdown parser interpreting the URL incorrectly, causing an error.

Let’s get into the solution for handling URLs with parentheses (especially text fragment links) in Markdown, ensuring that the Markdown parser correctly interprets the URL and the link works as expected when clicked.

Doc: Handling URLs with Parentheses in Markdown

When you are working with Markdown, there may be cases where you need to include a URL that contains parentheses. This can create issues because Markdown uses parentheses to define the start and end of a URL in link syntax. For example, a basic Markdown link is structured as follows:

[link text](URL)

However, if your URL also contains parentheses, the Markdown parser may get confused and interpret your URL incorrectly.

Consider the following example:

[link text](https://en.wikipedia.org/wiki/Example_Page#:~:text=Example%20Text(Example))

In this case, the Markdown parser may interpret the URL as ending at the first closing parenthesis, causing an error.

Solution

The solution to this problem is to percent-encode the parentheses within the URL. This involves replacing "(" with "%28" and ")" with "%29".

So, for the example above, the correct Markdown syntax would be:

[link text](https://en.wikipedia.org/wiki/Example_Page#:~:text=Example%20Text%28Example%29)

This will ensure that the Markdown parser correctly interprets the URL, and the link will still work correctly when clicked.

This is particularly useful when linking to a specific section of a webpage using the 'fragmention' syntax. For example, if you want to link to a specific section of a Wikipedia page and highlight some text, you might use a URL like the one in the example above. By percent-encoding the parentheses, you can avoid any issues especially with the less enhanced Markdown parser and ensure that your link works as expected.

Read next in DOCU

Optimize Netlify Build Minutes and DecapCMS by Skipping Unnecessary Builds

Optimize Netlify Build Minutes and DecapCMS by Skipping Unnecessary Builds

Read next in DOCU

Displaying Both the Publication and Update Dates on Webpages

Showing both the update and the publish date on your blog / web page seems to be difficult for Search Engines and therefore it seems like only displaying “last updated” is the safer way. If your blog shows more than one date, you are probably confusing Google.

Read next in DOCU

Localization: The "hreflang" Tag Accross Different Domains

John Mueller on how to use the hreflang tags across domains for the localization schemas: It doesn't matter if it's all on one domain or across multiple domains. It should just be one clear place per country and language.

Read next in DOCU

DecapCMS Markdown Guide: Handling URLs with Parentheses for Text Fragment Highlighting

Are broken links in your DecapCMS Markdown articles giving you a headache? never let parentheses break your links again: handle text fragment highlighting in Markdown. No more parentheses-induced troubles in your Github articles built with Netlify!

Read next in DOCU

Leveraging a Small JavaScript for a Quick Multilingual Strategy in Webflow

A button that appears when there is an alternate language defined for your content, making your cotent more relevant to your users experiences. Implementing a Dynamic Language Switcher Button with JavaScript

Read next in DOCU

Interactive URL Copy Feature in Webflow Using Clean JavaScript and Clipboard API

An interactive URL copy feature in Webflow. Using clean JavaScript and the powerful Clipboard API, making it easier for visitors to share your pages. Because who doesn’t appreciate a great user experience?

Read next in DOCU

An Extensive Dynamic Table of Contents Generator for Webflow CMS

Boost your Webflow Blog's readability and SEO with a dynamic Table of Contents (ToC) generator. It automatically creates a stylable, navigable ToC from your headings, and enhances user experience by highlighting the active section during scrolling.

Read next in DOCU

Styling Our Auto-Generated ToC in Webflow

Read next in DOCU

Creating or Changing Slugs in DecapCMS (formerly Netlify CMS)

Changing the URL Slug of your post in DecapCMS in config.yaml using the slug key and name key

Read next in DOCU

Smooth Scrolling to the Next Section with JavaScript and [foo](#next) markdown syntax

When I write [[`foo`](#next)`](#next)` markdown syntax in my content I want the reader to jump to the next section, the next anchor, on my webpage.

Read next in DOCU

Vimeo vs YouTube Embed for your Website

Consider this when you decide between YouTube or Vimeo for Website embeds

Read next in DOCU

Editorial Workflow in Decap CMs (formerly Netlify CMS)

Read next in DOCU

README for ChatGPT and How to Write the Best Prompts

When answering prompts, does it help ChatGPT to be more specific and precise if you give it a set of definitions upfront?

Read next in DOCU

Use Hash-symbol vs Triple-quotes Syntax for Commenting Python Code

Consider this when you choose the syntax for commenting code in Python

Read next in DOCU

Dynamically Generated ToC with Webflow CMS

Generating ToC’s based on h2 and h3 headings of a rich text CMS element with active states in a sticky Table of Contents

Read next in DOCU

Dynamic Social Media Share Buttons for Webflow CMS Blogposts

Add a Twitter button and a share on LinkedIn to your blogposts with sharing content generated from Webflow CMS

Read next in DOCU

Calculate Read Time from Webflow CMS

Calculated a read time from Webflow CMS and add to your blog template.

Read next in DOCU

Add Copy-able Code Blocks to Webflow CMS

Uses highlight.js and custom code to add code blocks where you can copy the code to rich text element of Webflow CMS

Hej. I am on Twitter, too.

Connect with me on Twitter and LinkedIn.