Markdown
There is explained some nice features that can be used in the markdown files. Github markdown
Using icons 👍 👏 👏
Icons can be used in the markdown files. This will give a more friendly appearance to the documentation 😃 Here is a link icons that can be used:
Markdown Components
Added the first of several markdown components. Markdown components are NHN-specific components that can be rendred in any markdown document using a pre-defined syntax. First macro component is linkbox, these can be rendered in singles (stacked vertically) or in a grid (2 per row).
Markdown components are created using simple HTML syntax, the following components are currently available:
Linkbox grid
Link boxes can be rendered as grid (2 boxes per row) or stacked vertically. Link boxes are added using the following syntax: Syntax Example:
<mdlinkboxgrid title="Linkbox grid!">
<mdlinkbox url="https://www.google.com" title="Linkbox 1!" description="description here!" newtab="true"></mdlinkbox>
<mdlinkbox url="https://www.google.com" title="Linkbox 2!" description="description here!" newtab="false"></mdlinkbox>
<mdlinkbox url="https://www.google.com" title="Linkbox 3!" description="description here!" newtab="true"></mdlinkbox>
<mdlinkboxgrid>
Linkbox grid - renders linkboxes in rows of 2 items per row
Required fields: [url, title (not required on grid element)]
Linkboxes - vertical
Link boxes can also be stacked vertically by forgoing the wrapping
Single linkboxes, will be stacked vertically
<mdlinkbox url="https://www.google.com" title="Linkbox 1!" description="description here!" newtab="true"></mdlinkbox>
<mdlinkbox url="https://www.google.com" title="Linkbox 2!" description="description here!" newtab="false"></mdlinkbox>
Required fields: [url, title]
This example will render link boxes in a grid as shown below:
Link button
Second macro component is link button. Like linkboxes these can be rendered in multiple ways, either stacked vertically or horizontally. Unlike linkboxes there are no limits to how many buttons can exist on one row.
Syntax example:
Stacking linkboxes horizontally
<mdlinkbutton url="https://www.vg.no" title="Single macro link button 1" newtab="true" single="false"></mdlinkbutton>
<mdlinkbutton url="https://www.vg.no" title="Single macro link button 2" newtab="false" single="false"></mdlinkbutton>
Required fields: [url, title]
This example will render linkbuttons and stack these horizontally as shown in the example below:
Stacking linkboxes vertically only requires setting the "single" value to true
<mdlinkbutton url="https://www.vg.no" title="Single macro link button 1" newtab="true" single="true"></mdlinkbutton>
<mdlinkbutton url="https://www.vg.no" title="Single macro link button 2" newtab="false" single="true"></mdlinkbutton>
Required fields: [url, title]
This example will render linkbuttons and stack these vertically as shown in the example below:
Dropdown
Dropdowns can be used to visualize content that would fit into a regular list in order to add a more visual and interactive interface for the end user. In cases where lists would contain a lot of content, dropdowns can be used to save space and let users located relevant paragraphs a lot quicker.
Create a single or multiple dropdowns with the following syntax:
<mddropdown title="Macro dropdown 1" content="This is a dropdown macro component!"></mddropdown>
<mddropdown title="Macro dropdown 2" content="This is once again a dropdown macro component!"></mddropdown>
Required fields: [title, content]
This example will render two dropdowns and stack these vertically as shown in the example below:
There are no limits to how many dropdowns can be added in a single markdown document.
Grouped code samples
The developer portal supports multi-language code samples. When your APIs support a multitude of different code languages it might come in handy to be able to group these up into tabs where the user can view your code samples in the language they require. This will reduce the length and clutter of your markdown documents, and the dev portal now supports this!
We use a functionally extended markdown parser to build these components, as such just as with our other markdown components, there is unfortunately no way to make these appear in a preview window in your markdown editor. You will however see the results when your docs are synced into the dev portal!
Using the following syntax you will be able to create a grouped code sample where every code language will receive its own tab based on the code language set at the beginning of the sample:
<mdcodesamples>
```json <-- LANGUAGE MUST BE SPECIFIED
{
"property 1": "true",
"property 2": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"property 3": "250"
}
```
```javascript
function testFunction(){
console.log('this is a test function');
}
```
```csharp
public class TestClass{
public string Name {get; set;}
public int Age {get; set;}
public bool IsHappy {get; set;}
}
```
</mdcodesamples>
NOTE: the empty lines between <mdcodesamples> and the rest of the content is required in order for the markdown parser to work properly.
An empty line is also required before </mdcodesamples>. Another important rule is that code language (or name) needs to be provided for each sample as seen in the example above. We reccomend using code language, as we will at some point implement syntax highlighting for any recognized code language.
When executed correctly, the code above will be parsed into a tab-grouped code sample as seen below:
{
"property 1": "true",
"property 2": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"property 3": "250"
}
function testFunction(){
console.log('this is a test function');
}
public class TestClass{
public string Name {get; set;}
public int Age {get; set;}
public bool IsHappy {get; set;}
}
That covers how you can group your code samples up into tabs, helping you reduce the length of your markdown documents.
We hope you find these custom markdown components handy in building your documentation!
These are the components available in markdown documents for now, more will be added if and when we see a need to do so. If you have any ideas or requirements in that direction, feel free to contact us!