A Case for Markdown

I'm embarrassed. If you googled this title, you'd find many other previous blog posts discussing the utility of Markdown. And in my humble opinion, it can be fully justified depending on the purpose.

With the launch of the early adopter programme for Oracle Application Express (APEX), developers now access to what the APEX Development Team has been working on these past few months. What appears not to be mentioned in the mew features page is a list of new page items.

I think it's pretty obvious which of the two new page items stand out. Just check out these tweets that came out soon after the EA programme was announced.

@martindsouza https://twitter.com/martindsouza/status/1172589077947830272 And thank you @OracleAPEX for adding native markdown support. Been waiting for this for a long time!

@commi235 https://twitter.com/commi235/status/1172599174161981440 Thanks #orclapex for finally giving us a modern, quick and easy way to style comments. 👍

As a developer, I use many platforms like GitHub, GitLab, Jira, StackOverflow etc. daily. I usually write code, notes and other text using a simple editor like Microsoft Visual Code (VS Code), focusing on content and structure than styling, as it should be! And because these platforms all support Markdown, I can easily transfer the text between applications.

I am pretty sure most developers have felt the pain of formatting code when writing technical documentation using Microsoft Word.

Consider this simple block of code:

declare
  l_name varchar2(8) := 'John Doe';
begin
  dbms_output.put_line('Hello ' || l_name);
end;

To write this in MS Word, here's what I might typically do:

1. Copy the code to the clipboard.
2. Paste the text in Word in plaintext.
3. Select the code and change the Font to something that's fixed-width, e.g. Courier.
4. Depending on the language, select each keyword and format to stand out.

How do we do the same with Markdown?

1. Copy the code to the clipboard.
2. Paste the text in GitHub issue description for example.
3. Enclose the code with ```sql and ```.

Done! The result:

declare
  l_name varchar2(8) := 'John Doe';
begin
  dbms_output.put_line('Hello ' || l_name);
end;

That said, please consider who your application's end users are. Markdown today, is still very much an acquired taste. A typical end user would probably be more comfortable editing formatted text usng a WYSIWYG editor and that option is still there in APEX.

The other consideration is the support for Markdown content in the database. Consider the text:

Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.

Suppose the user wanted to bold the word "Aldus" but not "PageMaker". Using the Rich Text Editor page item, the string would be stored as <strong>Aldus</strong> PageMaker, while the Markdown Editor, would store that as **Aldus** PageMaker.

To query the data for the phrase "Aldus PageMaker", you can quite easily find the latter using regular expression (regexp_like). To correctly search the HTML-formatted string, either strip the HTML elements or use Oracle Text. Using the appropriate CONTAINS operator, e.g. ABOUT, it is possible to ignore HTML markup. It might take a few more steps to also ignore Markdown syntax, but not impossible.

The other drawback with Markdown would be functionality like "Remove HTML" when choosing how an Interactive Report is displayed. There's yet to be a "Remove Markdown" option.

There are often many solutions to a puzzle. Having options is great, and using Markdown in APEX out-of-the-box is certainly welcomed! One thing's for sure, moving towards simplicity doesn't mean walking backwards.

This blog post was proudly written in Markdown.