docs-services

IBM Bluemix Service 3rd party service docs

The docs-services repo is for the product content for IBM Bluemix that is authored in Markdown. The Bluemix doc app builds all 3rd party service Markdown source from this location for all regions.

Each directory in this repo must synch with the overall architecture of the Bluemix doc app.

I am a 3rd party service provider, and I want to create a new service for Bluemix:

Register at https://github.com/
Send the following information to [email protected] (and copy [email protected])

Your GitHub ID, and any team member GitHub IDs that will need access to the docs repo
The Name of your service

You will receive a response within one working day (24 hrs) which will include:

The GitHub URL to your directory, a subfolder under /service, where you can create your files
Details on how to create your content in MarkDown

Under your /service subfolder, add your Getting Started MarkDown source by following the template, getting_started_template.md.
Under your /services subfolder, add your TOC file (lowercased toc, no file extension).
After you have created your Markdown files and you are ready to see it live in the Bluemix doc framework, send another note to to [email protected] (and copy [email protected]), asking for a build.
You will receive a response within one working day (24 hours) pointing you to a production preview URL where you can verify your content before it goes live. Please respond ASAP, telling the Bluemix ID contact to either push content live, or to hold off until further changes.
Your content will go live, or you will iterate through additional emails until it does.

Getting started template

The getting started template and guidelines are provided as a way to consistently represent service documentation within the Bluemix platform. The product documentation provided for a service should enable a user to quickly get up and running. Supplemental information should be task-based and support the productive use of the service.

Important: For IBM Bluemix Service 3rd party service docs, you are only required to have a Getting started with service_name topic (getting_started_template/index.md). You can link off to your full documentation from the related links.

Using the Copyright and Last Updated header (Required)

Both the span of years your content has been published across, and the last date that you updated your content must be included within YAML at the top of your file, as shown in the following example:

---

copyright:

  years: 2017

lastupdated: "2017-02-10"

---

The copyright and lastupdated information is YAML content that must occur at the top of the MD file, before attributes are listed.

It must be --- surrounded by 3 dashes ---
The value "years" can contain just one year or a two years separated by a comma. (years: 2014, 2016)
The value "lastupdated" must be followed by a machine date in quotes in the following format: "YYYY-MM-DD"
The value for "years" must be indented 2 spaces under "copyright", followed by "lastupdated" which should start on its own non-indented line.
Ensure that each time you update your Markdown topic, you also update the "lastupdated" date.

The getting started steps should include information on how to integrate the service into the app or use the service outside of Bluemix. They don't include steps to add the service from the Catalog; we should assume the user is starting at the service dashboard.

With task-based, technical information, reduce the conversational style in favor of succinct and direct instructions.
Include the basic, most-common-use scenario steps to use the service or integrate it into the app. (Document edge cases in blogs as examples…if they start to become more common, move them into the docs flow as child task flows)
Include code snippets in all programming languages that can be copied, as well as VCAP service info.

For additional tasks to use the service (after the getting started), create separately chunked groups of task topics. Example containers would be "Configuring x", "Administering y", "Creating z".

Troubleshooting information would then be the last section in the flow, including specific troubleshooting topics and error messages.

Example Outline:

Getting started (index.md)
About (about.md)
Configuring x (configuring.md)
child topics
Administering y (administering.md)
child topics
Creating z (creating.md)
child topics
Troubleshooting (troubleshooting.md)
child topics

Creating a table of contents (TOC) for your service catalog entry

To begin, you need to create a TOC map file in GitHub. This file must be in the root directory of your service. See the sample TOC in this (docs-services) folder. You can copy it into the root directory of your service and edit it from there.

Important note: The toc file has no extension. It is just named toc.

The following toc file would create the structure for the previous Example Outline:

{:navgroup: .navgroup}
{:topicgroup: .topicgroup}

{: .toc subcollection="FolderName" audience="service" href="/docs/services/FolderName/index.html"}
Name of service

    {: .navgroup id="learn"}
    index.md
        about.md
        configuring.md
        administering.md
        creating.md
        troubleshooting.md

    {: .topicgroup}
    Related links
        [Link text](URL)
        [Link text](URL)
    {: .navgroup-end}

    {: .navgroup id="reference"}
    Reference
    [API Documentation](URL)
    {: .navgroup-end}

Note: Nesting files is as simple as indenting 4 spaces. You can nest multiple levels of files, as shown in the previous example.

After you have your toc file created in GitHub, the Bluemix doc build picks this file up and generates your table of contents.

Adding external links to your TOC file

Notice that in the example above there is an html value, rather than a markdown value, for the first instance of the Getting Started topic. In most cases you can just add duplicate index.md entries, but because this Getting Started example has several subheaders that we want to generate TOC values for, creating a pre-defined custom html url was a way to create the top-level container without displaying all the nested sub-headers beneath it:

[Getting Started with <Name_of_Service>](docs/<folder_name>/index.html)

You can use this same standard markdown code used to specify a URL at any time in your toc map file to create an internal or external link. For example if I wanted to add a TOC entry for an API in API explorer, I could add: REST API to my toc map file in the appropriate place.

Tip: Keep in mind that the search results are generated from your TOC. (A search is generated from the TOC JSON file.) One of the ways you can improve SEO is to ensure that your TOC contains the critical topics you want your customers to find.

Excluding unwanted headers

You might not want every single header in your markdown topic or topics to be rendered as part of your TOC. To exclude a header, simply add the notoc attribute to the header you to exclude in your md file, as shown in the following example:

# Header I want to exclude
{: #xreftext notoc}

## Another header nested underneath
{: #api}

Note: In the previous example, the notoc attribute is only on the H1 header. The notoc attribute cascades down and excludes any sub-headers nested beneath the header you specify to exclude. You can add the notoc attribute to any header at any depth; H1, H2, H3, etc…

Sample Applications

We recommend that all 3rd party services provide sample apps for customers to use. Include links in your documentation that point to these sample apps.

Note: At a minimum, please provide your sample apps in Node and Java.

Authoring Bluemix content in Markdown

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.

How to suggest changes or updates to Bluemix documentation

All you need is a GitHub ID, and you can suggest edits and changes to Bluemix docs. A Bluemix team member will review any pull requests, and merge all or parts of your suggested changes as quickly as possible. To make your changes:

Fork the project or create a branch right from the repository.
Edit files.
When your changes are complete, send a pull request from your branch with your changes.
Wait for a Bluemix team member to review your changes and merge all or parts of your suggested changes
After you are notified of your changes, tidy up your branches using the delete button in the pull request or on the branches page.

For more detailed information on how to contribute content to Bluemix documentation, see https://developer.ibm.com/bluemix/2016/01/13/bluemix-docs-now-open-source-on-github/. Also see the following help from GitHub: https://help.github.com/articles/github-flow-in-the-browser/

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.

#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>` `<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.ng.bluemix.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.ng.bluemix.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.

####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}}

####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}} is actually a conref! I can use {{site.data.keyword.bluemix}} multiple times in a paragraph. 
	* I can use the full product name: {{site.data.keyword.bluemix}}
	* 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: IBM® Bluemix™ is actually a conref! I can use IBM® Bluemix™ multiple times in a paragraph.

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

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) and other file extensions like .html, .pdf, .json, .js
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)

Name		Name	Last commit message	Last commit date
Latest commit History 1,007 Commits
InsightsForOpenData		InsightsForOpenData
flowthings		flowthings
getting_started_template		getting_started_template
paypal		paypal
services		services
README.md		README.md
toc		toc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

docs-services

I am a 3rd party service provider, and I want to create a new service for Bluemix:

Getting started template

Using the Copyright and Last Updated header (Required)

Creating a table of contents (TOC) for your service catalog entry

Adding external links to your TOC file

Excluding unwanted headers

Sample Applications

Authoring Bluemix content in Markdown

How to suggest changes or updates to Bluemix documentation

Markdown Editors

Bluemix special mappings for how to code in DITA vs Markdown

Bluemix Extensions

Attributes

Headers and footers

Content References

TOC File

Accessible output

Additional functionality

Tips for avoiding common errors

About

Releases

Packages

pkamp3/docs-services

Folders and files

Latest commit

History

Repository files navigation

docs-services

I am a 3rd party service provider, and I want to create a new service for Bluemix:

Getting started template

Using the Copyright and Last Updated header (Required)

Creating a table of contents (TOC) for your service catalog entry

Adding external links to your TOC file

Excluding unwanted headers

Sample Applications

Authoring Bluemix content in Markdown

How to suggest changes or updates to Bluemix documentation

Markdown Editors

Bluemix special mappings for how to code in DITA vs Markdown

Bluemix Extensions

Attributes

Headers and footers

Content References

TOC File

Accessible output

Additional functionality

Tips for avoiding common errors

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Packages