New post
Article
· Oct 3, 2016 4m read

Markdown workflow for creating Community posts

#DC Feedback

Here in Community I use the WYSIWYG Text format control to answer questions and other quick text entries.

But for longer posts when I want formatting or if I am building incrementally over several days I use the Plain text (supports markdown) control because it's quicker and easier to post an article I have written offline. In this post I share my workflow and a set of tools to publish long read posts.

What is markdown?

There are references later in this post with more info on how markdown works. But in summary markdown allows you to create formatted writing by typing plain text with tags (similar concept to html). The tags take care of formatting when interpreted, for example by the engine behind Community, Wordpress, and any number of other portals in on the web. Importantly the text is easy to read without formatting and is very quick to type in any plain text editor.

A couple of examples:

  • some bold text, typed as **some bold text**
  • Headings are preceded by # for Heading1, ## for Heading 2, etc

Why markdown?

I am writing this post on my iPhone in a plain text editor while relaxing on my verandah with a coffee, later if I get inspiration I might add a paragraph while in line at the grocery store.... I will finish off at my desk for final draft, add some images then drop in our Slack group for comment before publishing.

The big win is that when I am ready to publish on Community I will just cut+paste into the Plain text (supports markdown) control and be confident that headings, code, bullets, etc will just work. So for me an alternative to using a browser based editor or cutting and pasting a formatted word doc which was just an exercise in frustration and time sink for me.

  • Tip: Keep your markdown simple. There are extensions and additions to the defacto standard for different platforms like Wordpress. Simple markdown will be easier to be read by a broad range of interpreters.

What is the workflow?

I use a Mac and iPhone and the workflow I use has some apple platform dependant tools but they are not required I just find they speed up the process - if you have something great that you use please share in the comments. But this post is really to show how simple the process is.

Steps

  1. Create text in plain text editor.
  2. Upload images to Community.
  3. Check formatting and image links.
  4. Publish.

Tools

I mention specific products here because I use them, however these apps are not endorsed or supported by InterSystems and I am sure you will have your own favourites to substitute.

References for markdown

Here are a few to get you started, but Google will find millions more;

Plain text editor

Anything really, thats the beauty of markdown. But here are a couple I use that also support markdown so have a few aids when writing;

Check formatting in browser

I use;

StackEdit works in a browser, I typically use Chrome. Simply paste your markdown text in the left pane and it automagically appears formatted on the right. StackEdit also works on mobile browsers (iOS anyway).

Upload images to Community

Your article will need to reference the url of images you want to use. I assume they could be anywhere public on the internet but to include with the article I use the WYSIWYG Text format control to upload the images.

Start by using "Create a New Post" and use the WYSIWYG Text format upload button to upload your image files.

  • Tip: Give your images easy/meaningful names because names are kept on upload. Also you can upload multiple files at once.

Check the urls by using the "Source" button. You will see paths like:

p><img alt="" src="/sites/default/files/inline/images/md-1wysiwyg.png"> <img alt="" src="/sites/default/files/inline/images/md-2plaintext.png"> <img alt="" src="/sites/default/files/inline/images/md-3upload.png"> <img alt="" src="/sites/default/files/inline/images/md-4source.png"></p>

To use the image files inline give the full url, for example:

<img alt="" src="https://community.intersystems.com/sites/default/files/inline/images/md-1wysiwyg.png">

That is it. Good luck posting your own articles :)

I post most often on the data platforms blog, mostly on performance and capacity planning here.

Discussion (8)1
Log in or sign up to continue
Murray Oldfield · Oct 25, 2016

Hi, if the question is how to format then I use the three tildes on the line immediately before and after the block of code "~~~" eg. The following code block had the tildes fencing the code on the line immediately before and immediately after the block.

eg.

~~~
//Get PDF stream object previously saved
  Set pdfStreamContainer =
etc
etc
~~~

//Get PDF stream object previously saved
   Set pdfStreamContainer = ##Class(Ens.StreamContainer).%OpenId(context.StreamContainerID)
   Try {
     Set pdfStreamObj = pdfStreamContainer.StreamGet()
   }
   Catch {
      $$$TRACE("Error opening stream object ID = "_context.StreamContainerID)
      Quit
   }
 //Set PDF stream object into new OBX:5 segment
   Set status = target.StoreFieldStreamBase64(pdfStreamObj,"OBX("_count_"):ObservationValue(1)")
   Set ^testglobal("status",$H) = status

I note that the engine for the community website should automatically highlight known languages but you can override .

eg. On first line before "~~~javascript" or "~~~python"

var s = "JavaScript syntax highlighting";
alert(s);

s = "Python syntax highlighting"
print s
1 0