docs-staging-cl

The docs-staging-cl repo is for the product content for Bluemix in China. The Bluemix staging-cl doc app builds from this location for all staging environments for China.

Each directory in the docs-staging repo must synch with the overall architecture of the Bluemix doc app.

To suggest changes or updates: fork the project or branch, make your edits, and then create a pull request.

For more details on suggesting changes, and for details on how to merge your content from /docs-staging to the production /docs repo, see the following blueprint: https://releaseblueprints.ibm.com/display/CLOUDOE/Creating+content+in+markdown#Creatingcontentinmarkdown-HowdoImergecontentfromthestagingGithubrepototheproductionGithubrepo?

Authoring Bluemix Content in Markdown

Purpose

Markdown is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML.

The Markdown used for Bluemix is based on GitHub-flavored Markdown. The following resources can be helpful in coding the markup for you content:

Bluemix has designed a parser that transforms Markdown into HTML5. Because the syntax available in standard Markdown is limited, the Bluemix team has developed Extensions to provide an enhanced authoring experience. These extensions provide key features available in DITA today, adding, for example, the ability to use metadata attributes and content references in Markdown. This document provides instructions for using these extensions.

Before you begin

###Markdown Editors There are many free Markdown editors available, however, not all editors will honor the syntax used by Bluemix extensions. Notepad ++ is free, compatible, and also supports YAML, which is used to define content reference keywords.

###Markdown Parser and setting up your environment The mdProcessor.js was created by Grant Gayed and can be cloned from the project ggayed | markdownProcessor at hub.jazz.net. The parser is as-is.

A version of the parser is installed on the Blueix doc build system and is used to output all Markdown sourced content to HTML 5.

To try out the parser or run it locally:

install node ( http://nodejs.org/ )
install any git client if you don't already have one
at a prompt:

> git clone https://hub.jazz.net/git/ggayed/markdownProcessor
> cd markdownProcessor
> npm install
> node mdProcessor.js --sourceDir=<fullPathToDirectoryContainingMarkdownFiles> --destDir=<fullPathToDestinationDirectory>

Example command:

node mdProcessor.js --sourceDir=C:\dev\bluemix_service --destDir=C:\dev\markdown_target\service �--headerFile=header.txt --footerFile=footer.txt -enableAttributes -overwrite --conrefFile=<fullpath>

Parameters:

--sourceDir: location of where the *.md files are located
--destDir: location of where the HTML files should be output
--headerFile: header information added to each of the HTML output files
--footerFile: footer information added to each of the HTML output file
-enableAttributes: disables the Attributes extension
-disableAttributes: disables the attribute extension
-overwrite: overwrites any previously output (HTML 5) version of the file in the destination directory
-conrefFile: location of where the master content reference file is located
-disableToc: disables the Table of Contents extension

For additional guidance in setting up your local environment for the mdProcess.js, see Setting up a local version of the Markdown parser for testing in the Bluemix Release Blueprints.

#Mappings between DITA, MarkDown, and HTML 5

Element	XDITA	HDITA	MarkDown (Git flavored)	HTML 5
container	`<topic>`	`<article>`	`No equivalent`	`<article>`
title	`<title>`	`<h1>...<h6>`	`# ## ### ####`	`<h1>...<h6>`
short description	`<shortdesc>`	`<p>`	`No equivalent, first thing under the title must be a paragraph of text`	`<p>`
body	`<body>`	`No equivalent (ignored)`	`No equivalent`	`--`
section	`<section>`	`<section>`	`No equivalent`	`<section>`
unordered list	`<ul>`	`<ul>`	`` or `-` Note*: Nested lists need to be indented four spaces or a tab, and mixing ordered and unordered lists does not work (use html)	`<ul><li></li></ul>`
ordered list	`<ol>`	`<ol>`	`1.` `2.` `3.` Note: Nested lists need to be indented four spaces or a tab, and mixing ordered and unordered lists does not work (use html)	`<ol><li></li></ol>`
list item	`<li>`	`<li>`	`use the appropriate list type; nested lists are supported:` `1. Item 1` `1. A corollary to the above item.` `2. Yet another point to consider.` `2. Item 2` `* A corollary that does not need to be ordered.` `* This is indented four spaces, because it's two spaces further than the item above.` `* You might want to consider making a new list.` `3. Item 3`	`<ol>` `<li>` `<ol>` `<li>` `<li>` `</ol>` `<li>` `<ul>` `<li>` `<li>` `</ul>` `<li>` `</ol>`
definition list	`<dl>`	`<dl>`	`No equivalent`	`<dl>`
definition list entry	`<dlentry>`	`No equivalent (ignored)`	`No equivalent`	`--`
term	`<dt>`	`<dt>`	`no equivalent`	`<dt>`
definition	`<dd>`	`<dd>`	`No equivalent`	`<dd>`
paragraph	`<p>`	`<p>`	No equivalent, Paragraphs in Markdown are just one or more lines of consecutive text followed by one or more blank lines.	`<p>`
code	`<pre>`	`<pre>`	```code```
syntax highlighting			``` `ruby` `require 'redcarpet'<br>markdown = Redcarpet.new("Hello World!")` `puts markdown.to_html` ```	need to look into this one...or if the Bluemix usage of the Highlighter for Dojo and use the css styles from the highlighter.js removes the need to set a codeLanguage [Languages supported] (https://github.com/github/linguist/blob/master/lib/linguist/languages.yml)
table			`Header 1` `	Header 2`<br> -------------`
italics	`<i>`		`italic`	`<em>`
bold	`<b>`		`bold`	`<strong>`
strikethrough			`~~strikethrough~~`	`<del>`
monospace			`monospace`	`<code>`
links			You can create an inline link by wrapping link text in brackets `( [ ] )`, and then wrapping the link in parenthesis `( ( ) )`. GFM will autolink standard URLs, so if you want to link to a URL (instead of setting link text), you can simply enter the URL and it will be turned into a link to that URL. Note: to create an external link that opens in a new window, place the following attribute defintion at the top of your file: `{:new_window: target="_blank"}` and then use the following attribute after your link `[link](url){: new_window}`	`<a href="https://www.link.com">Link Text</a>`
blockquote			`In the words of Abraham Lincoln:` `> Pardon my french`	`<blockquote>` `<p>text</p>` `</blockquote>`
image			`![alt text for my graphic](images/image_name.jpg)`	`<p><img src="images/1.png" alt="alt text"></p>`
video			`<video width="400px" controls>` `<source src="mov_bbb.mp4" type="video/mp4">` `<source src="mov_bbb.ogg" type="video/ogg">` `Your browser does not support HTML5 video.` `</video>`	`<video width="400px" controls>` `<source src="video/BlueMix Mobile Data iOS Demo v2.mp4" type="video/mp4">` `Your browser does not support HTML5 video.` `</video>`
keywords	`<prolog>` `<metadata>` `<keywords>` `<indexterm>` `keyword` `</indexterm>` `</keywords>` `</metadata>` `</prolog>`		`currently not available`	`<meta name="keywords" content="keyword">`
metadata			`{{site.data.product.bluemix}}`	`data-hd-metadata`
comments			`<!-– comment -->`	`<!-– comment -->`
mdash			`no equivalent`	`—`

#Mappings for how to code in DITA vs Markdown

Dita Element	HTML 5 output from Dita	How to code in Markdown	HTML 5 output from Markdown
codeblock	`<pre class="codeblock">`	```code``` `{: codeblock}` Note: This requires the following attribute definition available in the attribute definition template: `{:codeblock: .codeblock}`	`<pre class="codeblock">` `<code>code</code>` `</pre>`
pre	`<pre class="pre">`	```code``` `{: pre}` Note: This requires the following attribute definition available in the attribute definition template: `{:pre: .pre}`	`<pre>` `<code>code</code>` `</pre>`
systemoutput	`<samp class="ph systemoutput">`	`systemoutput`	`<code>systemoutput</code>`
codeph	`<samp class="ph codeph">`	`codeph`	`<code>codeph</code>`
userinput	`<kbd class="ph userinput">`	`userinput`	`<code>userinput</code>`
screen	`<pre class="pre screen"><code>screen</code></pre>`	```code``` `{: screen}` Note: This requires the following attribute definition available in the attribute definition template: `{:screen: .screen}`	`<pre class="screen">` `<code>code</code>` `</pre>`
cmdname	`<span class="keyword cmdname">cmdname</span>`	`cmdname`	`<strong>cmdname</strong>`
varname	`<span class="keyword varname">varname</span>`	`varname`	`<em>varname</em>`
option	`<span class="keyword option">option</span>`	`option`	`<code>option</code>`
parml	`<dl class="parml"><dt class="pt dlterm">pt</dt>` `<dd class="pd">pd</dd>` `</dl>`	`title` definition	`<p><strong>parameter title</strong>` `Definition of the parameter</p>`
uicontrol	`<span class="ph uicontrol">uicontrol</span>`	`uicontrol`	`<strong>uicontrol</strong>`
menucascade	`<span class="ph uicontrol">uicontrol > uicontrol</span>`	`uicontrol > uicontrol`	`<strong>uicontrol > uicontrol</strong>`
apiname	`<span class="keyword apiname">apiname</span>`	`apiname`	`<code>apiname</code>`
filepath	`<span class="ph filepath">filepath</span>`	`filepath`	`<code>filepath</code>`
shortdesc	`<shortdesc> <p class="shortdesc">`	This is a shortdesc paragraph `{: shortdesc}` Note: This requires the following attribute definition available in the attribute definition template: `{:shortdesc: .shortdesc}`	`<p class="shortdesc">`
term	`<span class="ph term">term</span>`	`term`	`<em>term</em>`

#Bluemix special mappings for how to code in DITA vs Markdown

Dita Element	HTML 5 output from Dita	How to code in Markdown	HTML 5 output from Markdown
Bluemix Messages msg msgBody msgID msgPrefix msgNumber msgSuffix msgExplanation msgUserResponse	`<section class="section section msgExplanation">Explanation:` `<section class="section section msgUserResponse">Action:`	`msgph` `>`msgblock of text `>`this is more text `>`and some more text `## BXNUI0001E` `The attempt to determine whether a session exists failed.` For instructions to fix this problem, see this `[troubleshooting topic](https://www.chinabluemix.net/docs/troubleshoot/index-gentopic3.html#tr_err)`.	`<code>msgph</code>` `<h2 id="bxnui0001e">BXNUI0001E</h2>` `<p><b>The attempt to determine whether a session exists failed.</b></p>` `<p>For instructions to fix this problem, see this <a href="https://www.chinabluemix.net/docs/troubleshoot/index-gentopic3.html#tr_err">troubleshooting topic</a>.</p>`
DITA troubleshooting specialization tsSymptom tsCauses tsResolve	`<section class="section tsSymptoms">What's happening` `<section class="section tsCauses">Why it's happening` `<section class="section tsResolve">How to fix it`	This is the "What's happening" paragraph `{: tsSymptoms}` This is the "Why it's happening" paragraph `{: tsCauses}` This is the "How to fix it" paragraph `{: tsResolve}` Note: This requires the following attribute definitions available in the attribute definition template: `{:tsSymptoms: .tsSymptoms}` `{:tsCauses: .tsCauses}` `{:tsResolve: .tsResolve}`	`<p class="tsSymptoms">This is the "What's happening" paragraph</p>` `<p class="tsCauses">This is the "Why it's happening" paragraph</p>` `<p class="tsResolve">This is the "How to fix it" paragraph</p>`
Bluemix Runtime Classes More Information	`<ul class="runtimeIconList">` `<p class="runtimeIcon">` `<p class="runtimeTitle">` `<p class="runtimeLink">`	`list item 1` `list item 2` `{: runtimeIconList}` Paragraph of text `{: runtimeIcon}` Paragraph of text `{: runtimeTitle}` Paragraph of text `{: runtimeLink}` Note: This requires the following attribute definitions available in the attribute definition template: `{:runtimeIconList: .runtimeIconList}` `{:runtimeIcon: .runtimeIcon}` `{:runtimeTitle: .runtimeTitle}` `{:runtimeLink: .runtimeLink}`	`<ul class="runtimeIconList">` `<li>list item 1</li>` `<li>list item 2</li></ul>` `<p class="runtimeIcon">Paragraph of text</p>` `<p class="runtimeTitle">Paragraph of text</p>` `<p class="runtimeLink">Paragraph of text</p>`
Bluemix Related Links `id="rellinks"` id of wrapper tag of all related links section `id='general'` id of RELATED LINKS `id='api'` id of API REFERENCE `id='samples'` id of TUTORIALS AND SAMPLES `id='buildpacks'` id of COMPATIBLE RUNTIMES `id='sdk'` id of SDK REFERENCE	`<article class="topic reference nested1" aria-labelledby="d68e338" lang="en-us" id="rellinks"><h2 class="topictitle2" id="d68e338">Related links</h2>` `<aside>` `<div class="linklist" id="general"><h3 class="linklistlabel">Related Links</h3>` `<ul><li><img src="./sout.gif" alt=""><a href="http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/personality-insights" rel="external" title="(Opens in a new tab or window)">Detailed Documentation</a></li>` `<li><img src="./sout.gif" alt=""><a href="http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/personality-insights.html" rel="external" title="(Opens in a new tab or window)"><span class="keyword">Personality Insights</span> home page</a></li>` `<li><img src="./sout.gif" alt=""><a href="https://developer.ibm.com/watson/" rel="external" title="(Opens in a new tab or window)">Watson developer cloud community</a></li>` `</ul></div>` `<div class="linklist" id="samples"><h3 class="linklistlabel">Tutorials and Samples</h3>` `<ul><li><img src="./sout.gif" alt=""><a href="https://watson-pi-demo.mybluemix.net/" rel="external" title="(Opens in a new tab or window)">Live Demo</a></li>` `<li><img src="./sout.gif" alt=""><a href="http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/personality-insights/index.html#sampleApp" rel="external" title="(Opens in a new tab or window)">Sample Application source and instructions</a></li>` `<li><img src="./sout.gif" alt=""><a href="https://github.com/watson-developer-cloud/nodejs-wrapper" rel="external" title="(Opens in a new tab or window)">Client-side library for Watson in Node.js</a></li>` `<li><img src="./sout.gif" alt=""><a href="https://github.com/watson-developer-cloud/java-wrapper" rel="external" title="(Opens in a new tab or window)">Client-side library for Watson in Java</a></li>` `</ul></div>` `<div class="linklist" id="api"><h3 class="linklistlabel">API Reference</h3>` `<ul><li><img src="./sout.gif" alt=""><a href="http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/apis/#!/personality-insights" rel="external" title="(Opens in a new tab or window)">REST API</a></li>` `</ul></div>` `</aside></article>`	`# rellinks` `## samples` `* [link text](http://URL)` `* [link text](http://URL)` `## sdk` `* [link text](http://URL)` `* [link text](http://URL)` `## api` `* [link text](http://URL)` `* [link text](http://URL)` `## buildpacks` `* [link text](http://URL)` `* [link text](http://URL)` `## general` `* [link text](http://URL)` `* [link text](http://URL)`	`<h1 id="rellinks">rellinks</h1>` `<h2 id="samples">samples</h2>` `<ul>` `<li>` `<li>` `</ul>` `<h2 id="sdk">sdk</h2>` `<ul>` `<li>` `<li>` `</ul>` `<h2 id="api">api</h2>` `<ul>` `<li>` `<li>` `</ul>` `<h2 id="buildpacks">buildpacks</h2>` `<ul>` `<li>` `<li>` `</ul>` `<h2 id="general">general</h2>` `<ul>` `<li><a href="http://www.softlayer.com/security">Soflayer Security Compliance</a></li>` `<li><a href="../services/SingleSignOn/index.html">Getting started with Single Sign On</a></li>` `</ul>`
Bluemix Context Switching `data-hd-programlang="languagecode"` `//programming language and OS` `csAllProgramlangs: [` `{key:"generic", label:"Generic"},` `{key:"java", label:"Java"},` `{key:"ruby", label:"Ruby"},` `{key:"c#", label:"C#"},` `{key:"objectc", label:"Objective C"},` `{key:"python", label:"Python"},` `{key:"javascript", label:"JavaScript"},` `{key:"php", label:"PHP"},` `{key:"swift", label:"Swift"}` `],` `csAllOperatingsystems: [` `{key:"generic", label:"Generic"},` `{key:"ios", label:"iOS"},` `{key:"android", label:"Android"}` `],`	`<pre class="codeblock"` `data-hd-programlang="javascript"><code><script>` `var setup = {` `applicationId:'<<var class="keyword varname">applicationId</var>>',` `applicationRoute:'<<var class="keyword varname">applicationRoute</var>>',` `applicationSecret:'<<var class="keyword varname">applicationSecret</var>>'` `}` `IBMBluemix.initialize(setup);` `</script></code>` `</pre>` `<pre class="codeblock" data-hd-operatingsystem="ios"><code>[IBMBluemix initializeWithApplicationId: <var class="keyword varname">applicationId</var> andApplicationSecret: <var class="keyword varname">applicationSecret</var> andApplicationRoute: <var class="keyword varname">applicationRoute</var>]</code></pre>`	`<!-- Attribute definitions -->` `{:javascript: #javascript .ph data-hd-programlang='javascript'}` `{:java: #java .ph data-hd-programlang='java'}` `{:ruby: #ruby .ph data-hd-programlang='ruby'}` `{:shortdescription: .shortdesc}` `<!-- Applying the above definitions to inline code tags and paragraph tags -->` `You can use the` Node.js`{: javascript}` Java`{: java}` Ruby`{: ruby} sample application to try the RabbitMQ service.` `{: shortdescription}` Note: This requires attribute definitions available in the attribute definition template.	`<p class="shortdesc">You can use the <code id="javascript" class="ph" data-hd-programlang="javascript">Node.js</code> <code id="java" class="ph" data-hd-programlang="java">Java</code> <code id="ruby" class="ph" data-hd-programlang="ruby">Ruby</code> sample application to try the RabbitMQ service.</p>`
Bluemix App Data `user's app related metadata: "app_name", "app_url", "service_name", "service_instance_name", "plan", "host"`	?	? Note: This requires the following attribute definition available in the attribute definition template: `{:?: .?}`	?

Bluemix Extensions

The following Bluemix extensions to Markdown are supported:

Output all MarkDown markup to standard, valid HTML5 tags
Attributes
Addition of headers and footers to the HTML output
Anchor IDs Generated for all Headers
Content References
TOC file
Output is fully accessible
Additional functionality

Attributes

The Bluemix Markdown parser allows you to define additional attributes in Markdown. After your attributes are defined, you can apply these values to any markdown element, like headers, paragraphs, and codeblocks.

You can use the Bluemix attributes extension to map the following attributes to an element:

ID
Class
Custom value

Note: Attributes, when defined and applied within a Markdown file, are output by the Bluemix Markdown parser by default. No additional parameters or flags need to be passed to the parser when the command is run.

####How attributes are defined in Markdown Attributes are defined at the top of your Markdown file. Each Attribute definition must be enclosed in curly brackets { }, and must contain a unique name. While you can provide attribute definition values for ID, Class, and Custom, none of these values are required, and you can define any combination of these different attribute values. The Bluemix Attribute Definitions implimentation is based on the Kramdown / Maraku Attribute Definiton extension: (http://kramdown.gettalong.org/syntax.html#attribute-list-definitions).

For Example:

<!-- Attribute definition --> 
{:Name: #ID .Class Custom='custom attribute'}
<!-- Sample Attribute definition --> 
{:java: #java .ph data-hd-programlang='java'}

:Name: is the name of the attribute. This value does not get passed through to the output, it is an internal Markdown name that is used to map the attribute definition at the top of the page to one or more uses throughout the Markdown file. This value must be surrounded by colons (: :).
#ID sets a value associated with the id attribute. This value is optional. If I define an ID of #java in my attribute, and I set this attribute on a Header, the HTML5 output will produce <h1 id="java"></h1>. This value must begin with a pound sign (#).
.Class sets a value associated with the Class attribute. This value is optional. If I define a Class of .ph in my attribute, and I set this attribute on a Header, the HTML5 output will produce <h1 Class="ph"></h1>. This value must begin with a pound period (.).
.Custom sets a custom attribute value. This value is optional. If I define a Custom value of data-hd-programlang='java' in my attribute, and I set this attribute on a Header, the HTML5 output will produce <h1 data-hd-programlang='java'></h1>.

####How attributes are applied in Markdown After you define your attribute at the top of your Markdown file, you can apply the attribute by adding a call to the name of your attribute to the end of the Markdown tag you want to bind your attribute to. The implimentation of Bluemix attribute usage is based on the Kramdown / Maraku Block/Span Inline Attribute Lists: http://kramdown.gettalong.org/syntax.html#inline-attribute-lists

To apply a defined attribute, call the name of the attribute surrounded by curly brackets, and pre-pended by a colon and a space: {: Name}

For example: I define a short description attribute at the top of my file and then apply it to a paragraph:

 {:shortdescription: .shortdesc}
 
 This is a short description paragraph
 {: shortdescription}

The Markdown parser will output HTML5 that looks like this:

<p class="shortdesc">This is a short description paragraph</p>

####Attributes in DITA vs Markdown
In DITA, attributes are used to add metadata to elements. For example, you might add a product, props, or otherprops attribute on a phrase or paragraph element in order to associate a value with that phrase or paragraph. These values allow for filtering either during build or runtime. DITA transforms to HTML5 also apply Class attributes to HTML5 elements, and these values are used by the .CSS stylesheets at runtime to control the display.

Example of DITA attributes (from using_rabbitmq_service.dita): Here we can see that the author has added a props attribute to 3 phrase tags, and added a unique programming language value to each prop.

<shortdesc>You can use the <ph props="programlang(javascript)">Node.js</ph> <ph
props="programlang(java)">Java</ph> <ph props="programlang(ruby)">Ruby</ph> sample
application to try the <keyword
conref="cloudoeconrefs.dita#cloudoeconrefs/rabbitmq">RabbitMQ</keyword> service.</shortdesc>

HTML5 output transformed with IDWB:

<p class="shortdesc">You can use the <span class="ph" data-hd-programlang="javascript">Node.js</span> <span class="ph" data-hd-programlang="java">Java</span> <span class="ph" data-hd-programlang="ruby">Ruby</span> sample
application to try the <span class="keyword">RabbitMQ</span> service.</p>

In Markdown, the Bluemix parser will apply whatever attributes you define to any of the supported Markdown elements, (For example, Header, Paragraph, Codeblock, Blockquote, Inline Code, Bold, Italics, Table, etc.). While Markdown does not support the Phrase tag, you can still bind attributes to single words or phrases by using inline tags like Code, Bold, or Italics.

The Bluemix doc framework provides runtime context switching functionality that looks for attributes on HTML5 elements and hides or displays this content depending on selections made by the user. Support for context switching in Markdown source is just one of the ways writers can use the Bluemix attribute extension. In addition, writers can add anchor IDs to multiple elements, overwrite anchor IDs on headers, add Class attributes like shortdesc to a paragraph to define the output as a shortdescription, as well as define their own custom attribute values on supported elements.

Example of Markdown attributes definitions and applications (from using_rabbitmq_service.md): The DITA source example above from using_rabbitmq_service.dita is an example of a file that has been designed for context switching. When the HTML5 output is displayed at runtime in the Bluemix doc framework, if the user selects to view only Ruby, elements containing the attribute data-hd-programlang="ruby" will be displayed, and elements with the attribute of data-hd-programlang that contain anything other than "ruby" will be hidden. Below I have created a near-equivalent version of the DITA topic in Markdown, complete with attributes that support context switching.

<!-- Attribute definitions --> 
{:javascript: #javascript .ph data-hd-programlang='javascript'}
{:java: #java .ph data-hd-programlang='java'}
{:ruby: #ruby .ph data-hd-programlang='ruby'}
{:shortdescription: .shortdesc}

<!-- Applying the above definitions to inline code tags and paragraph tags --> 
You can use the `Node.js`{: javascript} `Java`{: java} `Ruby`{: ruby} sample application to try the RabbitMQ service.
{: shortdescription}

Output of HTML5 from Markdown parser:

<p class="shortdesc">You can use the <code id="javascript" class="ph" data-hd-programlang="javascript">Node.js</code> <code id="java" class="ph" data-hd-programlang="java">Java</code> <code id="ruby" class="ph" data-hd-programlang="ruby">Ruby</code> sample application to try the RabbitMQ service.</p>

Headers and footers

Bluemix needed to add copyright and metadata to the header of the HTML 5 output. We have standard header and footer files that are called during transformation.

Opening and closing HTML tagging is added with a header.txt and footer.txt file that is called by the parser: --headerFile=header.txt --footerFile=footer.txt

<!DOCTYPE html><html lang="en-us">
<head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<meta name="copyright" content="© Copyright IBM Corporation 2016">
<meta name="DC.Rights.Owner" content="© Copyright IBM Corporation 2016">
<meta name="github.edit" content="yes">

<!-- Licensed Materials - Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->

</head>

####Anchor IDs Generated for all Headers When the Bluemix Markdown parser transforms Markdown to HTML5, it automatically binds an anchor ID to all Header elements. Any time the parser transforms a Markdown file that contains a header, the HTML5 output of that header tag will produce an id attribute, with a value that is unique. Unique anchor IDs on headers provide writers with the ability to link directly to a sub-topic that begins with a Header.

For example, here is a level 4 Header in Markdown:

####Content references in DITA vs Markdown

When the above Markdown is transformed into HTML5, the parser produces a unique id with a value that is equal to the name of the header:

<h4 id="content-references-in-dita-vs-markdown">Content references in DITA vs Markdown</h4>

Note: Header anchor IDs are output by the Bluemix Markdown parser by default. No additional parameters or flags need to be passed to the parser when the command is run.

####Changing an anchor ID on a Header

The Anchor ID is bound to a header by default, and it always uses the text of the header as its name, so you can always just link to that. However, any time you want to override the anchor tag of a header, you can use an attribute. See the Attribute section above for more details on using attributes.

Example of default anchor bound to a header:

Mardown source: ##Visualizing your data sample

HTML5 output: <h2 id="visualizing-your-data-sample">Visualizing your data sample</h2>

Example of remapping using a simple attribute (we use the ID attribute, which is mapped with the # character):

Markdown source:

##Visualizing your data sample
  {: #my-renamed-anchor}

HTML5 output: <h2 id="my-renamed-anchor">Visualizing your data sample</h2>

Note: You could produce the same results by making an attribute definition at the top of your file, and then you would call the name of the attribute definition, like so:

{:myanchor: #my-renamed-anchor}

##Visualizing your data sample
  {: myanchor}

####Linking to an anchor ID for a header

You can link directly to a header within a file using the header anchor ID. You can link to sub-headings; it does not need to be the top-level header. Use the automatically generated header value based on the text that is defined in the header (see Anchor IDs Generated for all Headers), or add your own anchor ID to use for linking (see Changing an anchor ID on a header). The following example for linking uses user-defined ID anchors for each header, and the goal is to provide a link to content that is further down in the same file.

Headings and user-defined header anchors for my file:

#Bluemix
{: #bluemix}

My short description links to the [Applications heading](filename.html#header_id).

##Services
{: #services}

##Applications
{: #applications}

I want to create a link within my short description that links to the second sub-heading, Applications. 
To do this, I would use the following format: [Link text for header](filename.html#header_id). 
For this example, I would use [Applications](readme.html#applications).

Content References

The Bluemix conref extension is invoked by the parser by using the conrefFile flag: --conrefFile=cloudoeconrefs.yml.

node mdProcessor.js --sourceDir=C:\pilot\sourceMD --destDir=C:\pilot\outputMD --headerFile=header.txt --footerFile=footer.txt --conrefFile=cloudoeconrefs.yml -overwrite

Conrefs are stored in cloudoeconrefs.yml. cloudoeconrefs.yml is a YAML file, and can be placed in any directory as specified in the --conrefFile parameter. Typically, cloudoeconrefs.yml can be found in C:\Users\IBM_ADMIN\Documents\GitHub\markdownProcessor.

Conref definitions in YAML are structured in nested keys, each key that contains a value or a subkey must be followed by a colon (:), and the next line must be indented 2 space. For example:

 key:
  subkey1:
    conref value 1
  subkey2:
    conref value 2

Conrefs in Markdown are called by using the following syntax: {{site.data.key1.key2...keyN}} Note: While you can Nest keys as deep as you like in YAML, and call deeper sets of keys from markdown, Bluemix conrefs use only 2 keys. For example: {{site.data.keyword.bluemix_notm}}

####Content references in DITA vs Markdown In DITA, a content reference, or conref, is a way of reusing or pulling content from one file into another file; effectively making a copy during the transform.

Example of conrefs sourced in DITA (stored in cloudoeconrefs.dita):

	<!--//Do not translate - Begin-->
	<p><keyword id="bluemix"><tm tmtype="reg" trademark="IBM">IBM</tm> <tm tmtype="tm" trademark="Bluemix">Bluemix</tm></keyword></p>
	<p><keyword id="bluemix_short"><tm tmtype="tm" trademark="Bluemix">Bluemix</tm></keyword></p>

Example of a conref being called from a DITA file (called from rails.dita):

	<p>This Ruby starter application is a boilerplate for <keyword conref="cloudoeconrefs.dita#cloudoeconrefs/bluemix_short">BlueMix</keyword> Ruby web application development.</p>

In the Bluemix Markdown extension, we create a similar mechanism for reusing or pulling content from one file into another file. The extension uses YAML as a source for the conrefs.

Example of conrefs sourced in YAML (stored in cloudoeconrefs.yml):

	#Bluemix conref equivalent file to cloudoeconrefs.dita

	#//Do not translate - Begin
	keyword:
	  bluemix:
	    IBM&reg; Bluemix&trade;
	  bluemix_short:
	    Bluemix&trade;
	  IBM:
	    IBM&reg;
	  cloudoe:
	    Cloud Operating Environment
	  domainname:
	    DomainName
	  Appdomainname:
	    AppDomainName
	#Service names
	  activedeployshort:
	    Active Deploy
	  amashort:
	    Advanced Mobile Access
	  activedeployshort:
	    Active Deploy
	  amashort:
	    Advanced Mobile Access

Example of conrefs called from Markdown (called from test.md):

	This is a new paragraph all about using conrefs. This word here: {{site.data.keyword.bluemix_notm}} is actually a conref! I can use {{site.data.keyword.bluemix_notm}} multiple times in a paragraph. 
	* I can use the full product name: {{site.data.keyword.bluemix_notm}}
	* Or I can use the shortened product name: {{site.data.keyword.bluemix_short}}
	* {{site.data.keyword.activedeployshort}} is a Service. 
	* So is {{site.data.keyword.amashort}}

Results:

	 This is a new paragraph all about using conrefs. This word here: Bluemix is actually a conref! I can use Bluemix multiple times in a paragraph.

		I can use the full product name: Bluemix
		Or I can use the shortened product name: Bluemix™
		Active Deploy is a Service.
		So is Advanced Mobile Access

####How to add a new content reference

You have a new product called Amazing Thing, and you plan to refer to it in multiple locations across multiple files.
Navigate to the /MarkdownProcessor directory that contains mdProcessor.js and open cloudoeconrefs.yml with an editor that supports YAML (notepad++, for example). Note: The parser that transforms Markdown to HTML5 restricts the use of conrefs to one conref source file. Bluemix uses cloudoeconrefs.yml stored at this location: https://github.ibm.com/Bluemix/docs/blob/staging/cloudoeconrefs.yml
YAML allows you to nest multiple value, (where each value contains the text you want to store as your content reference), under each key that you create. For example:

#Comments in YAML use the pound symbol
key
 value1
   conref value 1
 value2
   conref value 2

Note: Each key and value combination must be unique.

Add your new product, Amazing Thing to cloudoeconrefs.yml:

keyword
  amazing_thing
   Amazing Thing

Now you can call this conref from anywhere in your Markdown topics. Conrefs are called using the following syntax: {{site.data.key.value}}. To call your new conref, you would use: {{site.data.keyword.amazing_thing}}.
Run mdProcessor on your file, ensuring that you use the --conrefFile flag:

node mdProcessor.js --sourceDir=C:\pilot\sourceMD --destDir=C:\pilot\outputMD --headerFile=header.txt --footerFile=footer.txt --conrefFile=conref.yml -overwrite

The HTML5 output will contain the string Amazing Thing in each location that the source Markdown contains {{site.data.keyword.amazing_thing}}.

####Trademark and Registered Trademark recommendations When DITA is transformed to HTML5 using IDWB xHTML transforms, symbols stored in a DITA conref source file that has trademarks or registered trademarks appended to them are programmatically passed through to the output. However, only the first instance of each word with a trademark or registered trademark is added to the output, and subsequent uses of that same value are ignored. The Markdown to HTML5 transform does not have the ability to ignore multiple instances of a trademarked word. We recommend manually controlling the output of your trademarked words by creating two conrefs of a trademarked word, one with the trademark, and one without. This enables you to call the trademarked conref the first time the word is used on a page, and enables you to call the conref without a trademark on subsequent uses of the word.

Note: To add a trademark to a word in your conref file, simply add the HTML syntax for registered trademark (®), or trademark (™) to each word. For example:

 keyword:
   bluemix:
     IBM&reg; Bluemix&trade;

Note: Along with passing through trademarks in HTML, all of the following special characters are also supported: (http://www.w3.org/MarkUp/HTMLPlus/htmlplus_13.html)

TOC File

In addition to the standard HTML5 output that the Bluemix Markdown parser produces from each Markdown file, the parser also produces a Table of Contents file in different formats. Each TOC file produced from a markdown topic contains a nested set of structured headers or topicrefs that match the structure of headers in the original markdown source. Each TOC header or topicref also contains a link to a corresponding header anchor ID in the HTML5 output file that was generated from the Markdown source.

By default, for each Markdown file processed by the Bluemix parser, the following files are output:

Source: index.md

Output:

index.HTML: standard HTML5 output
indexTOC.md: Markdown file with nested Headers matching each Header in index.md. Each Header contains a link to a corresponding header anchor ID in index.HTML
indexTOC.HTML: HTML file with nested Headers matching each Header in index.md. Each Header contains a link to a corresponding header anchor ID in index.HTML
index.ditamap: DITA map file with nested topicrefs matching each Header in index.md. Each topicref contains a link to a corresponding header anchor ID in index.HTML

Note: Each TOC format is produced and structured following the conventions of that format. Because DITA map files enforce a strict rule where headers must be incremented by only a single level, any Headers in your markdown that skip a level, (for example, H1 to H3, skipping H2), will not produce a valid *.ditamap TOC. Header values can decrease by skipping a level, (for example, H3 to H1, skipping H2), but they cannot increase.

Note: TOC files are output by the Bluemix Markdown parser by default. No additional parameters or flags need to be passed to the parser when the command is run. To disable TOC files, add the following parameter: -disableToc

Accessible output

We have worked to output all Markdown markup to standard and valid HTML5 tags:

Alt text for images: Included as part of the Markdown tagging for images
Header row in tables: Output turns the first row into <thead>
Elements having a WAI-ARIA 'article' role must have a label specified with aria-label or aria-labelledby.
Use header elements where appropriate: Pass thru HTML tagging when Markdown markup is not available, for example definition lists (dl, dt, dd)
There must be a non-empty title element in the head of the document: For the HTML output from Markdown, the <head> element does not contain a <title> element. We added this with a header file.

Additional accessibility might be needed as content is migrated to Markdown. And, as a result, updates to the parser and/or to the markup recommendations might be required.

Additional functionality

Copy of non-.md files: Copies (doesn't process) image files (.bmp, .jpg, .png, .gif, .SVG)
Recurse sub-directories: Processes all directories in the specified source directory
Overwrite: Addition of an overwrite flag to replace previous output

Tips for avoiding common errors

Using HTML within your Markdown topics is allowed, and in some cases encouraged (the only way to output a definition list is by using HTML). However, if you chose to use HTML, always ensure your HTML is well-formed. Any tag that does not have a closing tag associated with it will break the parser, and your build will fail. For example, the only way that you can create a line break inside a table cell in Markdown is to use a break tag, however, using <br> will actually break the build. You must close the break tag like so: <br/>. If you use HTML, carefully validate that your tags are matching and that you close all open tags.
Avoid using < and >. For all special characters, it is recommended that you use the & value. For example, for > use >. All of the following special characters are also supported: (http://www.w3.org/MarkUp/HTMLPlus/htmlplus_13.html)

Tips for debugging Markdown parser errors:

Search for mal-formed HTML or special characters.
Run a local version of the parser, and copy text into a parallel .md document in small chunks. Rebuild each time until you find the offending key.
We did see an issue where someone used a non-standard editor to produce markdown, and there were hidden mal-formed characters.

leinine / docs-cl