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.
- 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.
- 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.
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:
1. Fork the project or create a branch right from the repository.
2. Edit files.
3. When your changes are complete, send a pull request from your branch with your changes.
4. Wait for a Bluemix team member to review your changes and merge all or parts of your suggested changes
5. 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/
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.
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
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.
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:
- https://help.github.com/articles/markdown-basics/
- https://help.github.com/articles/github-flavored-markdown/
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.
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 Switchingdata-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 Datauser'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: {:?: .?} |
? |
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
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>
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).
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® Bluemix™
bluemix_short:
Bluemix™
IBM:
IBM®
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
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 outputindexTOC.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.HTMLindexTOC.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.HTMLindex.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
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.
- 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
- 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)